IpatchConverter

IpatchConverter — Object conversion system.

Synopsis




                    IpatchConverter;
                    IpatchConverterClass;
enum                IpatchConverterLogType;
#define             IPATCH_CONVERTER_LOG_TYPE_MASK
#define             IPATCH_CONVERTER_LOG_MSG_ALLOC
enum                IpatchConverterFindFlags;
#define             IPATCH_CONVERTER_INPUT              (converter)
#define             IPATCH_CONVERTER_OUTPUT             (converter)
void                ipatch_register_converter           (GType conv_type,
                                                         GType src_type,
                                                         int src_count,
                                                         GType dest_type,
                                                         int dest_count);
GType               ipatch_find_converter               (GType src_type,
                                                         GType dest_type,
                                                         IpatchConverterFindFlags src_flags,
                                                         IpatchConverterFindFlags dest_flags);
gboolean            ipatch_lookup_converter_info        (GType converter_type,
                                                         GType *src_type,
                                                         int *src_count,
                                                         GType *dest_type,
                                                         int *dest_count);
IpatchConverter*    ipatch_create_converter             (GType src_type,
                                                         GType dest_type,
                                                         IpatchConverterFindFlags src_flags,
                                                         IpatchConverterFindFlags dest_flags);
GType*              ipatch_get_conversion_table         (void);
GType*              ipatch_get_conversion_dest_types    (GType src_type);
GType*              ipatch_get_conversion_src_types     (GType dest_type);
void                ipatch_converter_add_input          (IpatchConverter *converter,
                                                         GObject *object);
void                ipatch_converter_add_output         (IpatchConverter *converter,
                                                         GObject *object);
void                ipatch_converter_add_inputs         (IpatchConverter *converter,
                                                         GList *objects);
void                ipatch_converter_add_outputs        (IpatchConverter *converter,
                                                         GList *objects);
GObject*            ipatch_converter_ref_input          (IpatchConverter *converter);
GObject*            ipatch_converter_ref_output         (IpatchConverter *converter);
IpatchList*         ipatch_converter_ref_inputs         (IpatchConverter *converter);
IpatchList*         ipatch_converter_ref_outputs        (IpatchConverter *converter);
gboolean            ipatch_converter_verify             (IpatchConverter *converter,
                                                         char **failmsg);
void                ipatch_converter_init               (IpatchConverter *converter);
gboolean            ipatch_converter_convert            (IpatchConverter *converter,
                                                         GError **err);
void                ipatch_converter_reset              (IpatchConverter *converter);
char*               ipatch_converter_get_notes          (IpatchConverter *converter);
void                ipatch_converter_log                (IpatchConverter *converter,
                                                         GObject *item,
                                                         int type,
                                                         char *msg);
gboolean            ipatch_converter_log_next           (IpatchConverter *converter,
                                                         gpointer *pos,
                                                         GObject **item,
                                                         int *type,
                                                         char **msg);

Object Hierarchy


  GObject
   +----IpatchConverter
         +----IpatchCramDecoderConverter
         +----IpatchCramEncoderConverter

Properties


  "progress"                 gfloat                : Read / Write

Description

The IpatchConverter system provides an interface for converting between different object types. This interface will be the primary method of converting between different patch objects and even loading files into objects and saving objects into files.

Details

IpatchConverter

typedef struct _IpatchConverter IpatchConverter;


IpatchConverterClass

typedef struct {
  GObjectClass parent_class;

  /* methods */
  gboolean (*verify)(IpatchConverter *converter, char **failmsg);
  void (*init)(IpatchConverter *converter);
  gboolean (*convert)(IpatchConverter *converter, GError **err);
  char * (*notes)(IpatchConverter *converter);
} IpatchConverterClass;


enum IpatchConverterLogType

typedef enum
{
  IPATCH_CONVERTER_LOG_RATING,	/* log a rating update */
  IPATCH_CONVERTER_LOG_INFO,	/* informational only */
  IPATCH_CONVERTER_LOG_WARN,	/* warning */
  IPATCH_CONVERTER_LOG_CRITICAL, /* critical (but non fatal) message */
  IPATCH_CONVERTER_LOG_FATAL	/* fatal error */
} IpatchConverterLogType;


IPATCH_CONVERTER_LOG_TYPE_MASK

#define IPATCH_CONVERTER_LOG_TYPE_MASK   0x0F


IPATCH_CONVERTER_LOG_MSG_ALLOC

#define IPATCH_CONVERTER_LOG_MSG_ALLOC 0x80


enum IpatchConverterFindFlags

typedef enum /*< flags >*/
{
  IPATCH_CONVERTER_FIND_PARENT = 1 << 0, /* match parent types also */
  IPATCH_CONVERTER_FIND_CHILD  = 1 << 1	/* match child types also */
} IpatchConverterFindFlags;


