## Device

Device — Data structure holding information about the iPod (model, mount point, etc.)

## Synopsis

                        Itdb_Device;
    Itdb_Device *       itdb_device_new                     (void);
    void                itdb_device_free                    (Itdb_Device *device);
    void                itdb_device_set_mountpoint          (Itdb_Device *device,
                                                             const gchar *mp);
    gboolean            itdb_device_supports_artwork        (const Itdb_Device *device);
    gboolean            itdb_device_supports_chapter_image  (const Itdb_Device *device);
    gboolean            itdb_device_supports_photo          (const Itdb_Device *device);
    gboolean            itdb_device_supports_podcast        (const Itdb_Device *device);
    gboolean            itdb_device_supports_video          (const Itdb_Device *device);
                        Itdb_IpodInfo;
    const Itdb_IpodInfo * itdb_device_get_ipod_info         (const Itdb_Device *device);
    const Itdb_IpodInfo * itdb_info_get_ipod_info_table     (void);
    enum                Itdb_IpodGeneration;
    const gchar *       itdb_info_get_ipod_generation_string
                                                            (Itdb_IpodGeneration generation);
    enum                Itdb_IpodModel;
    const gchar *       itdb_info_get_ipod_model_name_string
                                                            (Itdb_IpodModel model);
                        Itdb_ArtworkFormat;
    gboolean            itdb_device_read_sysinfo            (Itdb_Device *device);
    gchar *             itdb_device_get_sysinfo             (const Itdb_Device *device,
                                                             const gchar *field);
    void                itdb_device_set_sysinfo             (Itdb_Device *device,
                                                             const gchar *field,
                                                             const gchar *value);
    gboolean            itdb_device_write_sysinfo           (Itdb_Device *device,
                                                             GError **error);

## Description

These functions are for reading and setting information about the iPod.

## Details

### Itdb_Device

    typedef struct {
        gchar *mountpoint;
        gint   musicdirs;
        guint  byte_order;
        GHashTable *sysinfo;
        SysInfoIpodProperties *sysinfo_extended;
        gboolean sysinfo_changed;
        gint timezone_shift;
        void *iphone_sync_context;
    } Itdb_Device;

Structure representing an iPod device

gchar *`mountpoint`; | The mountpoint of the iPod
gint `musicdirs`; | The number of /iPod_Control/Music/F.. dirs
guint `byte_order`; | G_LITTLE_ENDIAN "regular" endianness G_BIG_ENDIAN "reversed" endianness (e.g. mobile phone iTunesDBs)
GHashTable *`sysinfo`; | A hash with key/value pairs of all entries in Device/SysInfo
SysInfoIpodProperties *`sysinfo_extended`; | The parsed content of SysInfoExtended, which can be NULL
gboolean `sysinfo_changed`; | True if the sysinfo hash been changed by the user, false otherwise. (see `itdb_set_sysinfo()`)
gint `timezone_shift`; | The difference in seconds between the current timezone and UTC
void *`iphone_sync_context`; |

Since 0.4.0

### itdb_device_new ()

    Itdb_Device *       itdb_device_new                     (void);

Creates a new Itdb_Device structure

Returns : | a newly allocated Itdb_Device which must be freed with `itdb_device_free()` when no longer needed

Since 0.4.0

### itdb_device_free ()

    void                itdb_device_free                    (Itdb_Device *device);

Frees memory used by `device`

`device` : | an Itdb_Device

Since 0.4.0

### itdb_device_set_mountpoint ()

    void                itdb_device_set_mountpoint          (Itdb_Device *device,
                                                             const gchar *mp);

Sets the mountpoint of `device` to `mp` and update the cached device information (in particular, re-read the SysInfo file)

### Warning

Calling this function invalidates all the artwork in the Itdb_iTunesDB database using this Itdb_Device. Trying to access this artwork will result in memory corruption. It's recommended to use `itdb_set_mountpoint()` instead which will clean the invalidated artwork for you.

.

`device` : | an Itdb_Device
`mp` : | the new mount point

Since 0.4.0

### itdb_device_supports_artwork ()

    gboolean            itdb_device_supports_artwork        (const Itdb_Device *device);

Indicates whether `device` can display artwork or not. When dealing with a non-art capable iPod, no artwork data will be written to the iPod so you can spare calls to the artwork handling methods.

`device` : | an Itdb_Device
Returns : | true if `device` can display artwork.

Since 0.5.0

### itdb_device_supports_chapter_image ()

    gboolean            itdb_device_supports_chapter_image  (const Itdb_Device *device);

Indicates whether `device` can display chapter images or not.

