MIRAGE_CDTextEncDec object

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

## Synopsis

    #include <mirage.h>

    gboolean            (*MIRAGE_CDTextDataCallback)        (gint langcode,
                                                             gint type,
                                                             gint track,
                                                             guint8 *data,
                                                             gint data_len,
                                                             gpointer user_data);
                        MIRAGE_CDTextEncDec;
    gboolean            mirage_cdtext_encoder_init          (MIRAGE_CDTextEncDec *self,
                                                             guint8 *buffer,
                                                             gint buflen,
                                                             GError **error);
    gboolean            mirage_cdtext_encoder_set_block_info
                                                            (MIRAGE_CDTextEncDec *self,
                                                             gint block,
                                                             gint langcode,
                                                             gint charset,
                                                             gint copyright,
                                                             GError **error);
    gboolean            mirage_cdtext_encoder_add_data      (MIRAGE_CDTextEncDec *self,
                                                             gint langcode,
                                                             gint type,
                                                             gint track,
                                                             guint8 *data,
                                                             gint data_len,
                                                             GError **error);
    gboolean            mirage_cdtext_encoder_encode        (MIRAGE_CDTextEncDec *self,
                                                             guint8 **buffer,
                                                             gint *buflen,
                                                             GError **error);
    gboolean            mirage_cdtext_decoder_init          (MIRAGE_CDTextEncDec *self,
                                                             guint8 *buffer,
                                                             gint buflen,
                                                             GError **error);
    gboolean            mirage_cdtext_decoder_get_block_info
                                                            (MIRAGE_CDTextEncDec *self,
                                                             gint block,
                                                             gint *langcode,
                                                             gint *charset,
                                                             gint *copyright,
                                                             GError **error);
    gboolean            mirage_cdtext_decoder_get_data      (MIRAGE_CDTextEncDec *self,
                                                             gint block,
                                                             MIRAGE_CDTextDataCallback callback_func,
                                                             gpointer user_data,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MIRAGE_Object
             +----MIRAGE_CDTextEncDec

## Description

MIRAGE_CDTextEncDec object is a general-purpose CD-TEXT encoder/decoder. It was designed to be used by MIRAGE_Session objects to encode and decode CD-TEXT data, but it should be suitable for use in other applications as well.

It is losely 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 MIRAGE_CDTextEncDec 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 MIRAGE_CDTextEncDec 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

### MIRAGE_CDTextDataCallback ()

    gboolean            (*MIRAGE_CDTextDataCallback)        (gint langcode,
                                                             gint type,
                                                             gint track,
                                                             guint8 *data,
                                                             gint data_len,
                                                             gpointer user_data);

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

`langcode` 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.

`langcode` : | language code
`type` : | pack type
`track` : | track number
`data` : | data
`data_len` : | data length
`user_data` : | user data
Returns : | `TRUE` on success, `FALSE` on failure

### MIRAGE_CDTextEncDec

    typedef struct _MIRAGE_CDTextEncDec MIRAGE_CDTextEncDec;

Contains private data only, and should be accessed using the functions below.

### mirage_cdtext_encoder_init ()

    gboolean            mirage_cdtext_encoder_init          (MIRAGE_CDTextEncDec *self,
                                                             guint8 *buffer,
                                                             gint buflen,
                                                             GError **error);

Initializes CD-TEXT encoder.

`self` : | a MIRAGE_CDTextEncDec
`buffer` : | buffer into which data will be encoded
`buflen` : | buffer length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_encoder_set_block_info ()

    gboolean            mirage_cdtext_encoder_set_block_info
                                                            (MIRAGE_CDTextEncDec *self,
                                                             gint block,
                                                             gint langcode,
                                                             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). `langcode` 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 MIRAGE_CDTextEncDec
`block` : | block number
`langcode` : | language code
`charset` : | character set
`copyright` : | copyright flag
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_encoder_add_data ()

    gboolean            mirage_cdtext_encoder_add_data      (MIRAGE_CDTextEncDec *self,
                                                             gint langcode,
                                                             gint type,
                                                             gint track,
                                                             guint8 *data,
                                                             gint data_len,
                                                             GError **error);

Adds data to the encoder. `langcode` is language code of the block the data should be added to. `type` denotes pack type and should be one of MIRAGE_Language_PackTypes. `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 MIRAGE_CDTextEncDec
`langcode` : | language code
`type` : | data type
`track` : | track number
`data` : | data
`data_len` : | data length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_encoder_encode ()

    gboolean            mirage_cdtext_encoder_encode        (MIRAGE_CDTextEncDec *self,
                                                             guint8 **buffer,
                                                             gint *buflen,
                                                             GError **error);

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 MIRAGE_CDTextEncDec
`buffer` : | location to store buffer
`buflen` : | location to store buffer length
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_decoder_init ()

    gboolean            mirage_cdtext_decoder_init          (MIRAGE_CDTextEncDec *self,
                                                             guint8 *buffer,
                                                             gint buflen,
                                                             GError **error);

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 MIRAGE_CDTextEncDec
`buffer` : | buffer containing encoded data
`buflen` : | length of data in buffer
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_decoder_get_block_info ()

    gboolean            mirage_cdtext_decoder_get_block_info
                                                            (MIRAGE_CDTextEncDec *self,
                                                             gint block,
                                                             gint *langcode,
                                                             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 `langcode`, code of character set used within block is stored in `charset` and block's copyright flag is stored in `copyright`.

`self` : | a MIRAGE_CDTextEncDec
`block` : | block number
`langcode` : | location to store language code
`charset` : | location to store character set
`copyright` : | location to store copyright flag
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_cdtext_decoder_get_data ()

    gboolean            mirage_cdtext_decoder_get_data      (MIRAGE_CDTextEncDec *self,
                                                             gint block,
                                                             MIRAGE_CDTextDataCallback callback_func,
                                                             gpointer user_data,
                                                             GError **error);

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` and `error` is set to `MIRAGE_E_ITERCANCELLED`.

`self` : | a MIRAGE_CDTextEncDec
`block` : | block number
`callback_func` : | callback function
`user_data` : | data to be passed to callback function
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

## See Also

MIRAGE_Language, MIRAGE_Session