IPATCH_CONVERTER_INPUT()

#define             IPATCH_CONVERTER_INPUT(converter)

converter :

IPATCH_CONVERTER_OUTPUT()

#define             IPATCH_CONVERTER_OUTPUT(converter)

converter :

ipatch_register_converter ()

void                ipatch_register_converter           (GType conv_type,
                                                         GType src_type,
                                                         int src_count,
                                                         GType dest_type,
                                                         int dest_count);

Registers a IpatchConverter handler to convert objects of src_type to dest_type.

conv_type : IpatchConverter derived GType of conversion handler
src_type : GObject derived GType of source
src_count : Count of expected source objects (-1 for unlimited, -2 for unlimited but can be none)
dest_type : GObject derived GType of destination
dest_count : Count of expected destination objects (-1 for unlimited, -2 for unlimited but can be none)

ipatch_find_converter ()

GType               ipatch_find_converter               (GType src_type,
                                                         GType dest_type,
                                                         IpatchConverterFindFlags src_flags,
                                                         IpatchConverterFindFlags dest_flags);

Lookup a conversion handler type for a given src_type to dest_type conversion. Using the two flags parameters matches can be made to parent and/or child items of the given type. If a flags field contains 0 then only the same type will match.

src_type : GObject derived source type
dest_type : GObject derived destination type
src_flags : Find flags for source type (0 = exact match)
dest_flags : Find flags for destination type (0 = exact match)
Returns : An IpatchConverter derived GType of the matching conversion handler or 0 if no matches.

ipatch_lookup_converter_info ()

gboolean            ipatch_lookup_converter_info        (GType converter_type,
                                                         GType *src_type,
                                                         int *src_count,
                                                         GType *dest_type,
                                                         int *dest_count);

Lookup information for a given converter_type.

converter_type : Converter type
src_type : Output - Source type (pass NULL to ignore)
src_count : Output - Expected source item count (-1 = unlimited, -2 = unlimited and can be none, pass NULL to ignore)
dest_type : Output - Destination type (pass NULL to ignore)
dest_count : Output - Expected destination item count (-1 = unlimited, -2 = unlimited and can be none, pass NULL to ignore)
Returns : TRUE if info was found for the given converter_type (it is registered), FALSE otherwise

ipatch_create_converter ()

IpatchConverter*    ipatch_create_converter             (GType src_type,
                                                         GType dest_type,
                                                         IpatchConverterFindFlags src_flags,
                                                         IpatchConverterFindFlags dest_flags);

Create a converter object for converting an object of type src_type to dest_type. A convenience function, since one could use ipatch_find_converter() and create an instance of the returned type. See ipatch_find_converter() for more details.

src_type : GObject derived source type
dest_type : GObject derived destination type
src_flags : Find flags for source type (0 = exact match)
dest_flags : Find flags for destination type (0 = exact match)
Returns : The new converter object with a reference count of 1 which the caller owns, or NULL if there is no matching conversion handler type.

ipatch_get_conversion_table ()

GType*              ipatch_get_conversion_table         (void);

Retrieves the table of registered object conversion handlers.

Returns : A newly allocated and zero terminated array of GTypes which should be freed when finished with it. The array consists of type triplets: Source type, Destination type and the Conversion handler type. The Source and Destination are derived from GObject and the Conversion type is derived from IpatchConverter.

ipatch_get_conversion_dest_types ()

GType*              ipatch_get_conversion_dest_types    (GType src_type);

Gets the available destination conversion types for a given source type and parent types in its ancestry.

src_type : GObject derived GType to find available conversion destination types
Returns : A newly allocated and zero terminated array of destination GTypes which should be freed when finished with it or NULL if there aren't any matches.

ipatch_get_conversion_src_types ()

GType*              ipatch_get_conversion_src_types     (GType dest_type);

Gets the available source conversion types for a given destination type and parent types in its ancestry.

dest_type : GObject derived GType to find available conversion source types
Returns : A newly allocated and zero terminated array of source GTypes which should be freed when finished with it.

ipatch_converter_add_input ()

void                ipatch_converter_add_input          (IpatchConverter *converter,
                                                         GObject *object);

Add an input object to a converter object.

converter : Converter instance
object : Object to add

ipatch_converter_add_output ()

void                ipatch_converter_add_output         (IpatchConverter *converter,
                                                         GObject *object);

Add an output object to a converter object.

converter : Converter instance
object : Object to add

ipatch_converter_add_inputs ()

void                ipatch_converter_add_inputs         (IpatchConverter *converter,
                                                         GList *objects);

