## IpatchConverter IpatchConverter — Base class for object conversion handlers |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchConverter;
    enum                IpatchConverterLogType;
    #define             IPATCH_CONVERTER_LOG_TYPE_MASK
    #define             IPATCH_CONVERTER_LOG_MSG_ALLOC
    #define             IPATCH_CONVERTER_INPUT              (converter)
    #define             IPATCH_CONVERTER_OUTPUT             (converter)
    enum                IpatchConverterCount;
    enum                IpatchConverterFlags;
    enum                IpatchConverterPriority;
    gboolean            ipatch_convert_objects              (GObject *input,
                                                             GObject *output,
                                                             GError **err);
    GObject *           ipatch_convert_object_to_type       (GObject *object,
                                                             GType type,
                                                             GError **err);
    IpatchList *        ipatch_convert_object_to_type_multi (GObject *object,
                                                             GType type,
                                                             GError **err);
    IpatchList *        ipatch_convert_object_to_type_multi_set
                                                            (GObject *object,
                                                             GType type,
                                                             GError **err,
                                                             const char *first_property_name,
                                                             ...);
    IpatchConverter *   ipatch_create_converter             (GType src_type,
                                                             GType dest_type);
    void                ipatch_register_converter_map       (GType conv_type,
                                                             guint flags,
                                                             GType src_type,
                                                             GType src_match,
                                                             gint8 src_count,
                                                             GType dest_type,
                                                             GType dest_match,
                                                             gint8 dest_count);
    GType               ipatch_find_converter               (GType src_type,
                                                             GType dest_type);
    IpatchConverterInfo * ipatch_lookup_converter_info      (GType conv_type,
                                                             GType src_type,
                                                             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_get_input          (IpatchConverter *converter);
    GObject *           ipatch_converter_get_output         (IpatchConverter *converter);
    IpatchList *        ipatch_converter_get_inputs         (IpatchConverter *converter);
    IpatchList *        ipatch_converter_get_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);
    void                ipatch_converter_log_printf         (IpatchConverter *converter,
                                                             GObject *item,
                                                             int type,
                                                             const char *fmt,
                                                             ...);
    gboolean            ipatch_converter_log_next           (IpatchConverter *converter,
                                                             gpointer *pos,
                                                             GObject **item,
                                                             int *type,
                                                             char **msg);
    void                ipatch_converter_set_link_funcs     (IpatchConverter *converter,
                                                             IpatchConverterLinkLookupFunc *link_lookup,
                                                             IpatchConverterLinkNotifyFunc *link_notify);

## Object Hierarchy

      GObject
       +----IpatchConverter
             +----IpatchConverterSF2VoiceCache

## Properties

      "progress"                 gfloat                : Read / Write

## Description

A base abstract type for object conversion handlers.

## Details

### IpatchConverter

    typedef struct _IpatchConverter IpatchConverter;

### 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

### IPATCH_CONVERTER_INPUT()

    #define             IPATCH_CONVERTER_INPUT(converter)

### IPATCH_CONVERTER_OUTPUT()

    #define             IPATCH_CONVERTER_OUTPUT(converter)

### enum IpatchConverterCount

    typedef enum
    {
      IPATCH_CONVERTER_COUNT_ONE_OR_MORE  = -1,	/* 1 or more objects */
      IPATCH_CONVERTER_COUNT_ZERO_OR_MORE = -2	/* 0 or more objects */
    } IpatchConverterCount;

### enum IpatchConverterFlags

    typedef enum
    {
      IPATCH_CONVERTER_FLAG_SRC_DERIVED = 1 << 8    /* match source derived types */
    } IpatchConverterFlags;

### enum IpatchConverterPriority

    typedef enum
    {
      /* 0 value is an alias for IPATCH_CONVERTER_PRIORITY_DEFAULT */

      IPATCH_CONVERTER_PRIORITY_LOWEST  = 1,
      IPATCH_CONVERTER_PRIORITY_LOW     = 25,
      IPATCH_CONVERTER_PRIORITY_DEFAULT = 50,
      IPATCH_CONVERTER_PRIORITY_HIGH    = 75,
      IPATCH_CONVERTER_PRIORITY_HIGHEST = 100
    } IpatchConverterPriority;

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

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

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

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

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

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

`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`
`...` : | 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.

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

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

### ipatch_register_converter_map ()

    void                ipatch_register_converter_map       (GType conv_type,
                                                             guint flags,
                                                             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`.

`conv_type` : | IpatchConverter derived GType of conversion handler
`flags` : | IpatchConverterFlags logically ORed with a priority (number from 0 to 100, 0 will use the default). IpatchConverterPriority defines some common priorities. Used for overriding other converters for specific types. If IPATCH_CONVERTER_FLAG_SRC_DERIVED is specified then types which are derived (children) of `src_type` will also match.
`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 to match only `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 to match only `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.

### 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()`.

`src_type` : | GObject derived source type
`dest_type` : | GObject derived destination type
Returns : | An IpatchConverter derived GType of the matching conversion handler or 0 if no matches.

### ipatch_lookup_converter_info ()

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

Lookup converter map info.

`conv_type` : | IpatchConverter derived GType to lookup info on (or 0 for wildcard)
`src_type` : | Source type of conversion map to lookup (or 0 for default map)
`dest_type` : | Destination type of conversion map (0 if `src_type` is 0)
Returns : | Converter info structure or `NULL` if no match. The returned pointer is internal and should not be modified or freed.

### 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_get_input ()

    GObject *           ipatch_converter_get_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_get_output ()

    GObject *           ipatch_converter_get_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_get_inputs ()

    IpatchList *        ipatch_converter_get_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_get_outputs ()

    IpatchList *        ipatch_converter_get_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_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.

`converter` : | Converter object
`item` : | Item the log entry pertains to or `NULL` if not item specific
`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.

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

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

`converter` : | Converter object
`link_lookup` : | Set the link lookup callback function
`link_notify` : | Set the link notify callback function

## Property Details

### The `"progress"` property

      "progress"                 gfloat                : Read / Write

Conversion progress.

Allowed values: [0,1]

Default value: 0