`device` : | an Itdb_Device
Returns : | true if `device` can display chapter images.

Since 0.7.2

### itdb_device_supports_photo ()

    gboolean            itdb_device_supports_photo          (const Itdb_Device *device);

Indicates whether `device` can display photos or not.

`device` : | an Itdb_Device
Returns : | true if `device` can display photos.

Since 0.5.0

### itdb_device_supports_podcast ()

    gboolean            itdb_device_supports_podcast        (const Itdb_Device *device);

Indicates whether `device` can play podcasts or not.

`device` : | an Itdb_Device
Returns : | true if `device` can play podcasts.

Since 0.7.2

### itdb_device_supports_video ()

    gboolean            itdb_device_supports_video          (const Itdb_Device *device);

Indicates whether `device` can play videos or not.

`device` : | an Itdb_Device
Returns : | true if `device` can play videos.

Since 0.7.0

### Itdb_IpodInfo

    typedef struct {
        const gchar *model_number;
        const double capacity;
        const Itdb_IpodModel ipod_model;
        const Itdb_IpodGeneration ipod_generation;
        const guint musicdirs;
        /* reserved for future use */
        const gint32 reserved_int1;
        const gint32 reserved_int2;
        gconstpointer reserved1;
        gconstpointer reserved2;
    } Itdb_IpodInfo;

Structure representing information about an iPod

const gchar *`model_number`; | The model number. This is abbreviated. If the first character is not numeric, it is ommited. e.g. "MA350 -> A350", "M9829 -> 9829"
const double `capacity`; | The iPod's capacity in gigabytes
const Itdb_IpodModel `ipod_model`; | The iPod model
const Itdb_IpodGeneration `ipod_generation`; | The iPod generation
const guint `musicdirs`; | The number of music (Fnn) dirs created by iTunes. The exact number seems to be version dependent. Therefore, the numbers here represent a mixture of reported values and common sense. Note: this number does not necessarily represent the number of dirs present on a particular iPod. It is used when setting up a new iPod from scratch.
const gint32 `reserved_int1`; | Reserved for future use
const gint32 `reserved_int2`; | Reserved for future use
gconstpointer `reserved1`; | Reserved for future use
gconstpointer `reserved2`; | Reserved for future use

Since 0.4.0

### itdb_device_get_ipod_info ()

    const Itdb_IpodInfo * itdb_device_get_ipod_info         (const Itdb_Device *device);

Retrieve the Itdb_IpodInfo entry for this iPod

`device` : | an Itdb_Device
Returns : | the Itdb_IpodInfo entry for this iPod

Since 0.4.0

### itdb_info_get_ipod_info_table ()

    const Itdb_IpodInfo * itdb_info_get_ipod_info_table     (void);

Return a pointer to the start of valid iPod model descriptions, which is an array of Itdb_IpodInfo entries. This can be useful if you want to build a list of all iPod models known to the current libgpod.

Returns : | a pointer to the array of Itdb_IpodInfo entries.

Since 0.4.0

### enum Itdb_IpodGeneration

    typedef enum {
        ITDB_IPOD_GENERATION_UNKNOWN,
        ITDB_IPOD_GENERATION_FIRST,
        ITDB_IPOD_GENERATION_SECOND,
        ITDB_IPOD_GENERATION_THIRD,
        ITDB_IPOD_GENERATION_FOURTH,
        ITDB_IPOD_GENERATION_PHOTO,
        ITDB_IPOD_GENERATION_MOBILE,
        ITDB_IPOD_GENERATION_MINI_1,
        ITDB_IPOD_GENERATION_MINI_2,
        ITDB_IPOD_GENERATION_SHUFFLE_1,
        ITDB_IPOD_GENERATION_SHUFFLE_2,
        ITDB_IPOD_GENERATION_SHUFFLE_3,
        ITDB_IPOD_GENERATION_NANO_1,
        ITDB_IPOD_GENERATION_NANO_2,
        ITDB_IPOD_GENERATION_NANO_3,
        ITDB_IPOD_GENERATION_NANO_4,
        ITDB_IPOD_GENERATION_VIDEO_1,
        ITDB_IPOD_GENERATION_VIDEO_2,
        ITDB_IPOD_GENERATION_CLASSIC_1,
        ITDB_IPOD_GENERATION_CLASSIC_2,
        ITDB_IPOD_GENERATION_TOUCH_1,
        ITDB_IPOD_GENERATION_IPHONE_1,
        ITDB_IPOD_GENERATION_SHUFFLE_4,
        ITDB_IPOD_GENERATION_TOUCH_2,
        ITDB_IPOD_GENERATION_IPHONE_2,
        ITDB_IPOD_GENERATION_IPHONE_3,
        ITDB_IPOD_GENERATION_CLASSIC_3,
        ITDB_IPOD_GENERATION_NANO_5,
        ITDB_IPOD_GENERATION_TOUCH_3
    } Itdb_IpodGeneration;

