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

Generated by GTK-Doc V1.15