## BtSongIO

BtSongIO — base class for song input and output

## Synopsis

    #include <libbtcore/core.h>

                        BtSongIO;
                        BtSongIOClass;
    BtSongIO *          bt_song_io_make                     (const gchar * const file_name);
    gboolean            bt_song_io_load                     (BtSongIO const *self,
                                                             const BtSong * const song);
    gboolean            bt_song_io_save                     (BtSongIO const *self,
                                                             const BtSong * const song);
    const GList *       bt_song_io_get_module_info_list     (void);
    GType               (*BtSongIODetect)                   (const gchar * const file_name);
                        BtSongIOFormatInfo;
                        BtSongIOModuleInfo;
    #define             BT_SONG_IO_MODULE_INFO_MAX_FORMATS

    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

      "file-name"                gchar*                : Read
      "status"                   gchar*                : Read / Write

## Description

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

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

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

### BtSongIO

    typedef struct _BtSongIO BtSongIO;

base object for song input and output plugins

### BtSongIOClass

    typedef struct {
      const GObjectClass parent;

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

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

### bt_song_io_make ()

    BtSongIO *          bt_song_io_make                     (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 new song
Returns : | the new instance or `NULL` in case of an error

### 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 SongIO instance to use
`song` : | the Song 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 SongIO instance to use
`song` : | the Song instance that should stored
Returns : | `TRUE` for success

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

### BtSongIODetect ()

    GType               (*BtSongIODetect)                   (const gchar * const file_name);

Type of the file-format detect function. Each BtSongIO plugin must provide this one.

`file_name` : | the file to run the detection against
Returns : | the GType of the song-io class on succes or `NULL` otherwise

### BtSongIOFormatInfo

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

Metadata structure for BtSongIO plugins describing one format.

const gchar *`name`; | format name
const gchar *`mime_type`; | mime type
const gchar *`extension`; |

### BtSongIOModuleInfo

    typedef struct {
      BtSongIODetect detect;
      BtSongIOFormatInfo formats[BT_SONG_IO_MODULE_INFO_MAX_FORMATS];
    } BtSongIOModuleInfo;

Metadata structure for BtSongIO plugins.

BtSongIODetect `detect`; | pointer to detection function
BtSongIOFormatInfo `formats`[BT_SONG_IO_MODULE_INFO_MAX_FORMATS]; | `NULL` terminated array of formats supported by this plugin

### BT_SONG_IO_MODULE_INFO_MAX_FORMATS

    #define BT_SONG_IO_MODULE_INFO_MAX_FORMATS 10

Maximum number of BtSongIOFormatInfo per plugin (10).

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