MIRAGE_Sector object

## MIRAGE_Sector object MIRAGE_Sector object — Object representing a sector |

## Synopsis

    #include <mirage.h>

    enum                MIRAGE_Sector_MCSB;
    enum                MIRAGE_Sector_SubchannelFormat;
    enum                MIRAGE_Sector_ValidData;
                        MIRAGE_Sector;
    gboolean            mirage_sector_feed_data             (MIRAGE_Sector *self,
                                                             gint address,
                                                             GObject *track,
                                                             GError **error);
    gboolean            mirage_sector_get_sector_type       (MIRAGE_Sector *self,
                                                             gint *type,
                                                             GError **error);
    gboolean            mirage_sector_get_sync              (MIRAGE_Sector *self,
                                                             guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_header            (MIRAGE_Sector *self,
                                                             guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_subheader         (MIRAGE_Sector *self,
                                                             guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_data              (MIRAGE_Sector *self,
                                                             guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_edc_ecc           (MIRAGE_Sector *self,
                                                             guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);
    gboolean            mirage_sector_get_subchannel        (MIRAGE_Sector *self,
                                                             gint format,
                                                             guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);

## Object Hierarchy

      GObject
       +----MIRAGE_Object
             +----MIRAGE_Sector

## Description

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

## Details

### enum MIRAGE_Sector_MCSB

    typedef enum {
        MIRAGE_MCSB_SYNC      = 0x80,
        MIRAGE_MCSB_SUBHEADER = 0x40,
        MIRAGE_MCSB_HEADER    = 0x20,
        MIRAGE_MCSB_DATA      = 0x10,
        MIRAGE_MCSB_EDC_ECC   = 0x08,
        MIRAGE_MCSB_C2_2      = 0x04,
        MIRAGE_MCSB_C2_1      = 0x02,
    } MIRAGE_Sector_MCSB;

Main channel selection flags.

`MIRAGE_MCSB_SYNC` | sync pattern
`MIRAGE_MCSB_SUBHEADER` | subheader
`MIRAGE_MCSB_HEADER` | header
`MIRAGE_MCSB_DATA` | user data
`MIRAGE_MCSB_EDC_ECC` | EDC/ECC code
`MIRAGE_MCSB_C2_2` | C2 layer 2 error
`MIRAGE_MCSB_C2_1` | C2 layer 1 error

### enum MIRAGE_Sector_SubchannelFormat

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

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 MIRAGE_Sector_ValidData

    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,
    } MIRAGE_Sector_ValidData;

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

    typedef struct _MIRAGE_Sector MIRAGE_Sector;

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

### mirage_sector_feed_data ()

    gboolean            mirage_sector_feed_data             (MIRAGE_Sector *self,
                                                             gint address,
                                                             GObject *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 MIRAGE_Sector
`address` : | address the sector represents. Given in sectors.
`track` : | track the sector belongs to
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_sector_get_sector_type ()

    gboolean            mirage_sector_get_sector_type       (MIRAGE_Sector *self,
                                                             gint *type,
                                                             GError **error);

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

`self` : | a MIRAGE_Sector
`type` : | location to store sector type
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_sector_get_sync ()

    gboolean            mirage_sector_get_sync              (MIRAGE_Sector *self,
                                                             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`; as such, it should not be freed.

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

`self` : | a MIRAGE_Sector
`ret_buf` : | location to store pointer to buffer containing sync pattern, or `NULL`
`ret_len` : | location to store length of sync pattern, or `NULL`. Length is given in bytes.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_sector_get_header ()

    gboolean            mirage_sector_get_header            (MIRAGE_Sector *self,
                                                             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`; as such, it should not be freed.

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

`self` : | a MIRAGE_Sector
`ret_buf` : | location to store pointer to buffer containing header, or `NULL`
`ret_len` : | location to store length of header, or `NULL`. Length is given in bytes.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_sector_get_subheader ()

    gboolean            mirage_sector_get_subheader         (MIRAGE_Sector *self,
                                                             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`; as such, it should not be freed.

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

`self` : | a MIRAGE_Sector
`ret_buf` : | location to store pointer to buffer containing subheader, or `NULL`
`ret_len` : | location to store length of subheader, or `NULL`. Length is given in bytes.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_sector_get_data ()

    gboolean            mirage_sector_get_data              (MIRAGE_Sector *self,
                                                             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`; as such, it should not be freed.

`self` : | a MIRAGE_Sector
`ret_buf` : | location to store pointer to buffer containing user data, or `NULL`
`ret_len` : | location to store length of user data, or `NULL`. Length is given in bytes.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_sector_get_edc_ecc ()

    gboolean            mirage_sector_get_edc_ecc           (MIRAGE_Sector *self,
                                                             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`; as such, it should not be freed.

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

`self` : | a MIRAGE_Sector
`ret_buf` : | location to store pointer to buffer containing EDC/ECC data, or `NULL`
`ret_len` : | location to store length of EDC/ECC data, or `NULL`. Length is given in bytes.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

### mirage_sector_get_subchannel ()

    gboolean            mirage_sector_get_subchannel        (MIRAGE_Sector *self,
                                                             gint format,
                                                             guint8 **ret_buf,
                                                             gint *ret_len,
                                                             GError **error);

Retrieves sector's subchannel. `type` must be one of MIRAGE_Sector_SubchannelFormat. The pointer to appropriate location in sector's data buffer is stored into `ret_buf`; as such, it should not be freed.

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

`self` : | a MIRAGE_Sector
`format` : | subchannel format
`ret_buf` : | location to store pointer to buffer containing subchannel, or `NULL`
`ret_len` : | location to store length of subchannel data, or `NULL`. Length is given in bytes.
`error` : | location to store error, or `NULL`
Returns : | `TRUE` on success, `FALSE` on failure

## See Also

MIRAGE_Track