iPod generation information

See http://support.apple.com/kb/HT1353 and http://en.wikipedia.org/wiki/IPod for more details.

`ITDB_IPOD_GENERATION_UNKNOWN` | Unknown iPod
`ITDB_IPOD_GENERATION_FIRST` | First Generation iPod
`ITDB_IPOD_GENERATION_SECOND` | Second Generation iPod
`ITDB_IPOD_GENERATION_THIRD` | Third Generation iPod
`ITDB_IPOD_GENERATION_FOURTH` | Fourth Generation iPod
`ITDB_IPOD_GENERATION_PHOTO` | Photo iPod
`ITDB_IPOD_GENERATION_MOBILE` | Mobile iPod
`ITDB_IPOD_GENERATION_MINI_1` | First Generation iPod Mini
`ITDB_IPOD_GENERATION_MINI_2` | Second Generation iPod Mini
`ITDB_IPOD_GENERATION_SHUFFLE_1` | First Generation iPod Shuffle
`ITDB_IPOD_GENERATION_SHUFFLE_2` | Second Generation iPod Shuffle
`ITDB_IPOD_GENERATION_SHUFFLE_3` | Third Generation iPod Shuffle
`ITDB_IPOD_GENERATION_NANO_1` | First Generation iPod Nano
`ITDB_IPOD_GENERATION_NANO_2` | Second Generation iPod Nano
`ITDB_IPOD_GENERATION_NANO_3` | Third Generation iPod Nano
`ITDB_IPOD_GENERATION_NANO_4` | Fourth Generation iPod Nano
`ITDB_IPOD_GENERATION_VIDEO_1` | First Generation iPod Video (aka 5g)
`ITDB_IPOD_GENERATION_VIDEO_2` | Second Generation iPod Video (aka 5.5g)
`ITDB_IPOD_GENERATION_CLASSIC_1` | First Generation iPod Classic
`ITDB_IPOD_GENERATION_CLASSIC_2` | Second Generation iPod Classic
`ITDB_IPOD_GENERATION_TOUCH_1` | First Generation iPod Touch
`ITDB_IPOD_GENERATION_IPHONE_1` | First Generation iPhone
`ITDB_IPOD_GENERATION_SHUFFLE_4` | Third Generation iPod Shuffle
`ITDB_IPOD_GENERATION_TOUCH_2` |
`ITDB_IPOD_GENERATION_IPHONE_2` |
`ITDB_IPOD_GENERATION_IPHONE_3` |
`ITDB_IPOD_GENERATION_CLASSIC_3` |
`ITDB_IPOD_GENERATION_NANO_5` |
`ITDB_IPOD_GENERATION_TOUCH_3` |

Since 0.4.0

### itdb_info_get_ipod_generation_string ()

    const gchar *       itdb_info_get_ipod_generation_string
                                                            (Itdb_IpodGeneration generation);

Return the iPod's generic generation name, like "First Generation", "Mobile Phone"...

`generation` : | an Itdb_IpodGeneration
Returns : | a pointer to the generation name. This is a static string and must not be `g_free()`d.

Since 0.4.0

