labcomm.h

#ifndef _LABCOMM_H_
#define _LABCOMM_H_

#include <stdarg.h>
#include <unistd.h>

/* Forward declaration */
struct labcomm_encoder;
struct labcomm_decoder;

/*
 * Signature entry
 */
typedef struct labcomm_signature {
  int type;
  char *name;
  int (*encoded_size)(struct labcomm_signature *, void *); // void * == encoded_sample *
  int size;
  unsigned char *signature; 
  int cached_encoded_size; // -1 if not initialized or type is variable size
} labcomm_signature_t;

/*
 * Error handling.
 */

/* Error IDs */
enum labcomm_error {
  LABCOMM_ERROR_ENUM_BEGIN_GUARD,	// _must_ be the first enum element. labcomm_error_get_str() depends on this.
  LABCOMM_ERROR_ENC_NO_REG_SIGNATURE, 	
  LABCOMM_ERROR_ENC_MISSING_DO_REG,
  LABCOMM_ERROR_ENC_MISSING_DO_ENCODE,
  LABCOMM_ERROR_ENC_BUF_FULL,
  LABCOMM_ERROR_DEC_MISSING_DO_REG,
  LABCOMM_ERROR_DEC_MISSING_DO_DECODE_ONE,
  LABCOMM_ERROR_DEC_UNKNOWN_DATATYPE,
  LABCOMM_ERROR_DEC_INDEX_MISMATCH,
  LABCOMM_ERROR_DEC_TYPE_NOT_FOUND,
  LABCOMM_ERROR_UNIMPLEMENTED_FUNC,
  LABCOMM_ERROR_MEMORY,
  LABCOMM_ERROR_USER_DEF,			
  LABCOMM_ERROR_ENUM_END_GUARD		// _must_ be the last enum element. labcomm_error_get_str() depends on this.
};

/* Error strings. _must_ be the same order as in enum labcomm_error */
extern const char *labcomm_error_strings[];

/* The callback prototype for error handling.
 * First parameter is the error ID.
 * The second paramters is the number of va_args that comes after this 
 * one. If none it should be 0.
 * Optionaly other paramters can be supplied depending on what is needed 
 * for this error ID.
 */
typedef void (*labcomm_error_handler_callback)(enum labcomm_error error_id, 
					       size_t nbr_va_args, ...); 

/* Default error handler, prints message to stderr. 
 * Extra info about the error can be supplied as char* as VA-args. Especially user defined errors should supply a describing string. if nbr_va_args > 1 the first variable argument must be a printf format string and the possibly following arguments are passed as va_args to vprintf. 
 */
void on_error_fprintf(enum labcomm_error error_id, size_t nbr_va_args, ...);

/* Register a callback for the error handler for this encoder. */
void labcomm_register_error_handler_encoder(struct labcomm_encoder *encoder, labcomm_error_handler_callback callback);

/* Register a callback for the error handler for this decoder. */
void labcomm_register_error_handler_decoder(struct labcomm_decoder *decoder, labcomm_error_handler_callback callback);

/* Get a string describing the supplied standrad labcomm error. */
const char *labcomm_error_get_str(enum labcomm_error error_id);

typedef int (*labcomm_handle_new_datatype_callback)(
  struct labcomm_decoder *decoder,
  labcomm_signature_t *sig);

void labcomm_decoder_register_new_datatype_handler(struct labcomm_decoder *d,
		labcomm_handle_new_datatype_callback on_new_datatype);

/*
 * Locking support (optional)
 */

struct labcomm_lock_action {
  int (*alloc)(void *context);
  int (*free)(void *context);
  int (*read_lock)(void *context);
  int (*read_unlock)(void *context);
  int (*write_lock)(void *context);
  int (*write_unlock)(void *context);
};

/*
 * Decoder
 */

struct labcomm_reader;

struct labcomm_reader_action {
  int (*alloc)(struct labcomm_reader *r, char *labcomm_version);
  int (*free)(struct labcomm_reader *r);
  int (*start)(struct labcomm_reader *r);
  int (*end)(struct labcomm_reader *r);
  int (*fill)(struct labcomm_reader *r); 
  int (*ioctl)(struct labcomm_reader *r, int, labcomm_signature_t *, va_list);
};

typedef struct labcomm_reader {
  void *context;
  unsigned char *data;
  int data_size;
  int count;
  int pos;
  int error;
  struct labcomm_reader_action action;
  labcomm_error_handler_callback on_error;
}  labcomm_reader_t;

struct labcomm_decoder *labcomm_decoder_new(
  const struct labcomm_reader_action reader,
  void *reader_context,
  const struct labcomm_lock_action *lock,
  void *lock_context);
int labcomm_decoder_decode_one(
  struct labcomm_decoder *decoder);
void labcomm_decoder_run(
  struct labcomm_decoder *decoder);
void labcomm_decoder_free(
  struct labcomm_decoder *decoder);

/* See labcomm_ioctl.h for predefined ioctl_action values */
int labcomm_decoder_ioctl(struct labcomm_decoder *decoder, 
			  int ioctl_action,
			  ...);

/*
 * Encoder
 */
struct labcomm_writer;

struct labcomm_writer_action {
  int (*alloc)(struct labcomm_writer *w, char *labcomm_version);
  int (*free)(struct labcomm_writer *w);
  int (*start)(struct labcomm_writer *w,
	       struct labcomm_encoder *encoder,
	       int index,
	       labcomm_signature_t *signature,
	       void *value);
  int (*end)(struct labcomm_writer *w);
  int (*flush)(struct labcomm_writer *w); 
  int (*ioctl)(struct labcomm_writer *w, int, labcomm_signature_t *, va_list);
};

typedef struct labcomm_writer {
  void *context;
  unsigned char *data;
  int data_size;
  int count;
  int pos;
  int error;
  struct labcomm_writer_action action;
  labcomm_error_handler_callback on_error;
} labcomm_writer_t;

struct labcomm_encoder *labcomm_encoder_new(
  const struct labcomm_writer_action writer,
  void *writer_context,
  const struct labcomm_lock_action *lock,
  void *lock_context);
void labcomm_encoder_free(
  struct labcomm_encoder *encoder);

/* See labcomm_ioctl.h for predefined ioctl_action values */
int labcomm_encoder_ioctl(struct labcomm_encoder *encoder, 
			  int ioctl_action,
			  ...);

#endif