## IpatchDLS2 IpatchDLS2 — DLS version 2 instrument file object |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchDLS2;
    enum                IpatchDLS2Flags;
    #define             IPATCH_DLS2_UNUSED_FLAG_SHIFT
    IpatchDLS2 *        ipatch_dls2_new                     (void);
    #define             ipatch_dls2_get_insts               (dls)
    #define             ipatch_dls2_get_samples             (dls)
    void                ipatch_dls2_set_file                (IpatchDLS2 *dls,
                                                             IpatchDLSFile *file);
    IpatchDLSFile *     ipatch_dls2_get_file                (IpatchDLS2 *dls);
    char *              ipatch_dls2_get_info                (IpatchDLS2 *dls,
                                                             guint32 fourcc);
    void                ipatch_dls2_set_info                (IpatchDLS2 *dls,
                                                             guint32 fourcc,
                                                             const char *val);
    char *              ipatch_dls2_make_unique_name        (IpatchDLS2 *dls,
                                                             GType child_type,
                                                             const char *name,
                                                             const IpatchItem *exclude);
    IpatchDLS2Inst *    ipatch_dls2_find_inst               (IpatchDLS2 *dls,
                                                             const char *name,
                                                             int bank,
                                                             int program,
                                                             const IpatchDLS2Inst *exclude);
    IpatchDLS2Sample *  ipatch_dls2_find_sample             (IpatchDLS2 *dls,
                                                             const char *name,
                                                             const IpatchDLS2Sample *exclude);
    IpatchList *        ipatch_dls2_get_region_references   (IpatchDLS2Sample *sample);

## Object Hierarchy

      GObject
       +----IpatchItem
             +----IpatchContainer
                   +----IpatchBase
                         +----IpatchDLS2
                               +----IpatchGig

## Properties

      "archive-location"         gchar*                : Read / Write
      "artist"                   gchar*                : Read / Write
      "comment"                  gchar*                : Read / Write
      "commissioned"             gchar*                : Read / Write
      "copyright"                gchar*                : Read / Write
      "date"                     gchar*                : Read / Write
      "engineer"                 gchar*                : Read / Write
      "genre"                    gchar*                : Read / Write
      "keywords"                 gchar*                : Read / Write
      "medium"                   gchar*                : Read / Write
      "name"                     gchar*                : Read / Write
      "product"                  gchar*                : Read / Write
      "software"                 gchar*                : Read / Write
      "source"                   gchar*                : Read / Write
      "source-form"              gchar*                : Read / Write
      "subject"                  gchar*                : Read / Write
      "technician"               gchar*                : Read / Write
      "version"                  gchar*                : Read / Write

## Description

Object type for DLS version 2 format instruments.

## Details

### IpatchDLS2

    typedef struct {
      IpatchBase parent_instance;

      /* NOTE: This is not the DLS version! Optional descriptive stamp version */
      guint32 ms_version; /* most significant 32 bits of 64 bit version */
      guint32 ls_version; /* least significant 32 bits of 64 bit version */

      IpatchDLS2Info *info;		/* info strings */
      GSList *insts;		/* list of #IpatchDLS2Inst objects */
      GSList *samples;		/* list of #IpatchDLS2Sample objects */

      guint8 *dlid;	/* 16 bytes or NULL - globally unique ID (indicates changes) */
    } IpatchDLS2;

### enum IpatchDLS2Flags

    typedef enum
    {
      /* set if the ms_version/ls_version values are valid */
      IPATCH_DLS2_VERSION_SET = 1 << IPATCH_BASE_UNUSED_FLAG_SHIFT
    } IpatchDLS2Flags;

### IPATCH_DLS2_UNUSED_FLAG_SHIFT

    #define IPATCH_DLS2_UNUSED_FLAG_SHIFT (IPATCH_BASE_UNUSED_FLAG_SHIFT + 4)

### ipatch_dls2_new ()

    IpatchDLS2 *        ipatch_dls2_new                     (void);

Create a new DLS base object.

Returns : | New DLS base object with a reference count of 1. Caller owns the reference and removing it will destroy the item.

### ipatch_dls2_get_insts()

    #define             ipatch_dls2_get_insts(dls)

### ipatch_dls2_get_samples()

    #define             ipatch_dls2_get_samples(dls)

### ipatch_dls2_set_file ()

    void                ipatch_dls2_set_file                (IpatchDLS2 *dls,
                                                             IpatchDLSFile *file);

Sets the file object of a DLS object. DLS files are kept open for sample data that references the file. This function sets a DLS object's authoritive file. A convenience function, as `ipatch_base_set_file()` does the same thing (albeit without more specific type casting).

`dls` : | DLS to set file object of
`file` : | File object to use with the DLS object

### ipatch_dls2_get_file ()

    IpatchDLSFile *     ipatch_dls2_get_file                (IpatchDLS2 *dls);

Gets the file object of a DLS. The returned DLS file object's reference count has been incremented. The caller owns the reference and is responsible for removing it with g_object_unref. A convenience function as `ipatch_base_get_file()` does the same thing (albeit without more specific type casting).

`dls` : | DLS object to get file object of
Returns : | The DLS file object or `NULL` if `dls` is not open. Remember to unref the file object with `g_object_unref()` when done with it.

### ipatch_dls2_get_info ()

    char *              ipatch_dls2_get_info                (IpatchDLS2 *dls,
                                                             guint32 fourcc);

Get a DLS info string by FOURCC integer ID (integer representation of a 4 character RIFF chunk ID, see IpatchRiff).

