MirageSector: libMirage Reference Manual

## MirageSector MirageSector — Object representing a sector. |

## Functions

gboolean | mirage_sector_feed_data ()
gboolean | mirage_sector_extract_data ()
gint | mirage_sector_get_address ()
gboolean | mirage_sector_get_data ()
gboolean | mirage_sector_set_data ()
gboolean | mirage_sector_get_edc_ecc ()
gboolean | mirage_sector_set_edc_ecc ()
gboolean | mirage_sector_get_header ()
gboolean | mirage_sector_set_header ()
MirageSectorType | mirage_sector_get_sector_type ()
gboolean | mirage_sector_get_subchannel ()
gboolean | mirage_sector_set_subchannel ()
gboolean | mirage_sector_get_subheader ()
gboolean | mirage_sector_set_subheader ()
gboolean | mirage_sector_get_sync ()
gboolean | mirage_sector_set_sync ()
gboolean | mirage_sector_verify_lec ()
gboolean | mirage_sector_verify_subchannel_crc ()
void | mirage_sector_scramble ()

## Types and Values

| MirageSector
struct | MirageSectorClass
enum | MirageSectorType
enum | MirageSectorSubchannelFormat
enum | MirageSectorValidData

## Object Hierarchy

        GObject
        ╰── MirageObject
            ╰── MirageSector

## Implemented Interfaces

MirageSector implements MirageContextual.

## Includes

    #include <mirage-sector.h>

## Description

MirageSector object represents a sector. It provides access to the sector data, generating it if needed.

## Functions

### mirage_sector_feed_data ()

    gboolean
    mirage_sector_feed_data (MirageSector *self,
                             gint address,
                             MirageSectorType type,
                             const guint8 *main_data,
                             guint main_data_length,
                             MirageSectorSubchannelFormat subchannel_format,
                             const guint8 *subchannel_data,
                             guint subchannel_data_length,
                             gint ignore_data_mask,
                             GError **error);

Feeds data to sector. If `type` is `MIRAGE_SECTOR_RAW` or `MIRAGE_SECTOR_RAW_SCRAMBLED`, the real sector type is determined during feeding.

Intended for internal use.

#### Parameters

self | a MirageSector |
address | absolute disc address the sector represents. Given in sectors. | [in]
type | track type (one of MirageSectorType). | [in]
main_data | main data buffer. | [in]
main_data_length | length of data in main data buffer. | [in]
subchannel_format | subchannel data format. | [in]
subchannel_data | subchannel data buffer. | [in][allow-none]
subchannel_data_length | length of data in subchannel data buffer. | [in]
ignore_data_mask | a mask of MirageSectorValidData values, indicating which parts of main channel sector data, if any, should be ignored and regerated even though they are provided by the data feed. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_extract_data ()

    gboolean
    mirage_sector_extract_data (MirageSector *self,
                                const guint8 **main_data,
                                guint main_data_length,
                                MirageSectorSubchannelFormat subchannel_format,
                                const guint8 **subchannel_data,
                                guint subchannel_data_length,
                                GError **error);

Extracts data from sector. Which parts of main channel data are extracted depends on provided `main_data_length` .

Intended for internal use.

#### Parameters

self | a MirageSector |
main_data | location to store pointer to main data buffer. | [out][transfer none]
main_data_length | requested length of data in main data buffer. | [in]
subchannel_format | requested subchannel data format. | [out]
subchannel_data | location to store pointer to subchannel data buffer, or `NULL`. | [in][transfer none][allow-none]
subchannel_data_length | requested length of data in subchannel data buffer. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_get_address ()

    gint
    mirage_sector_get_address (MirageSector *self);

Retrieves absolute disc address of the sector.

#### Parameters

self | a MirageSector |

#### Returns

sector address

### mirage_sector_get_data ()

    gboolean
    mirage_sector_get_data (MirageSector *self,
                            const guint8 **ret_buf,
                            gint *ret_len,
                            GError **error);

Retrieves sector's user data. The pointer to appropriate location in sector's data buffer is stored into `ret_buf` ; therefore, the buffer should not be modified.

#### Parameters

self | a MirageSector |
ret_buf | location to store pointer to buffer containing user data, or `NULL`. | [out][transfer none][allow-none][array length=ret_len]
ret_len | location to store length of user data, or `NULL`. Length is given in bytes. | [out][allow-none]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_set_data ()

    gboolean
    mirage_sector_set_data (MirageSector *self,
                            const guint8 *buf,
                            gint len,
                            GError **error);

Sets sector's user data to that stored in `buf` .

#### Parameters

self | a MirageSector |
buf | buffer containing user data. | [in][array length=len]
len | length of user data. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_get_edc_ecc ()

    gboolean
    mirage_sector_get_edc_ecc (MirageSector *self,
                               const guint8 **ret_buf,
                               gint *ret_len,
                               GError **error);

