## MirageSector MirageSector — Object representing a sector. |

## Synopsis

    #include <mirage-sector.h>

                        MirageSector;
    struct              MirageSectorClass;
    enum                MirageSectorSubchannelFormat;
    enum                MirageSectorValidData;
    gboolean            mirage_sector_feed_data             (MirageSector *self,
                                                             gint address,
                                                             MirageTrack *track,
                                                             GError **error);
    gboolean            mirage_sector_get_data              (MirageSector *self,
                                                             const guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_edc_ecc           (MirageSector *self,
                                                             const guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_header            (MirageSector *self,
                                                             const guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    MirageTrackModes    mirage_sector_get_sector_type       (MirageSector *self);
    gboolean            mirage_sector_get_subchannel        (MirageSector *self,
                                                             MirageSectorSubchannelFormat format,
                                                             const guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_subheader         (MirageSector *self,
                                                             const guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_sync              (MirageSector *self,
                                                             const guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_verify_lec            (MirageSector *self);
    gboolean            mirage_sector_verify_subchannel_crc (MirageSector *self);

## Object Hierarchy

      GObject
       +----MirageObject
             +----MirageSector

## Implemented Interfaces

MirageSector implements MirageContextual.

## Description

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

## Details

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

MirageObjectClass `parent_class`; | the parent class

### enum MirageSectorSubchannelFormat

    typedef enum {
        MIRAGE_SUBCHANNEL_PW = 0x01,
        MIRAGE_SUBCHANNEL_PQ = 0x02,
        MIRAGE_SUBCHANNEL_RW = 0x03
    } MirageSectorSubchannelFormat;

Subchannel selection flags.

`MIRAGE_SUBCHANNEL_PW` | PW subchannel; 96 bytes, interleaved P-W
`MIRAGE_SUBCHANNEL_PQ` | PQ subchannel; 16 bytes, Q subchannel
`MIRAGE_SUBCHANNEL_RW` | RW subchannel; 96 bytes, deinterleaved R-W

### enum MirageSectorValidData

    typedef enum {
        MIRAGE_VALID_SYNC      = 0x01,
        MIRAGE_VALID_HEADER    = 0x02,
        MIRAGE_VALID_SUBHEADER = 0x04,
        MIRAGE_VALID_DATA      = 0x08,
        MIRAGE_VALID_EDC_ECC   = 0x10,
        MIRAGE_VALID_SUBCHAN   = 0x20,
    } MirageSectorValidData;

Sector data validity flags.

`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

### mirage_sector_feed_data ()

    gboolean            mirage_sector_feed_data             (MirageSector *self,
                                                             gint address,
                                                             MirageTrack *track,
                                                             GError **error);

Feeds data to sector. It finds appropriate fragment to feed from, reads data into sector object and sets data validity flags.

### Note

Intended for internal use.

`self` : | a MirageSector
`address` : | address the sector represents. Given in sectors. [in]
`track` : | track the sector belongs to. [in]
`error` : | location to store error, or `NULL`. [out][allow-none]
Returns : | `TRUE` on success, `FALSE` on failure

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

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

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

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

    MirageTrackModes    mirage_sector_get_sector_type       (MirageSector *self);

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

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

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

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

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

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

`self` : | a MirageSector
Returns : | `TRUE` if sector's Q subchannel CRC passes verification otherwise `FALSE`

## See Also

MirageTrack