## BtSongIO

BtSongIO — base class for song input and output

## Synopsis

    #include <libbtcore/core.h>

    #define             BT_SONG_IO_MODULE_INFO_MAX_FORMATS
    struct              BtSongIO;
    struct              BtSongIOClass;
                        BtSongIOFormatInfo;
    gboolean            (*BtSongIOInit)                     (void);
                        BtSongIOModuleInfo;
    BtSongIO *          bt_song_io_from_data                (gpointer *data,
                                                             guint len,
                                                             const gchar *media_type);
    BtSongIO *          bt_song_io_from_file                (const gchar * const file_name);
    const GList *       bt_song_io_get_module_info_list     (void);
    gboolean            bt_song_io_load                     (BtSongIO const *self,
                                                             const BtSong * const song);
    gboolean            bt_song_io_save                     (BtSongIO const *self,
                                                             const BtSong * const song);
    gboolean            (*bt_song_io_virtual_load)          (gconstpointer self,
                                                             const BtSong * const song);
    gboolean            (*bt_song_io_virtual_save)          (gconstpointer const self,
                                                             const BtSong * const song);

## Object Hierarchy

      GObject
       +----BtSongIO
             +----BtSongIONative

## Properties

      "data"                     gpointer              : Read
      "data-len"                 guint                 : Read
      "file-name"                gchar*                : Read
      "status"                   gchar*                : Read / Write

## Description

A base class for BtSong loader and saver implementations. A BtSongIO module needs to be installed as a shared library into LIBDIR/songio. It is recognized, if it exports a BtSongIOModuleInfo structure. At runtime the detect method of each module is called with the chosen file-name. The module should return its GType if it can handle the format or `NULL` else.

Such a module should overwrite the `bt_song_io_load()` and/or `bt_song_io_save()` default implementations.

There is an internal subclass of this called BtSongIONative.

### Note

This API is not yet fully stable. Please discuss with the deverloper team if you intend to write a io plugin.

## Details

### BT_SONG_IO_MODULE_INFO_MAX_FORMATS

    #define BT_SONG_IO_MODULE_INFO_MAX_FORMATS 10

Maximum number of BtSongIOFormatInfo per plugin (10).

### struct BtSongIO

    struct BtSongIO;

base object for song input and output plugins

### struct BtSongIOClass

    struct BtSongIOClass {
      const GObjectClass parent;

      /* class methods */
      bt_song_io_virtual_load load;
      bt_song_io_virtual_save save;
    };

Base class for song input and output plugins

const GObjectClass `parent`; | parent class type
bt_song_io_virtual_load `load`; | virtual method for loading a song
bt_song_io_virtual_save `save`; | virtual method for saving a song

### BtSongIOFormatInfo

    typedef struct {
      GType type;
      const gchar *name;
      const gchar *mime_type;
      const gchar *extension;
    } BtSongIOFormatInfo;

Metadata structure for BtSongIO plugins describing one format.

GType `type`; | the io module GType
const gchar *`name`; | format name
const gchar *`mime_type`; | mime type
const gchar *`extension`; | file extension

### BtSongIOInit ()

    gboolean            (*BtSongIOInit)                     (void);

Function to init the plugin.

Returns : | `TRUE` if the plugin was initialized fine

### BtSongIOModuleInfo

    typedef struct {
      BtSongIOInit init;
      BtSongIOFormatInfo formats[BT_SONG_IO_MODULE_INFO_MAX_FORMATS];
    } BtSongIOModuleInfo;

Metadata structure for BtSongIO plugins.

BtSongIOInit `init`; | pointer to init function, can be `NULL`.
BtSongIOFormatInfo `formats`[BT_SONG_IO_MODULE_INFO_MAX_FORMATS]; | `NULL` terminated array of formats supported by this plugin

### bt_song_io_from_data ()

    BtSongIO *          bt_song_io_from_data                (gpointer *data,
                                                             guint len,
                                                             const gchar *media_type);

Create a new instance from the given parameters. Each installed plugin will test if it can handle the file type.

`data` : | in memory data of the song
`len` : | the siye of the `data` block
`media_type` : | the media-type of the song, if available
Returns : | the new instance or `NULL` in case of an error

### bt_song_io_from_file ()

    BtSongIO *          bt_song_io_from_file                (const gchar * const file_name);

Create a new instance from the given `file_name`. Each installed plugin will test if it can handle the file type.

`file_name` : | the file name of the song
Returns : | the new instance or `NULL` in case of an error

### bt_song_io_get_module_info_list ()

    const GList *       bt_song_io_get_module_info_list     (void);

Get read only access to list of BtSongIOModuleInfo entries.

Returns : | the GList.

### bt_song_io_load ()

    gboolean            bt_song_io_load                     (BtSongIO const *self,
                                                             const BtSong * const song);

load the song from a file. The file is set in the constructor

`self` : | the BtSongIO instance to use
`song` : | the BtSong instance that should initialized
Returns : | `TRUE` for success

### bt_song_io_save ()

    gboolean            bt_song_io_save                     (BtSongIO const *self,
                                                             const BtSong * const song);

save the song to a file. The file is set in the constructor

`self` : | the BtSongIO instance to use
`song` : | the BtSong instance that should stored
Returns : | `TRUE` for success

### bt_song_io_virtual_load ()

    gboolean            (*bt_song_io_virtual_load)          (gconstpointer self,
                                                             const BtSong * const song);

Subclasses will override this methods with the loader function.

`self` : | song-io instance
`song` : | song object to load
Returns : | `TRUE` for success

### bt_song_io_virtual_save ()

    gboolean            (*bt_song_io_virtual_save)          (gconstpointer const self,
                                                             const BtSong * const song);

Subclasses will override this methods with the saver function.

`self` : | song-io instance
`song` : | song object to save
Returns : | `TRUE` for success

## Property Details

### The `"data"` property

      "data"                     gpointer              : Read

in memory block pointer for load save operations.

### The `"data-len"` property

      "data-len"                 guint                 : Read

in memory block length for load save operations.

Default value: 0

### The `"file-name"` property

      "file-name"                gchar*                : Read

full filename for load save operations.

Default value: NULL

### The `"status"` property

      "status"                   gchar*                : Read / Write

status of load save operations.

Default value: NULL