IpatchConverter

IpatchConverter — Base class for object conversion handlers

Stability Level

Stable, unless otherwise indicated

Functions

#define IPATCH_CONVERTER_INPUT()
#define IPATCH_CONVERTER_OUTPUT()
gboolean ipatch_convert_objects ()
GObject * ipatch_convert_object_to_type ()
IpatchList * ipatch_convert_object_to_type_multi ()
GList * ipatch_convert_object_to_type_multi_list ()
IpatchList * ipatch_convert_object_to_type_multi_set ()
GList * ipatch_convert_object_to_type_multi_set_vlist ()
IpatchConverter * ipatch_create_converter ()
IpatchConverter * ipatch_create_converter_for_objects ()
IpatchConverter * ipatch_create_converter_for_object_to_type ()
void ipatch_register_converter_map ()
GType ipatch_find_converter ()
GType * ipatch_find_converters ()
const IpatchConverterInfo * ipatch_lookup_converter_info ()
const IpatchConverterInfo * ipatch_get_converter_info ()
void ipatch_converter_add_input ()
void ipatch_converter_add_output ()
void ipatch_converter_add_inputs ()
void ipatch_converter_add_outputs ()
GObject * ipatch_converter_get_input ()
GObject * ipatch_converter_get_output ()
IpatchList * ipatch_converter_get_inputs ()
GList * ipatch_converter_get_inputs_list ()
IpatchList * ipatch_converter_get_outputs ()
GList * ipatch_converter_get_outputs_list ()
gboolean ipatch_converter_verify ()
void ipatch_converter_init ()
gboolean ipatch_converter_convert ()
void ipatch_converter_reset ()
char * ipatch_converter_get_notes ()
void ipatch_converter_log ()
void ipatch_converter_log_printf ()
gboolean ipatch_converter_log_next ()
void ipatch_converter_set_link_funcs ()
void ipatch_converter_set_link_funcs_full ()

Properties

float progress Read / Write

Types and Values

Object Hierarchy

    GObject
    ╰── IpatchConverter
        ├── IpatchConverterFileToSLI
        ├── IpatchConverterFileToSLISample
        ╰── IpatchConverterSF2VoiceCache

Description

A base abstract type for object conversion handlers.

Functions

IPATCH_CONVERTER_INPUT()

#define             IPATCH_CONVERTER_INPUT(converter)

IPATCH_CONVERTER_OUTPUT()

#define             IPATCH_CONVERTER_OUTPUT(converter)

ipatch_convert_objects ()

gboolean
ipatch_convert_objects (GObject *input,
                        GObject *output,
                        GError **err);

A convenience function for converting from one object to another. This function will only work for converters which take exactly one input and output object.

Parameters

input

Input object

 

output

Output object

 

err

Location to store error info or NULL

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set)


ipatch_convert_object_to_type ()

GObject *
ipatch_convert_object_to_type (GObject *object,
                               GType type,
                               GError **err);

A convenience function to convert an object to another object of a given type. This function will only work for converters which require 1 input and one or zero outputs. The output object is created as needed and returned.

Parameters

object

Object to convert from

 

type

Type of object to convert to

 

err

Location to store error info or NULL to ignore

 

Returns

The output object or NULL on error (in which case err may be set). The returned object has a refcount of 1 which the caller owns.

[transfer full]


ipatch_convert_object_to_type_multi ()

IpatchList *
ipatch_convert_object_to_type_multi (GObject *object,
                                     GType type,
                                     GError **err);

A convenience function to convert an object to one or more objects of a given type . This function will work for converters which require 1 input and any number of outputs.

[skip]

Parameters

object

Object to convert from

 

type

Type of object to convert to

 

err

Location to store error info or NULL to ignore

 

Returns

List of output objects or NULL on error (in which case err may be set). The returned object list has a refcount of 1 which the caller owns.

[transfer full]


ipatch_convert_object_to_type_multi_list ()

GList *
ipatch_convert_object_to_type_multi_list
                               (GObject *object,
                                GType type,
                                GError **err);

A convenience function to convert an object to one or more objects of a given type . This function will work for converters which require 1 input and any number of outputs.

[rename-to ipatch_convert_object_to_type_multi]

Parameters

object

Object to convert from

 

type

Type of object to convert to

 

err

Location to store error info or NULL to ignore

 

Returns

List of output objects or NULL on error (in which case err may be set). Free the list with ipatch_glist_unref_free() when finished using it.

[element-type GObject.Object][transfer full]

Since: 1.1.0


ipatch_convert_object_to_type_multi_set ()

IpatchList *
ipatch_convert_object_to_type_multi_set
                               (GObject *object,
                                GType type,
                                GError **err,
                                const char *first_property_name,
                                ...);

