## MirageCdTextCoder MirageCdTextCoder — General-purpose CD-TEXT encoder/decoder object. |

## Synopsis

    #include <mirage-cdtext-coder.h>

    struct              MirageCdTextCoder;
    struct              MirageCdTextCoderClass;
    gboolean            (*MirageCdTextDataCallback)         (gint code,
                                                             gint type,
                                                             gint track,
                                                             const guint8 *data,
                                                             gint data_len,
                                                             gpointer user_data);
    gboolean            mirage_cdtext_decoder_get_block_info
                                                            (MirageCdTextCoder *self,
                                                             gint block,
                                                             gint *code,
                                                             gint *charset,
                                                             gint *copyright,
                                                             GError **error);
    gboolean            mirage_cdtext_decoder_get_data      (MirageCdTextCoder *self,
                                                             gint block,
                                                             MirageCdTextDataCallback callback_func,
                                                             gpointer user_data);
    void                mirage_cdtext_decoder_init          (MirageCdTextCoder *self,
                                                             guint8 *buffer,
                                                             gint buflen);
    void                mirage_cdtext_encoder_add_data      (MirageCdTextCoder *self,
                                                             gint code,
                                                             gint type,
                                                             gint track,
                                                             const guint8 *data,
                                                             gint data_len);
    void                mirage_cdtext_encoder_encode        (MirageCdTextCoder *self,
                                                             guint8 **buffer,
                                                             gint *buflen);
    void                mirage_cdtext_encoder_init          (MirageCdTextCoder *self,
                                                             guint8 *buffer,
                                                             gint buflen);
    gboolean            mirage_cdtext_encoder_set_block_info
                                                            (MirageCdTextCoder *self,
                                                             gint block,
                                                             gint code,
                                                             gint charset,
                                                             gint copyright,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MirageObject
             +----MirageCdTextCoder

## Implemented Interfaces

MirageCdTextCoder implements MirageContextual.

## Description

MirageCdTextCoder object is a general-purpose CD-TEXT encoder/decoder. It was designed to be used by MirageSession objects to encode and decode CD-TEXT data, but it could be used in other applications as well.

It is loosely based on the CD-TEXT encoding/decoding code found in cdrdao and supports 8 CD-TEXT blocks with pack types from 0x80 to 0x8F. When encoding data, pack size data (pack type 0x8F) is always generated.

To be used as encoder, a MirageCdTextCoder encoder must be first initialized with `mirage_cdtext_encoder_init()`. Then, information for at least one CD-TEXT block (up to 8 are supported) should be set with `mirage_cdtext_encoder_set_block_info()`. After all the CD-TEXT data is added to encoder with `mirage_cdtext_encoder_add_data()`, buffer containing the encoded data can be obtained with `mirage_cdtext_encoder_encode()`.

To use a MirageCdTextCoder as CD-TEXT decoder, one should first initialize it with `mirage_cdtext_decoder_init()`. This function already performs all the decoding; block information can be obtained with `mirage_cdtext_decoder_get_block_info()` and data for each block can be obtained with `mirage_cdtext_decoder_get_data()` and the appropriate callback function.

## Details

### struct MirageCdTextCoder

    struct MirageCdTextCoder;

All the fields in the MirageCdTextCoder structure are private to the MirageCdTextCoder implementation and should never be accessed directly.

### struct MirageCdTextCoderClass

    struct MirageCdTextCoderClass {
        MirageObjectClass parent_class;
    };

The class structure for the MirageCdTextCoder type.

MirageObjectClass `parent_class`; | the parent class

### MirageCdTextDataCallback ()

    gboolean            (*MirageCdTextDataCallback)         (gint code,
                                                             gint type,
                                                             gint track,
                                                             const guint8 *data,
                                                             gint data_len,
                                                             gpointer user_data);

Specifies the type of callback functions that can be passed to `mirage_cdtext_decoder_get_data()`.

`code` is the language code assigned to the block which data belongs to. `track` is the number of track to which data belongs to, or 0 if data is global (belongs to session/disc). `data` is buffer containing data and `data_len` is the length of data in the buffer.

`data` points to buffer that belongs to decoder and therefore should not be freed.

`code` : | language code. [in]
`type` : | pack type. [in]
`track` : | track number. [in]
`data` : | data. [in][array length=data_len]
`data_len` : | data length. [in]
`user_data` : | user data. [in][closure]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_decoder_get_block_info ()

    gboolean            mirage_cdtext_decoder_get_block_info
                                                            (MirageCdTextCoder *self,
                                                             gint block,
                                                             gint *code,
                                                             gint *charset,
                                                             gint *copyright,
                                                             GError **error);

Retrieves block information for CD-TEXT block specified by `block`. `block` must be a valid block number (0-7). Language code assigned to the block is stored in `code`, code of character set used within block is stored in `charset` and block's copyright flag is stored in `copyright`.

`self` : | a MirageCdTextCoder
`block` : | block number. [in]
`code` : | location to store language code, or `NULL`. [out][allow-none]
`charset` : | location to store character set, or `NULL`. [out][allow-none]
`copyright` : | location to store copyright flag, or `NULL`. [out][allow-none]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_decoder_get_data ()

    gboolean            mirage_cdtext_decoder_get_data      (MirageCdTextCoder *self,
                                                             gint block,
                                                             MirageCdTextDataCallback callback_func,
                                                             gpointer user_data);

Retrieves data for CD-TEXT block specified by `block`. `block` must be a valid block number (0-7). It calls `callback_func` for every data pack that has been encoded in the block.

If `callback_func` returns `FALSE`, the function immediately returns `FALSE`.

`self` : | a MirageCdTextCoder
`block` : | block number. [in]
`callback_func` : | callback function. [in][scope call]
`user_data` : | data to be passed to callback function. [in][closure]
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_decoder_init ()

    void                mirage_cdtext_decoder_init          (MirageCdTextCoder *self,
                                                             guint8 *buffer,
                                                             gint buflen);

Initializes CD-TEXT decoder. `buffer` is the buffer containing encoded CD-TEXT data and `buflen` is length of data in the buffer.

This function decodes CD-TEXT data and stores it in decoder's internal representation. Information about decoded CD-TEXT blocks and their data can be obtained via subsequent calls to `mirage_cdtext_decoder_get_block_info()` and `mirage_cdtext_decoder_get_data()`.

`self` : | a MirageCdTextCoder
`buffer` : | buffer containing encoded data. [in][array length=buflen]
`buflen` : | length of data in buffer. [in]

### mirage_cdtext_encoder_add_data ()

    void                mirage_cdtext_encoder_add_data      (MirageCdTextCoder *self,
                                                             gint code,
                                                             gint type,
                                                             gint track,
                                                             const guint8 *data,
                                                             gint data_len);

Adds data to the encoder. `code` is language code of the block the data should be added to. `type` denotes pack type and should be one of MirageLanguagePackTypes. `track` is track number the data belongs to, or 0 if data is global (belongs to disc/session). `data` is buffer containing data to be added, and `data_len` is length of data in the buffer.

This function does not perform any encoding yet; it merely adds the data into encoder's internal representation of CD-TEXT block.

### Note

Block needs to have its information set with `mirage_cdtext_encoder_set_block_info()` before data can be added to it.

`self` : | a MirageCdTextCoder
`code` : | language code. [in]
`type` : | data type. [in]
`track` : | track number. [in]
`data` : | data. [in][array length=data_len]
`data_len` : | data length. [in]

### mirage_cdtext_encoder_encode ()

    void                mirage_cdtext_encoder_encode        (MirageCdTextCoder *self,
                                                             guint8 **buffer,
                                                             gint *buflen);

Encodes the CD-TEXT data. Pointer to buffer containing the encoded data is stored in `buffer`, and length of data in buffer is stored in `buflen`.

Note that `buffer` is the same as the argument passed to `mirage_cdtext_encoder_init()`.

`self` : | a MirageCdTextCoder
`buffer` : | location to store buffer. [out][array length=buflen]
`buflen` : | location to store buffer length. [out]

### mirage_cdtext_encoder_init ()

    void                mirage_cdtext_encoder_init          (MirageCdTextCoder *self,
                                                             guint8 *buffer,
                                                             gint buflen);

Initializes CD-TEXT encoder.

`self` : | a MirageCdTextCoder
`buffer` : | buffer into which data will be encoded. [in][array length=buflen]
`buflen` : | buffer length. [in]

### mirage_cdtext_encoder_set_block_info ()

    gboolean            mirage_cdtext_encoder_set_block_info
                                                            (MirageCdTextCoder *self,
                                                             gint block,
                                                             gint code,
                                                             gint charset,
                                                             gint copyright,
                                                             GError **error);

Sets block information for CD-TEXT block specified by `block`. `block` must be a valid block number (0-7). `code` is the language code that is to be assigned to the block (e.g. 9 for English), `charset` denotes character set that is used within the block, and `copyright` is the copyright flag for the block.

`self` : | a MirageCdTextCoder
`block` : | block number. [in]
`code` : | language code. [in]
`charset` : | character set. [in]
`copyright` : | copyright flag. [in]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

## See Also

MirageLanguage, MirageSession