DexterPluginISampler

typedef struct _DexterPluginISampler DexterPluginISampler;

Dummy object for the DexterPluginISampler interface.

struct DexterPluginISamplerInterface

struct DexterPluginISamplerInterface {
  gboolean (*initialize)        (DexterPluginISampler  *isampler,
                                 const gint            *param,
                                 gconstpointer          input,
                                 GError               **error); 

  gboolean (*sample)            (DexterPluginISampler  *isampler,
                                 GError               **error);

  gpointer (*data_new)          (DexterPluginISampler  *isampler,
                                 gboolean               populate);
    
  gpointer (*data_dup)          (DexterPluginISampler  *isampler,
                                 gconstpointer          source_data);

  void     (*data_xfer)         (DexterPluginISampler  *isampler,
                                 gpointer               old_data,
                                 gconstpointer          new_data);
    
  void     (*data_copy)         (DexterPluginISampler  *isampler,
                                 gpointer               dest_data,
                                 gconstpointer          source_data);
    
  void     (*data_free)         (DexterPluginISampler  *isampler,
                                 gpointer               data);

  gboolean (*data_serialize)    (DexterPluginISampler  *isampler,
                                 GString               *dest_buffer,
                                 gconstpointer          source_data,
                                 GError               **error);

  gpointer (*data_deserialize)  (DexterPluginISampler  *isampler,
                                 const GString         *source_buffer,
                                 GError               **error);
                
  gpointer (*input_new)         (DexterPluginISampler  *isampler);

  void     (*input_free)        (DexterPluginISampler  *isampler,
                                 gpointer               input);

  gboolean (*input_serialize)   (DexterPluginISampler  *isampler,
                                 GString               *dest_buffer,
                                 gconstpointer          source_input,
                                 GError               **error);

  gpointer (*input_deserialize) (DexterPluginISampler  *isampler,
                                 const GString         *source_buffer,
                                 GError               **error);
};

The definition of the DexterPluginISamplerInterface.

dexterplugin_isampler_initialize ()

gboolean            dexterplugin_isampler_initialize    (DexterPluginISampler *isampler,
                                                         const gint *param,
                                                         gconstpointer input,
                                                         GError **error);

Perform one-time initialization of a sampler using supplied parameter and/or input. The param integer is a "free" parameter for plugin writers in the sense that no serialization code need be written for it. The input pointer is meant for any additional, structured or otherwise complex initialization data that the sampler might need. Plugin writers must write serialization code for this parameter.

If the sampler requires no param or input for initialization, NULL should be specified.

After a sampler is created, it must be initialized once, and only once, using this function.

The optional error parameter can be used to return errors to the caller, e.g. a GLib error, or an error you describe using the DEXTERPLUGIN_SAMPLER_ERROR_FAILED error code from the DEXTERPLUGIN_SAMPLER_ERROR error domain.

dexterplugin_isampler_sample ()

gboolean            dexterplugin_isampler_sample        (DexterPluginISampler *isampler,
                                                         GError **error);

Perform the sampling operation implemented by this sampler service. Samplers must store the sample data internally so that the data may be exchanged with the user using the data api's described below.

The optional error parameter can be used to return errors to the caller, e.g. a GLib error, or an error you describe using the DEXTERPLUGIN_SAMPLER_ERROR_FAILED error code from the DEXTERPLUGIN_SAMPLER_ERROR error domain.

dexterplugin_isampler_data_new ()

gpointer            dexterplugin_isampler_data_new      (DexterPluginISampler *isampler,
                                                         gboolean populate);

The sampler should return a newly allocated sample data structure, as defined by the service implementation. If populate is TRUE, the data structure should be populated with the sampler's current sample data. If FALSE, the structure should be zero-filled.

The sample structure should be freed when done with dexterplugin_isampler_data_free().

dexterplugin_isampler_data_dup ()

gpointer            dexterplugin_isampler_data_dup      (DexterPluginISampler *isampler,
                                                         gconstpointer source_data);

The sampler should duplicate the provided sample data structure, i.e. return a newly allocated (deep) copy of the structure.

The sample structure should be freed when done with dexterplugin_isampler_data_free().

dexterplugin_isampler_data_xfer ()

void                dexterplugin_isampler_data_xfer     (DexterPluginISampler *isampler,
                                                         gpointer old_data,
                                                         gconstpointer new_data);