A convenience function to convert an object to one or more objects of a given type . This function will work for converters which require 1 input and any number of outputs. Like ipatch_convert_object_to_type_multi() but allows for properties of the converter to be assigned.

[skip]

Parameters

object

Object to convert from

 

type

Type of object to convert to

 

err

Location to store error info or NULL to ignore

 

first_property_name

Name of first property to assign or NULL.

[nullable]

...

First property value followed by property name/value pairs (as per g_object_set()) to assign to the resulting converter, terminated with a NULL property name.

 

Returns

List of output objects or NULL on error (in which case err may be set). The returned object list has a refcount of 1 which the caller owns.

[transfer full]


ipatch_convert_object_to_type_multi_set_vlist ()

GList *
ipatch_convert_object_to_type_multi_set_vlist
                               (GObject *object,
                                GType type,
                                GError **err,
                                const char *first_property_name,
                                va_list args);

A convenience function to convert an object to one or more objects of a given type . This function will work for converters which require 1 input and any number of outputs. Like ipatch_convert_object_to_type_multi() but allows for properties of the converter to be assigned.

[skip]

Parameters

object

Object to convert from

 

type

Type of object to convert to

 

err

Location to store error info or NULL to ignore

 

first_property_name

Name of first property to assign or NULL.

[nullable]

args

First property value followed by property name/value pairs (as per g_object_set()) to assign to the resulting converter, terminated with a NULL property name.

 

Returns

List of output objects or NULL on error (in which case err may be set). Free the list with ipatch_glist_unref_free() when finished using it.

[element-type GObject.Object][transfer full]

Since: 1.1.0


ipatch_create_converter ()

IpatchConverter *
ipatch_create_converter (GType src_type,
                         GType dest_type);

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.

Parameters

src_type

GObject derived source type

 

dest_type

GObject derived destination type

 

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.

[transfer full]


ipatch_create_converter_for_objects ()

IpatchConverter *
ipatch_create_converter_for_objects (GObject *input,
                                     GObject *output,
                                     GError **err);

A convenience function for creating a converter for converting from one object to another. This function will only work for converters which take exactly one input and output object.

Parameters

input

Input object

 

output

Output object

 

err

Location to store error info or NULL

 

Returns

The new converter or NULL on error.

[transfer full]

Since: 1.1.0


ipatch_create_converter_for_object_to_type ()

IpatchConverter *
ipatch_create_converter_for_object_to_type
                               (GObject *object,
                                GType dest_type,
                                GError **err);

A convenience function to create a converter for converting an object to another object of a given type.

Parameters

object

Object to convert from

 

dest_type

Type of object to convert to

 

err

Location to store error info or NULL to ignore

 

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.

[transfer full]

Since: 1.1.0


ipatch_register_converter_map ()

void
ipatch_register_converter_map (GType conv_type,
                               guint8 flags,
                               guint8 priority,
                               GType src_type,
                               GType src_match,
                               gint8 src_count,
                               GType dest_type,
                               GType dest_match,
                               gint8 dest_count);

Registers a IpatchConverter handler to convert objects of src_type to dest_type . NOTE: Previous versions of this function combined flags and priority into a single param.

Parameters

conv_type

IpatchConverter derived GType of conversion handler

 

flags

IpatchConverterFlags, IPATCH_CONVERTER_SRC_DERIVED or IPATCH_CONVERTER_DEST_DERIVED will match derived types of src_type or dest_type respectively.

 

priority

Converter map priority (number from 0 to 100, 0 will use the default). IpatchConverterPriority defines some common priorities. Used for overriding other converters for specific types.

 

src_type

Type for source object (GObject derived type or interface type).

 

src_match

The furthest parent type of src_type to match (all types in between are also matched, 0 or G_TYPE_NONE to only use src_type ).

 

src_count

Required number of source items (can also be an IpatchConverterCount value)

 

dest_type

Type for destination object (GObject derived type or interface type).

 

dest_match

The furthest parent type of dest_type to match (all types in between are also matched, 0, or G_TYPE_NONE to only use dest_type ).

 

dest_count

Required number of destination items (can also be an IpatchConverterCount value). This value can be 0 in the case where no objects should be supplied, but will be instead assigned after conversion.

 

Since: 1.1.0


ipatch_find_converter ()

GType
ipatch_find_converter (GType src_type,
                       GType dest_type);

Lookup a conversion handler type for a given src_type to dest_type conversion. In some cases there may be multiple conversion handlers for the given types, this function only returns the highest priority type. To get a list of all available converters use ipatch_find_converters().

Parameters

src_type

GObject derived source type (0 or G_TYPE_NONE for wildcard - Since 1.1.0)

 

dest_type

GObject derived destination type (0 or G_TYPE_NONE for wildcard - Since 1.1.0)

 

