MirageCdTextCoder: libMirage Reference Manual

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

## Functions

gboolean | (*MirageCdTextDataCallback) ()
gboolean | mirage_cdtext_decoder_get_block_info ()
gboolean | mirage_cdtext_decoder_get_data ()
void | mirage_cdtext_decoder_init ()
void | mirage_cdtext_encoder_add_data ()
void | mirage_cdtext_encoder_encode ()
void | mirage_cdtext_encoder_init ()
gboolean | mirage_cdtext_encoder_set_block_info ()

## Types and Values

struct | MirageCdTextCoder
struct | MirageCdTextCoderClass

## Object Hierarchy

        GObject
        ╰── MirageObject
            ╰── MirageCdTextCoder

## Implemented Interfaces

MirageCdTextCoder implements MirageContextual.

## Includes

    #include <mirage-cdtext-coder.h>

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

## Functions

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

#### Parameters

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

#### Parameters

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

#### Parameters

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()`.

#### Parameters

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

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

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

## Types and Values

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

#### Members

## See Also

MirageLanguage, MirageSession