Retrieves sector's EDC/ECC data. The pointer to appropriate location in sector's data buffer is stored into `ret_buf` ; therefore, the buffer should not be modified.

If EDC/ECC data is not provided by image file(s), it is generated.

#### Parameters

self | a MirageSector |
ret_buf | location to store pointer to buffer containing EDC/ECC data, or `NULL`. | [out][transfer none][allow-none][array length=ret_len]
ret_len | location to store length of EDC/ECC data, or `NULL`. Length is given in bytes. | [out][allow-none]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_set_edc_ecc ()

    gboolean
    mirage_sector_set_edc_ecc (MirageSector *self,
                               const guint8 *buf,
                               gint len,
                               GError **error);

Sets sector's EDC/ECC data to that stored in `buf` .

#### Parameters

self | a MirageSector |
buf | buffer containing EDC/ECC data. | [in][array length=len]
len | length of EDC/ECC data. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_get_header ()

    gboolean
    mirage_sector_get_header (MirageSector *self,
                              const guint8 **ret_buf,
                              gint *ret_len,
                              GError **error);

Retrieves sector's header. The pointer to appropriate location in sector's data buffer is stored into `ret_buf` ; therefore, the buffer should not be modified.

If header is not provided by image file(s), it is generated.

#### Parameters

self | a MirageSector |
ret_buf | location to store pointer to buffer containing header, or `NULL`. | [out][transfer none][allow-none][array length=ret_len]
ret_len | location to store length of header, or `NULL`. Length is given in bytes. | [out][allow-none]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_set_header ()

    gboolean
    mirage_sector_set_header (MirageSector *self,
                              const guint8 *buf,
                              gint len,
                              GError **error);

Sets sector's header to that stored in `buf` .

#### Parameters

self | a MirageSector |
buf | buffer containing header. | [in][array length=len]
len | length of header. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_get_sector_type ()

    MirageSectorType
    mirage_sector_get_sector_type (MirageSector *self);

Retrieves sector type (track mode); one of MirageSectorType.

#### Parameters

self | a MirageSector |

#### Returns

sector type (track mode)

### mirage_sector_get_subchannel ()

    gboolean
    mirage_sector_get_subchannel (MirageSector *self,
                                  MirageSectorSubchannelFormat format,
                                  const guint8 **ret_buf,
                                  gint *ret_len,
                                  GError **error);

Retrieves sector's subchannel. `format` must be one of MirageSectorSubchannelFormat. The pointer to appropriate location in sector's data buffer is stored into `ret_buf` ; therefore, the buffer should not be modified.

If subchannel is not provided by image file(s), it is generated.

#### Parameters

self | a MirageSector |
format | subchannel format. | [in]
ret_buf | location to store pointer to buffer containing subchannel, or `NULL`. | [out][transfer none][allow-none][array length=ret_len]
ret_len | location to store length of subchannel data, or `NULL`. Length is given in bytes. | [out][allow-none]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_set_subchannel ()

    gboolean
    mirage_sector_set_subchannel (MirageSector *self,
                                  MirageSectorSubchannelFormat format,
                                  const guint8 *buf,
                                  gint len,
                                  GError **error);

Sets sector's subchannel data to that stored in `buf` . `format` must be one of MirageSectorSubchannelFormat.

#### Parameters

self | a MirageSector |
format | subchannel format. | [in]
buf | buffer containing subchannel data. | [in][array length=len]
len | length of subchannel data. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_get_subheader ()

    gboolean
    mirage_sector_get_subheader (MirageSector *self,
                                 const guint8 **ret_buf,
                                 gint *ret_len,
                                 GError **error);

Retrieves sector's subheader. The pointer to appropriate location in sector's data buffer is stored into `ret_buf` ; therefore, the buffer should not be modified.

If subheader is not provided by image file(s), it is generated.

#### Parameters

self | a MirageSector |
ret_buf | location to store pointer to buffer containing subheader, or `NULL`. | [out][transfer none][allow-none][array length=ret_len]
ret_len | location to store length of subheader, or `NULL`. Length is given in bytes. | [out][allow-none]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_set_subheader ()

    gboolean
    mirage_sector_set_subheader (MirageSector *self,
                                 const guint8 *buf,
                                 gint len,
                                 GError **error);

Sets sector's subheader to that stored in `buf` .

#### Parameters

self | a MirageSector |
buf | buffer containing subheader. | [in][array length=len]
len | length of subheader. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_get_sync ()

    gboolean
    mirage_sector_get_sync (MirageSector *self,
                            const guint8 **ret_buf,
                            gint *ret_len,
                            GError **error);

Retrieves sector's sync pattern. The pointer to appropriate location in sector's data buffer is stored into `ret_buf` ; therefore, the buffer should not be modified.