Returns

An IpatchConverter derived GType of the matching conversion handler or 0 if no matches.


ipatch_find_converters ()

GType *
ipatch_find_converters (GType src_type,
                        GType dest_type,
                        guint flags);

Lookup conversion handler types matching search criteria.

Parameters

src_type

GObject derived source type (G_TYPE_NONE for wildcard)

 

dest_type

GObject derived destination type (G_TYPE_NONE for wildcard)

 

flags

IpatchConverterFlags to modify converter matching behavior (logically OR'd with registered converter flags)

 

Returns

0 terminated array of IpatchConverter derived GTypes or NULL if no matching converters. Array should be freed with g_free() when finished using it.

[array zero-terminated=1][transfer full][nullable]

Since: 1.1.0


ipatch_lookup_converter_info ()

const IpatchConverterInfo *
ipatch_lookup_converter_info (GType conv_type,
                              GType src_type,
                              GType dest_type);

Lookup converter map info.

Parameters

conv_type

IpatchConverter derived GType to lookup info on (or 0 for wildcard, or G_TYPE_NONE - since 1.1.0)

 

src_type

Source type of conversion map to lookup (or 0 for default map, or G_TYPE_NONE - since 1.1.0)

 

dest_type

Destination type of conversion map (0 if src_type is 0, or G_TYPE_NONE - since 1.1.0)

 

Returns

Converter info structure or NULL if no match. The returned pointer is internal and should not be modified or freed.

[transfer none][nullable]


ipatch_get_converter_info ()

const IpatchConverterInfo *
ipatch_get_converter_info (GType conv_type);

Get converter info structure for a converter type.

Parameters

conv_type

IpatchConverter derived GType to lookup info on

 

Returns

Converter info structure or NULL if no match. The returned pointer is internal and should not be modified or freed.

[transfer none][nullable]

Since: 1.1.0


ipatch_converter_add_input ()

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

Add an input object to a converter object.

Parameters

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.

Parameters

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.

Parameters

converter

Converter instance

 

objects

List of objects to add.

[element-type GObject.Object][transfer none]

ipatch_converter_add_outputs ()

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

Add a list of output objects to a converter object.

Parameters

converter

Converter instance

 

objects

List of objects to add.

[element-type GObject.Object][transfer none]

ipatch_converter_get_input ()

GObject *
ipatch_converter_get_input (IpatchConverter *converter);

Get a single input object from a converter.

Parameters

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.

[transfer full]


ipatch_converter_get_output ()

GObject *
ipatch_converter_get_output (IpatchConverter *converter);

Get a single output object from a converter.

Parameters

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.

[transfer full]


ipatch_converter_get_inputs ()

IpatchList *
ipatch_converter_get_inputs (IpatchConverter *converter);

Get a list of input objects from a converter.

[skip]

Parameters

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.

[transfer full]


ipatch_converter_get_inputs_list ()

GList *
ipatch_converter_get_inputs_list (IpatchConverter *converter);

Get a list of input objects from a converter.

[rename-to ipatch_converter_get_inputs]

Parameters

converter

Converter instance

 

Returns

A newly created input object list from a converter or NULL if no input objects. Free the list with ipatch_glist_unref_free() when finished using it.

[element-type GObject.Object][transfer full]

Since: 1.1.0


ipatch_converter_get_outputs ()

IpatchList *
ipatch_converter_get_outputs (IpatchConverter *converter);

Get a list of output objects from a converter.

[skip]

Parameters

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.

[transfer full]


ipatch_converter_get_outputs_list ()

GList *
ipatch_converter_get_outputs_list (IpatchConverter *converter);

Get a list of output objects from a converter.

[rename-to ipatch_converter_get_outputs]

Parameters

converter

Converter instance

 

Returns

A newly created output object list from a converter or NULL if no output objects. Free the list with ipatch_glist_unref_free() when finished using it.

[element-type GObject.Object][transfer full]

Since: 1.1.0


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.

Parameters

converter

Converter object

 

failmsg

Location to store a failure message if converter fails verification. The stored message should be freed when no longer needed.

[out][transfer full]

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

[skip]

Parameters

converter

Converter object

 

item

Item the log entry pertains to or NULL if not item specific.

[nullable]

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_printf ()

void
ipatch_converter_log_printf (IpatchConverter *converter,
                             GObject *item,
                             int type,
                             const char *fmt,
                             ...);

Logs a printf style message to a converter log. Usually only used by converter object handlers. The IPATCH_CONVERTER_LOG_MSG_ALLOC flag is automatically set on the log entry, since it is dynamically allocated.

Parameters

converter

Converter object

 

item

Item the log entry pertains to or NULL if not item specific.

[nullable]

type

IpatchConverterLogType and other flags

 

fmt

Printf format style string

 

...

Arguments to fmt message string

 

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.

Parameters

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).