The sampler should first (deep) copy its current, internal sample data to the old_data structure, if specified. Then, the sampler should replace its internal sample data with a (deep) copy of the new_data structure, if specified. Implementors must free any existing heap-allocated data on the copy targets before performing the copies, so as not to leak memory.

Note that it would be highly unusual for most users to change the internal data of a sampler explicitly by specifying a new_data parameter. Libdexter uses that feature internally when deserializing data transmitted over the network. The preferred way to update the sampler's internal sample data is simply to take a sample, i.e. to use dexterplugin_isampler_sample().

dexterplugin_isampler_data_copy ()

void                dexterplugin_isampler_data_copy     (DexterPluginISampler *isampler,
                                                         gpointer dest_data,
                                                         gconstpointer source_data);

The sampler should (deep) copy the source sample data onto the destination structure, first freeing any heap-allocated data on the destination structure so as not to leak memory.

dexterplugin_isampler_data_free ()

void                dexterplugin_isampler_data_free     (DexterPluginISampler *isampler,
                                                         gpointer data);

The sampler should free the indicated sampler data.

dexterplugin_isampler_data_serialize ()

gboolean            dexterplugin_isampler_data_serialize
                                                        (DexterPluginISampler *isampler,
                                                         GString *dest_buffer,
                                                         gconstpointer source_data,
                                                         GError **error);

The sampler should serialize the source sample data structure to the destination buffer.

The optional error parameter can be used to return errors to the caller, e.g. a GLib error, or an error you describe using the DEXTERPLUGIN_SAMPLER_ERROR_FAILED error code from the DEXTERPLUGIN_SAMPLER_ERROR error domain.

Libdexter uses these serialization functions to transmit sampler data over the network via Channels. The format you use to serialize the sampler data is completely up to you. You may perhaps choose to implement several services that each do the same thing but that serialize data differently, e.g. plain text, binary, XML, etc.

GString is used as the destination buffer since it conveniently implements a growable buffer and thus helps to avoid buffer overflow issues. GString's can also contain binary data, embedded nulls, etc. See g_string_new_len().

dexterplugin_isampler_data_deserialize ()

gpointer            dexterplugin_isampler_data_deserialize
                                                        (DexterPluginISampler *isampler,
                                                         const GString *source_buffer,
                                                         GError **error);

The sampler should deserialize the indicated GString buffer of encoded sampler data, allocate and return a data structure containing the deserialized data.

The optional error parameter can be used to return errors to the caller, e.g. a GLib error, or an error you describe using the DEXTERPLUGIN_SAMPLER_ERROR_FAILED error code from the DEXTERPLUGIN_SAMPLER_ERROR error domain.

The sample structure should be freed when done with dexterplugin_isampler_data_free().

dexterplugin_isampler_input_new ()

gpointer            dexterplugin_isampler_input_new     (DexterPluginISampler *isampler);

The sampler should allocate and return a zero-filled input data structure, or NULL if no such input structure is defined for the sampler service.

The input structure should be freed when done with dexterplugin_isampler_input_free().

dexterplugin_isampler_input_free ()

void                dexterplugin_isampler_input_free    (DexterPluginISampler *isampler,
                                                         gpointer input);

The sampler should free the indicated input structure.

dexterplugin_isampler_input_serialize ()

gboolean            dexterplugin_isampler_input_serialize
                                                        (DexterPluginISampler *isampler,
                                                         GString *dest_buffer,
                                                         gconstpointer source_input,
                                                         GError **error);

If the sampler requires input data during dexterplugin_isampler_initialize(), the input data must be serialized for transmission over the network when the sampler is operating over a Libdexter Channel.

The sampler should serialize the input data structure to the destination buffer.

The optional error parameter can be used to return errors to the caller, e.g. a GLib error, or an error you describe using the DEXTERPLUGIN_SAMPLER_ERROR_FAILED error code from the DEXTERPLUGIN_SAMPLER_ERROR error domain.

dexterplugin_isampler_input_deserialize ()

gpointer            dexterplugin_isampler_input_deserialize
                                                        (DexterPluginISampler *isampler,
                                                         const GString *source_buffer,
                                                         GError **error);

The sampler should deserialize the indicated GString buffer of encoded input data, allocate and return an input structure containing the deserialized data.

The optional error parameter can be used to return errors to the caller, e.g. a GLib error, or an error you describe using the DEXTERPLUGIN_SAMPLER_ERROR_FAILED error code from the DEXTERPLUGIN_SAMPLER_ERROR error domain.

The input structure should be freed when done with dexterplugin_isampler_input_free().