### enum Itdb_IpodModel

    typedef enum {
        ITDB_IPOD_MODEL_INVALID,
        ITDB_IPOD_MODEL_UNKNOWN,
        ITDB_IPOD_MODEL_COLOR,
        ITDB_IPOD_MODEL_COLOR_U2,
        ITDB_IPOD_MODEL_REGULAR,
        ITDB_IPOD_MODEL_REGULAR_U2,
        ITDB_IPOD_MODEL_MINI,
        ITDB_IPOD_MODEL_MINI_BLUE,
        ITDB_IPOD_MODEL_MINI_PINK,
        ITDB_IPOD_MODEL_MINI_GREEN,
        ITDB_IPOD_MODEL_MINI_GOLD,
        ITDB_IPOD_MODEL_SHUFFLE,
        ITDB_IPOD_MODEL_NANO_WHITE,
        ITDB_IPOD_MODEL_NANO_BLACK,
        ITDB_IPOD_MODEL_VIDEO_WHITE,
        ITDB_IPOD_MODEL_VIDEO_BLACK,
        ITDB_IPOD_MODEL_MOBILE_1,
        ITDB_IPOD_MODEL_VIDEO_U2,
        ITDB_IPOD_MODEL_NANO_SILVER,
        ITDB_IPOD_MODEL_NANO_BLUE,
        ITDB_IPOD_MODEL_NANO_GREEN,
        ITDB_IPOD_MODEL_NANO_PINK,
        ITDB_IPOD_MODEL_NANO_RED,
        ITDB_IPOD_MODEL_NANO_YELLOW,
        ITDB_IPOD_MODEL_NANO_PURPLE,
        ITDB_IPOD_MODEL_NANO_ORANGE,
        ITDB_IPOD_MODEL_IPHONE_1,
        ITDB_IPOD_MODEL_SHUFFLE_SILVER,
        ITDB_IPOD_MODEL_SHUFFLE_PINK,
        ITDB_IPOD_MODEL_SHUFFLE_BLUE,
        ITDB_IPOD_MODEL_SHUFFLE_GREEN,
        ITDB_IPOD_MODEL_SHUFFLE_ORANGE,
        ITDB_IPOD_MODEL_SHUFFLE_PURPLE,
        ITDB_IPOD_MODEL_SHUFFLE_RED,
        ITDB_IPOD_MODEL_CLASSIC_SILVER,
        ITDB_IPOD_MODEL_CLASSIC_BLACK,
        ITDB_IPOD_MODEL_TOUCH_SILVER,
        ITDB_IPOD_MODEL_SHUFFLE_BLACK,
        ITDB_IPOD_MODEL_IPHONE_WHITE,
        ITDB_IPOD_MODEL_IPHONE_BLACK,
    } Itdb_IpodModel;

iPod model information

`ITDB_IPOD_MODEL_INVALID` | Invalid model
`ITDB_IPOD_MODEL_UNKNOWN` | Unknown model
`ITDB_IPOD_MODEL_COLOR` | Color iPod
`ITDB_IPOD_MODEL_COLOR_U2` | Color iPod (U2)
`ITDB_IPOD_MODEL_REGULAR` | Regular iPod
`ITDB_IPOD_MODEL_REGULAR_U2` | Regular iPod (U2)
`ITDB_IPOD_MODEL_MINI` | iPod Mini
`ITDB_IPOD_MODEL_MINI_BLUE` | iPod Mini (Blue)
`ITDB_IPOD_MODEL_MINI_PINK` | iPod Mini (Pink)
`ITDB_IPOD_MODEL_MINI_GREEN` | iPod Mini (Green)
`ITDB_IPOD_MODEL_MINI_GOLD` | iPod Mini (Gold)
`ITDB_IPOD_MODEL_SHUFFLE` | iPod Shuffle
`ITDB_IPOD_MODEL_NANO_WHITE` | iPod Nano (White)
`ITDB_IPOD_MODEL_NANO_BLACK` | iPod Nano (Black)
`ITDB_IPOD_MODEL_VIDEO_WHITE` | iPod Video (White)
`ITDB_IPOD_MODEL_VIDEO_BLACK` | iPod Video (Black)
`ITDB_IPOD_MODEL_MOBILE_1` | Mobile iPod
`ITDB_IPOD_MODEL_VIDEO_U2` | iPod Video (U2)
`ITDB_IPOD_MODEL_NANO_SILVER` | iPod Nano (Silver)
`ITDB_IPOD_MODEL_NANO_BLUE` | iPod Nano (Blue)
`ITDB_IPOD_MODEL_NANO_GREEN` | iPod Nano (Green)
`ITDB_IPOD_MODEL_NANO_PINK` | iPod Nano (Pink)
`ITDB_IPOD_MODEL_NANO_RED` | iPod Nano (Red)
`ITDB_IPOD_MODEL_NANO_YELLOW` | iPod Nano (Yellow)
`ITDB_IPOD_MODEL_NANO_PURPLE` | iPod Nano (Purple)
`ITDB_IPOD_MODEL_NANO_ORANGE` | iPod Nano (Orange)
`ITDB_IPOD_MODEL_IPHONE_1` | iPhone
`ITDB_IPOD_MODEL_SHUFFLE_SILVER` | iPod Shuffle (Silver)
`ITDB_IPOD_MODEL_SHUFFLE_PINK` | iPod Shuffle (Pink)
`ITDB_IPOD_MODEL_SHUFFLE_BLUE` | iPod Shuffle (Blue)
`ITDB_IPOD_MODEL_SHUFFLE_GREEN` | iPod Shuffle (Green)
`ITDB_IPOD_MODEL_SHUFFLE_ORANGE` | iPod Shuffle (Orange)
`ITDB_IPOD_MODEL_SHUFFLE_PURPLE` | iPod Shuffle (Purple)
`ITDB_IPOD_MODEL_SHUFFLE_RED` | iPod Shuffle (Red)
`ITDB_IPOD_MODEL_CLASSIC_SILVER` | iPod Classic (Silver)
`ITDB_IPOD_MODEL_CLASSIC_BLACK` | iPod Classic (Black)
`ITDB_IPOD_MODEL_TOUCH_SILVER` |
`ITDB_IPOD_MODEL_SHUFFLE_BLACK` | iPod Shuffle (Black)
`ITDB_IPOD_MODEL_IPHONE_WHITE` |
`ITDB_IPOD_MODEL_IPHONE_BLACK` |