If sync pattern is not provided by image file(s), it is generated.

#### Parameters

self | a MirageSector |
ret_buf | location to store pointer to buffer containing sync pattern, or `NULL`. | [out][transfer none][allow-none][array length=ret_len]
ret_len | location to store length of sync pattern, or `NULL`. Length is given in bytes. | [out][allow-none]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_set_sync ()

    gboolean
    mirage_sector_set_sync (MirageSector *self,
                            const guint8 *buf,
                            gint len,
                            GError **error);

Sets sector's sync pattern to that stored in `buf` .

#### Parameters

self | a MirageSector |
buf | buffer containing sync pattern. | [in][array length=len]
len | length of sync pattern. | [in]
error | location to store error, or `NULL`. | [out][allow-none]

#### Returns

`TRUE` on success, `FALSE` on failure

### mirage_sector_verify_lec ()

    gboolean
    mirage_sector_verify_lec (MirageSector *self);

Verifies the sector data in terms of L-EC error detection/correction. Data sectors (Mode 1, Mode 2 Form 1 and Mode 2 Form 2) contain error detection/error correction codes which is part of so called layered error correction. This function calculates the EDC for sector data and compares it with EDC provided by the image file.

As a result of comparison, the sectors with intentionally faulty EDC (and possibly ECC, though ECC is not verified) can be discovered.

This function requires EDC/ECC data to be provided by the image. If it is not provided, it would be generated by MirageSector on first access via `mirage_sector_get_edc_ecc()` using the same algorithm as the one used by this function. Therefore, in case of EDC/ECC data missing, the verification automatically succeeds.

#### Parameters

self | a MirageSector |

#### Returns

`TRUE` if sector passes verification (i.e. no L-EC errors are detected) otherwise `FALSE`

### mirage_sector_verify_subchannel_crc ()

    gboolean
    mirage_sector_verify_subchannel_crc (MirageSector *self);

Verifies the Q subchannel's CRC for the sector.

As a result of comparison, the sectors with intentionally faulty Q subchannel can be discovered.

This function requires subchannel data to be provided by the image. If it is not provided, it would be generated by MirageSector on first access via `mirage_sector_get_subchannel()` using the same algorithm as the one used by this function. Therefore, in case of subchannel data missing, the verification automatically succeeds.

#### Parameters

self | a MirageSector |

#### Returns

`TRUE` if sector's Q subchannel CRC passes verification otherwise `FALSE`

### mirage_sector_scramble ()

    void
    mirage_sector_scramble (MirageSector *self);

Scrambles 2340 bytes of sector data after sync pattern, using scrambler from ECMA-130 Annex B. Running this function on already-scrambled sector results in unscrambling.

#### Parameters

self | a MirageSector |

## Types and Values

### MirageSector

    typedef struct _MirageSector MirageSector;

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

### struct MirageSectorClass

    struct MirageSectorClass {
        MirageObjectClass parent_class;
    };

The class structure for the MirageSector type.

#### Members

### enum MirageSectorType

Sector type. Also implies track mode.

#### Members

MIRAGE_SECTOR_MODE0 | Mode 0 sector |
MIRAGE_SECTOR_AUDIO | Audio sector |
MIRAGE_SECTOR_MODE1 | Mode 1 sector |
MIRAGE_SECTOR_MODE2 | Mode 2 Formless sector |
MIRAGE_SECTOR_MODE2_FORM1 | Mode 2 Form 1 sector |
MIRAGE_SECTOR_MODE2_FORM2 | Mode 2 Form 2 sector |
MIRAGE_SECTOR_MODE2_MIXED | Mode 2 Mixed sector |
MIRAGE_SECTOR_RAW | raw sector (automatic sector type detection) |
MIRAGE_SECTOR_RAW_SCRAMBLED | scrambled raw sector (automatic sector type detection) |

### enum MirageSectorSubchannelFormat

Subchannel selection flags.

#### Members

MIRAGE_SUBCHANNEL_NONE | no subchannel |
MIRAGE_SUBCHANNEL_PW | PW subchannel; 96 bytes, interleaved P-W |
MIRAGE_SUBCHANNEL_Q | Q subchannel; 16 bytes, Q subchannel |
MIRAGE_SUBCHANNEL_RW | RW subchannel; 96 bytes, cooked R-W |

### enum MirageSectorValidData

Sector data validity flags.

#### Members

MIRAGE_VALID_SYNC | sync pattern valid |
MIRAGE_VALID_HEADER | header valid |
MIRAGE_VALID_SUBHEADER | subheader valid |
MIRAGE_VALID_DATA | user data valid |
MIRAGE_VALID_EDC_ECC | EDC/ECC data valid |
MIRAGE_VALID_SUBCHAN | subchannel valid |

## See Also

MirageTrack