[out]

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.

[out][transfer none][optional]

type

Location to store the type parameter of the log entry or NULL.

[out][optional]

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 .

[out][transfer none]

Returns

TRUE if an entry was returned, FALSE if no more entries in which case item, type and msg are all undefined.


ipatch_converter_set_link_funcs ()

void
ipatch_converter_set_link_funcs (IpatchConverter *converter,
                                 IpatchConverterLinkLookupFunc *link_lookup,
                                 IpatchConverterLinkNotifyFunc *link_notify);

This function allows for object link interception by the user of an IpatchConverter instance. The callback functions are used by conversion processes which create objects linking other external objects which need to be converted. For each link object needing conversion link_lookup will be called. If link_lookup returns a valid pointer it is used as the converted link object, if NULL is returned then the link will be converted and link_notify will be called with the new converted item. An example usage of this feature is the IpatchPaste system, which does object conversions and substitutes already converted objects (a conversion pool).

[skip]

Parameters

converter

Converter object

 

link_lookup

Set the link lookup callback function

 

link_notify

Set the link notify callback function

 

ipatch_converter_set_link_funcs_full ()

void
ipatch_converter_set_link_funcs_full (IpatchConverter *converter,
                                      IpatchConverterLinkLookupFunc *link_lookup,
                                      IpatchConverterLinkNotifyFunc *link_notify,
                                      GDestroyNotify notify_func,
                                      gpointer user_data);

This function allows for object link interception by the user of an IpatchConverter instance. The callback functions are used by conversion processes which create objects linking other external objects which need to be converted. For each link object needing conversion link_lookup will be called. If link_lookup returns a valid pointer it is used as the converted link object, if NULL is returned then the link will be converted and link_notify will be called with the new converted item. An example usage of this feature is the IpatchPaste system, which does object conversions and substitutes already converted objects (a conversion pool).

[rename-to ipatch_converter_set_link_funcs]

Parameters

converter

Converter object

 

link_lookup

Set the link lookup callback function.

[scope notified][nullable]

link_notify

Set the link notify callback function.

[scope notified][nullable]

notify_func

Callback which gets called when link functions are removed.

[scope async][closure user_data][nullable]

user_data

User data passed to notify_func (not link_lookup or link_notify ).

[nullable]

Since: 1.1.0

Types and Values

enum IpatchConverterLogType

Members

IPATCH_CONVERTER_LOG_RATING

   

IPATCH_CONVERTER_LOG_INFO

   

IPATCH_CONVERTER_LOG_WARN

   

IPATCH_CONVERTER_LOG_CRITICAL

   

IPATCH_CONVERTER_LOG_FATAL

   

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 IpatchConverterCount

Members

IPATCH_CONVERTER_COUNT_ONE_OR_MORE

   

IPATCH_CONVERTER_COUNT_ZERO_OR_MORE

   

enum IpatchConverterFlags

Flags for ipatch_register_converter_map()

Members

IPATCH_CONVERTER_SRC_DERIVED

Match source derived types also (type descendants of src_type)

 

IPATCH_CONVERTER_DEST_DERIVED

Match destination derived types also (type descendants of dest_type)

 

Since: 1.1.0


enum IpatchConverterPriority

Members

IPATCH_CONVERTER_PRIORITY_LOWEST

   

IPATCH_CONVERTER_PRIORITY_LOW

   

IPATCH_CONVERTER_PRIORITY_DEFAULT

   

IPATCH_CONVERTER_PRIORITY_HIGH

   

IPATCH_CONVERTER_PRIORITY_HIGHEST

   

struct IpatchConverterInfo

struct IpatchConverterInfo {
    GType conv_type;
    GType src_type;
    GType src_match;
    GType dest_type;
    GType dest_match;
    guint8 flags;
    guint8 priority;
    gint8 src_count;
    gint8 dest_count;
};

Registered object converter information.

Members

GType conv_type;

Conversion handler type

 

GType src_type;

Source type of conversion handler

 

GType src_match;

Furthest source parent type to match (0 = exact match)

 

GType dest_type;

Destination type of conversion handler

 

GType dest_match;

Furthest dest parent type to match (0 = exact match)

 

guint8 flags;

IpatchConverterFlags | priority (IpatchConverterPriority value or other integer value)

 

guint8 priority;

   

gint8 src_count;

Required source item count or IpatchConverterCount

 

gint8 dest_count;

Required destination item count or IpatchConverterCount

 

Property Details

The “progress” property

  “progress”                 float

Conversion progress.

Owner: IpatchConverter

Flags: Read / Write

Allowed values: [0,1]

Default value: 0