`dls` : | DLS to get info from
`fourcc` : | FOURCC integer id of INFO to get
Returns : | New allocated info string value or `NULL` if no info with the given `fourcc` ID. String should be freed when finished with it.

### ipatch_dls2_set_info ()

    void                ipatch_dls2_set_info                (IpatchDLS2 *dls,
                                                             guint32 fourcc,
                                                             const char *val);

Sets an INFO value in a DLS object.

Emits changed signal on DLS object.

`dls` : | DLS to set info of
`fourcc` : | FOURCC integer ID of INFO to set
`val` : | Value to set info to or `NULL` to unset (clear) info.

### ipatch_dls2_make_unique_name ()

    char *              ipatch_dls2_make_unique_name        (IpatchDLS2 *dls,
                                                             GType child_type,
                                                             const char *name,
                                                             const IpatchItem *exclude);

Generates a unique name for the given `child_type` in `dls`. The `name` parameter is used as a base and is modified, by appending a number, to make it unique (if necessary). The `exclude` parameter is used to exclude an existing `dls` child item from the search.

MT-Note: To ensure that an item is actually unique before being added to a DLS object, `ipatch_container_add_unique()` should be used.

`dls` : | DLS object
`child_type` : | A child type of `dls` to search for a unique name in
`name` : | An initial name to use or NULL
`exclude` : | An item to exclude from search or NULL
Returns : | A new unique name which should be freed when finished with it.

### ipatch_dls2_find_inst ()

    IpatchDLS2Inst *    ipatch_dls2_find_inst               (IpatchDLS2 *dls,
                                                             const char *name,
                                                             int bank,
                                                             int program,
                                                             const IpatchDLS2Inst *exclude);

Find a instrument by name or bank:program MIDI numbers. If instrument `name` and `bank`:`program` are specified then match for either condition. If a instrument is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with `g_object_unref()` when finished with it.

`dls` : | DLS object to search in
`name` : | Name of instrument to find or `NULL` to match any name
`bank` : | MIDI bank number of instrument to search for or -1 to not search by MIDI bank:program numbers
`program` : | MIDI program number of instrument to search for, only used if `bank` is 0-128
`exclude` : | A instrument to exclude from the search or `NULL`
Returns : | The matching instrument or `NULL` if not found. Remember to unref the item when finished with it.

### ipatch_dls2_find_sample ()

    IpatchDLS2Sample *  ipatch_dls2_find_sample             (IpatchDLS2 *dls,
                                                             const char *name,
                                                             const IpatchDLS2Sample *exclude);

Find a sample by `name` in a SoundFont. If a sample is found its reference count is incremented before it is returned. The caller is responsible for removing the reference with `g_object_unref()` when finished with it.

`dls` : | SoundFont to search in
`name` : | Name of sample to find
`exclude` : | A sample to exclude from the search or `NULL`
Returns : | The matching sample or `NULL` if not found. Remember to unref the item when finished with it.

### ipatch_dls2_get_region_references ()

    IpatchList *        ipatch_dls2_get_region_references   (IpatchDLS2Sample *sample);

Get list of regions referencing an IpatchDLS2Sample.

`sample` : | Sample to locate referencing regions of.
Returns : | New item list containing IpatchDLS2Region objects that refer to `sample`. The returned list has a reference count of 1 which the caller owns, unreference it when done.

## Property Details

### The `"archive-location"` property

      "archive-location"         gchar*                : Read / Write

Location where subject is archived.

Default value: NULL

### The `"artist"` property

      "artist"                   gchar*                : Read / Write

Original artist.

Default value: NULL

### The `"comment"` property

      "comment"                  gchar*                : Read / Write

Comments.

Default value: NULL

### The `"commissioned"` property

      "commissioned"             gchar*                : Read / Write

Who commissioned the material.

Default value: NULL

### The `"copyright"` property

      "copyright"                gchar*                : Read / Write

Copyright.

Default value: NULL

### The `"date"` property

      "date"                     gchar*                : Read / Write

Creation date (YYYY-MM-DD).

Default value: NULL

### The `"engineer"` property

      "engineer"                 gchar*                : Read / Write

Engineers separated by "; ".

Default value: NULL

### The `"genre"` property

      "genre"                    gchar*                : Read / Write

Genre.

Default value: NULL

### The `"keywords"` property

      "keywords"                 gchar*                : Read / Write

Keywords (separated by "; ").

Default value: NULL

### The `"medium"` property

      "medium"                   gchar*                : Read / Write

Original medium of the material (record, CD, etc).

Default value: NULL

### The `"name"` property

      "name"                     gchar*                : Read / Write

Name.

Default value: "untitled"

### The `"product"` property

      "product"                  gchar*                : Read / Write

Product intended for.

Default value: NULL

### The `"software"` property

      "software"                 gchar*                : Read / Write

Editor software used.

Default value: NULL

### The `"source"` property

      "source"                   gchar*                : Read / Write

Source of the original material.

Default value: NULL

### The `"source-form"` property

      "source-form"              gchar*                : Read / Write

Original source that was digitized.

Default value: NULL

### The `"subject"` property

      "subject"                  gchar*                : Read / Write

Subject of the material.

Default value: NULL

### The `"technician"` property

      "technician"               gchar*                : Read / Write

Technician who sampled the material.

Default value: NULL

### The `"version"` property

      "version"                  gchar*                : Read / Write

File version "n.n.n.n".

Default value: NULL