BtSongIO: Buzztrax Bt-Core Reference Manual

## BtSongIO BtSongIO — base class for song input and output |

## Functions

gboolean | (*BtSongIOInit) ()
BtSongIO * | bt_song_io_from_data ()
BtSongIO * | bt_song_io_from_file ()
const GList * | bt_song_io_get_module_info_list ()
gboolean | bt_song_io_load ()
gboolean | bt_song_io_save ()
gboolean | (*bt_song_io_virtual_load) ()
gboolean | (*bt_song_io_virtual_save) ()

## Properties

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

## Types and Values

#define | BT_SONG_IO_ERROR
#define | BT_SONG_IO_MODULE_INFO_MAX_FORMATS
struct | BtSongIO
struct | BtSongIOClass
enum | BtSongIOError
| BtSongIOFormatInfo
| BtSongIOModuleInfo

## Object Hierarchy

        GObject
        ╰── BtSongIO
            ├── BtSongIOBuzz
            ╰── BtSongIONative

## Includes

    #include <libbtcore/core.h>

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

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

## Functions

### BtSongIOInit ()

    gboolean
    (*BtSongIOInit) (void);

Function to init the plugin.

#### Returns

`TRUE` if the plugin was initialized fine

### bt_song_io_from_data ()

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

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

#### Parameters

data | in memory data of the song |
len | the siye of the `data` block |
media_type | the media-type of the song, if available |
err | where to store the error message in case of an error, or `NULL` |

#### Returns

the new instance or `NULL` in case of an error.

[transfer full]

### bt_song_io_from_file ()

    BtSongIO *
    bt_song_io_from_file (const gchar * const file_name,
                          GError **err);

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

#### Parameters

file_name | the file name of the song |
err | where to store the error message in case of an error, or `NULL` |

#### Returns

the new instance or `NULL` in case of an error.

[transfer full]

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

[element-type BuzztraxCore.SongIOModuleInfo][transfer none]

### bt_song_io_load ()

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

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

#### Parameters

self | the BtSongIO instance to use |
song | the BtSong instance that should initialized |
err | where to store the error message in case of an error, or `NULL` |

#### Returns

`TRUE` for success

### bt_song_io_save ()

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

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

#### Parameters

self | the BtSongIO instance to use |
song | the BtSong instance that should stored |
err | where to store the error message in case of an error, or `NULL` |

#### Returns

`TRUE` for success

### bt_song_io_virtual_load ()

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

Subclasses will override this methods with the loader function.

#### Parameters

self | song-io instance |
song | song object to load |
err | where to store the error message in case of an error, or `NULL` |

#### Returns

`TRUE` for success

### bt_song_io_virtual_save ()

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

Subclasses will override this methods with the saver function.

#### Parameters

self | song-io instance |
song | song object to save |
err | where to store the error message in case of an error, or `NULL` |

#### Returns

`TRUE` for success

## Types and Values

### BT_SONG_IO_ERROR

    #define BT_SONG_IO_ERROR      bt_song_io_error_quark ()

Error domain for the song-io subsystem. Errors in this domain will be from the BtSongIOError enumeration. See GError for information on error domains.

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

#### Members

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 |

### enum BtSongIOError

Error codes returned by the song-io subsystem in additions to GIOErrorEnum.

#### Members

BT_SONG_IO_ERROR_UNKNOWN_FORMAT | file is not in one of the supported formats |
BT_SONG_IO_ERROR_UNSUPPORTED_METHOD | operation is not supported for this file type |
BT_SONG_IO_ERROR_INVALID_FORMAT | file has structural errors |

### BtSongIOFormatInfo

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

Metadata structure for BtSongIO plugins describing one format.

#### Members

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

### BtSongIOModuleInfo

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

Metadata structure for BtSongIO plugins.

#### Members

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 |

## Property Details

### The `“data”` property

      “data”                     gpointer

in memory block pointer for load save operations.

Flags: Read

### The `“data-len”` property

      “data-len”                 guint

in memory block length for load save operations.

Flags: Read

Default value: 0

### The `“file-name”` property

      “file-name”                gchar *

full filename for load save operations.

Flags: Read

Default value: NULL

### The `“status”` property

      “status”                   gchar *

status of load save operations.

Flags: Read / Write

Default value: NULL