exstreamspeed Reference/es_mbc

Reference/es_mbc_addfldmbu

Syntax

int es_mbc_addfldmbu( struct es_mbc *cls, const char *fieldnm, struct es_mbu *cb );

Arguments

`struct es_mbc *cls`	A database class.
`const char *fieldnm`	Field name.
`struct es_mbu *cb`	Save, load and delete callbacks for user-defined field.

Return Codes

`ES_ERROR_NONE`	Success. No errors.
`ES_ERROR_UNKNOWNFIELD`	Field name does not exist in class definition.
`ES_ERROR_INVALIDFIELDTYPE`	Field is not of type `ES_FLDTYPE_MBU`.

Description

es_mbc_addfldmbu defines the save, load and delete callback functions for a user-defined field (of type ES_FLDTYPE_MBU) previously defined via es_mbc_addfld().

/* callback invoked as part of es_mb_save() */
typedef int (*es_mbu_save_t)( void *obj, void *udata, struct es_mbio *io );

/* callback invoked as part of es_mb_load() */
typedef int (*es_mbu_load_t)( void **objres, void *udata, struct es_mbio *io );

/* callback invoked as part of es_mb_delete */
typedef void (*es_mbu_delete_t)( void *obj, void *udata );

/* user-type callback interface */
struct es_mbu
{
  void           *udata;  /* user-data passed as parameter to callback functions */
  es_mbu_save_t   savefn; /* save callback function called as part of es_mb_save */
  es_mbu_load_t   loadfn; /* load callback function called as part of es_mb_load */
  es_mbu_delete_t delfn;  /* delete callback called as part of es_mbn_delete */
};

savefn is invoked by es_mb_save() and is passed a field value (void *obj) and pointer to static user data ( void *udata ). obj may be passed as NULL. savefn must return ES_ERROR_NONE on success and ES_ERROR_FAILTOSAVE on error.

loadfn is invoked by es_mb_load() and is passed a pointer to a field value by reference (void **objres). *objres must be assigned a field value or NULL. loadfn must return ES_ERROR_NONE on success and ES_ERROR_FAILTOLOAD on error.

Both savefn and loadfn are passed a struct es_mbio* (a pass-through from es_mb_save() or es_mb_load() ) with which to write or read data from the binary stream using the writefn and readfn function pointers respectively.

/* read/write function prototype */
typedef int (*es_mb_io_t)( void *fndata, void *buf, unsigned numbytes );

/* handle for read/write functions and state-data */
struct es_mbio
{
  void      *fndata;  /* user-specific data */
  es_mb_io_t writefn; /* write (serialize) function */
  es_mb_io_t readfn;  /* read (deserialize) function */
};

The delete function delfn is invoked by es_mbn_delete() for each field value (void *obj) in a database node and is meant to destory a user-defined field and free-up resources. obj is guaranteed to be not NULL.

Please note that duplicate user-defined fields are not recognised by es_mb_save(), es_mb_load() or es_mbn_delete() and must be managed by the supplied callback functions.

Please note also that user-defined callback functions are not saved as part of database definition save via es_mbd_save().

[Back To Reference] [Back To Reference/es_mbc]