Add a list of input objects to a converter object.

converter : Converter instance
objects : List of objects to add

ipatch_converter_add_outputs ()

void                ipatch_converter_add_outputs        (IpatchConverter *converter,
                                                         GList *objects);

Add a list of output objects to a converter object.

converter : Converter instance
objects : List of objects to add

ipatch_converter_ref_input ()

GObject*            ipatch_converter_ref_input          (IpatchConverter *converter);

Get a single input object from a converter.

converter : Converter instance
Returns : The first input object from a converter or NULL if no input objects. The caller owns a reference to the returned object.

ipatch_converter_ref_output ()

GObject*            ipatch_converter_ref_output         (IpatchConverter *converter);

Get a single output object from a converter.

converter : Converter instance
Returns : The first output object from a converter or NULL if no output objects. The caller owns a reference to the returned object.

ipatch_converter_ref_inputs ()

IpatchList*         ipatch_converter_ref_inputs         (IpatchConverter *converter);

Get a list of input objects from a converter.

converter : Converter instance
Returns : A newly created input object list from a converter or NULL if no input objects. The caller owns a reference to the returned list.

ipatch_converter_ref_outputs ()

IpatchList*         ipatch_converter_ref_outputs        (IpatchConverter *converter);

Get a list of output objects from a converter.

converter : Converter instance
Returns : A newly created output object list from a converter or NULL if no output objects. The caller owns a reference to the returned list.

ipatch_converter_verify ()

gboolean            ipatch_converter_verify             (IpatchConverter *converter,
                                                         char **failmsg);

Verifies the settings of a converter object. This is automatically called before a conversion is done, so it doesn't usually need to be explicitly called.

converter : Converter object
failmsg : Location to store a failure message if converter fails verification. The stored message should be freed when no longer needed.
Returns : TRUE if converter passed verification, FALSE otherwise in which case an error message may be stored in failmsg. Remember to free the message when finished with it.

ipatch_converter_init ()

void                ipatch_converter_init               (IpatchConverter *converter);

Allows a converter type to initialize its parameters based on its input and/or output objects. This function should be called after setting the input and output objects, but before setting object parameters or converting. Calling this function is not required, but certain converters will work more intuitively if it is (an example is an audio sample saver converter which could initialize the output sample file object format based on the input sample object format).

NOTE: Verification of converter parameters is not done by this routine so converter types implementing an init method are responsible for their own verification.

converter : Converter object

ipatch_converter_convert ()

gboolean            ipatch_converter_convert            (IpatchConverter *converter,
                                                         GError **err);

Runs the conversion method of a converter object. The converter object's conversion paramters are first verified before the conversion is run.

converter : Converter object
err : Location to store error info or NULL
Returns : TRUE on success, FALSE otherwise

ipatch_converter_reset ()

void                ipatch_converter_reset              (IpatchConverter *converter);

Reset a converter object so it can be re-used.

converter : Converter object

ipatch_converter_get_notes ()

char*               ipatch_converter_get_notes          (IpatchConverter *converter);

Get notes about a conversion implementation. These notes could include things such as information about any loss of information in the conversion that may occur, etc.

converter : Converter object
Returns : Newly allocated and possibly multi-line notes and comments about a given conversion or NULL if no notes. Meant for display to the user. This string should be freed when no longer needed.

ipatch_converter_log ()

void                ipatch_converter_log                (IpatchConverter *converter,
                                                         GObject *item,
                                                         int type,
                                                         char *msg);

Logs an entry to a converter log. Usually only used by converter object handlers.

converter : Converter object
item : Item the log entry pertains to or NULL if not item specific
type : IpatchConverterLogType and other flags
msg : Message of the log. If message is dynamically allocated then the IPATCH_CONVERTER_LOG_MSG_ALLOC flag should be set in type

ipatch_converter_log_next ()

gboolean            ipatch_converter_log_next           (IpatchConverter *converter,
                                                         gpointer *pos,
                                                         GObject **item,
                                                         int *type,
                                                         char **msg);

Get the first or next log entry from a converter object.

converter : Converter object
pos : Opaque current position in log, should be NULL on first call to this function to return first log item (oldest item)
item : Location to store item of the log entry or NULL, no reference is added so the item is only guarenteed to exist for as long as the converter does
type : Location to store the type parameter of the log entry or NULL
msg : Location to store the message of the log entry or NULL, message is internal and should not be messed with and is only guarenteed for the lifetime of the converter
Returns : TRUE if an entry was returned, FALSE if no more entries in which case item, type and msg are all undefined.

Property Details

The "progress" property

  "progress"                 gfloat                : Read / Write

Conversion progress.

Allowed values: [0,1]

Default value: 0