Since 0.4.0

### itdb_info_get_ipod_model_name_string ()

    const gchar *       itdb_info_get_ipod_model_name_string
                                                            (Itdb_IpodModel model);

Return the iPod's generic model name, like "Color", "Nano"...

`model` : | an Itdb_IpodModel
Returns : | a pointer to the model name. This is a static string and must not be `g_free()`d.

Since 0.4.0

### Itdb_ArtworkFormat

    typedef struct {
            gint format_id;
            gint width;
            gint height;
            ItdbThumbFormat format;
            gint32 padding;
            gboolean crop;
            gint rotation;
            guchar back_color[4];

            gint display_width;
            gboolean interlaced;
            gboolean align_row_bytes;
            gint color_adjustment;
            gdouble gamma;
            gint associated_format;
    } Itdb_ArtworkFormat;

Structure representing the characteristics of the thumbnails to write to a given .ithmb file. The format of the structure is based on the way artwork formats are written to SysInfoExtended.

gint `format_id`; | Unique ID for the format (generally a 4 digit int)
gint `width`; | Width of the thumbnail
gint `height`; | Height of the thumbnail
ItdbThumbFormat `format`; | Pixel format of the thumbnail (RGB, YUV, ...)
gint32 `padding`; | Number of bytes of padding to add after the thumbnail (not found in SysInfoExtended -- added for compatibility with hardcoded artwork formats)
gboolean `crop`; | Indicates if the thumbnail is to be cropped
gint `rotation`; | Degrees to rotate the thumbnail
guchar `back_color`[4]; | Background color for the thumbnail
gint `display_width`; | Width at which the thumbnail will be displayed (not currently used)
gboolean `interlaced`; | If TRUE, the thumbnails are interlaced (not currently used)
gboolean `align_row_bytes`; | If TRUE, each pixel row must be aligned a 2-byte boundary
gint `color_adjustment`; | Color adjustment for the thumbnails (not currently used)
gdouble `gamma`; | Gamma value for the thumbails (not currently used)
gint `associated_format`; | Unknown (not currently used)

### itdb_device_read_sysinfo ()

    gboolean            itdb_device_read_sysinfo            (Itdb_Device *device);

Reads the SysInfo file and stores information in device->sysinfo for later use.

### Warning

Calling this function invalidates all the artwork in the Itdb_iTunesDB database using this Itdb_Device. Trying to access this artwork will result in memory corruption. Directly calling this function shouldn't ever be needed and it will be deprecated soon.

.

`device` : | an Itdb_Device
Returns : | TRUE if file could be read, FALSE otherwise

Since 0.4.0

### itdb_device_get_sysinfo ()

    gchar *             itdb_device_get_sysinfo             (const Itdb_Device *device,
                                                             const gchar *field);

Retrieve specified field from the SysInfo file.

`device` : | an Itdb_Device
`field` : | field to retrive information from
Returns : | the information associated with `field`, or NULL if `field` couldn't be found. `g_free()` after use

Since 0.4.0

### itdb_device_set_sysinfo ()

    void                itdb_device_set_sysinfo             (Itdb_Device *device,
                                                             const gchar *field,
                                                             const gchar *value);

Set specified field. It can later be written to the iPod using `itdb_device_write_sysinfo()`

`device` : | an Itdb_Device
`field` : | field to set
`value` : | value to set (or NULL to remove the field).

Since 0.4.0

### itdb_device_write_sysinfo ()

    gboolean            itdb_device_write_sysinfo           (Itdb_Device *device,
                                                             GError **error);

Fills the SysInfo file with information in device->sysinfo. Note: no directories are created if not already existent.

`device` : | an Itdb_Device
`error` : | return location for a GError or NULL
Returns : | TRUE if file could be read, FALSE otherwise

Since 0.4.0