![]() |
![]() |
![]() |
libInstPatch Reference Manual | ![]() |
---|---|---|---|---|
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);
GObject +----IpatchConverter +----IpatchCramDecoderConverter +----IpatchCramEncoderConverter
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.
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;
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;
typedef enum /*< flags >*/ { IPATCH_CONVERTER_FIND_PARENT = 1 << 0, /* match parent types also */ IPATCH_CONVERTER_FIND_CHILD = 1 << 1 /* match child types also */ } IpatchConverterFindFlags;
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) |
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. |
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
|
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.
|
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. |
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. |
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. |
void ipatch_converter_add_input (IpatchConverter *converter, GObject *object);
Add an input object to a converter object.
converter : |
Converter instance |
object : |
Object to add |
void ipatch_converter_add_output (IpatchConverter *converter, GObject *object);
Add an output object to a converter object.
converter : |
Converter instance |
object : |
Object to add |
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 |
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 |
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.
|
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.
|
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.
|
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.
|
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.
|
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 |
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.
void ipatch_converter_reset (IpatchConverter *converter);
Reset a converter object so it can be re-used.
converter : |
Converter object |
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.
|
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
|
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.
|
progress
" property"progress" gfloat : Read / Write
Conversion progress.
Allowed values: [0,1]
Default value: 0