Device

## 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_read_sysinfo            (Itdb_Device *device);
    gchar*              itdb_device_get_sysinfo             (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);
    const Itdb_IpodInfo* itdb_device_get_ipod_info          (Itdb_Device *device);
    gboolean            itdb_device_supports_artwork        (Itdb_Device *device);
    gboolean            itdb_device_supports_photo          (Itdb_Device *device);
    const Itdb_IpodInfo* itdb_info_get_ipod_info_table      (void);
    const gchar*        itdb_info_get_ipod_generation_string
                                                            (Itdb_IpodGeneration generation);
    const gchar*        itdb_info_get_ipod_model_name_string
                                                            (Itdb_IpodModel model);
    gboolean            itdb_init_ipod                      (const gchar *mountpoint,
                                                             const gchar *model_number,
                                                             const gchar *ipod_name,
                                                             GError **error);
    enum                Itdb_IpodGeneration;
                        Itdb_IpodInfo;
    enum                Itdb_IpodModel;
                        Itdb_ArtworkFormat;

## Description

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

## Details

### Itdb_Device

    typedef struct {
        gchar *mountpoint;    /* mountpoint of the iPod */
        gint   musicdirs;     /* 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;  /* hash with value/key pairs of all entries
    			   * in Device/SysInfo */
        gboolean sysinfo_changed; /* Has the sysinfo hash been changed by
    				 the user (itdb_set_sysinfo) */
        gint timezone_shift;  /* difference in seconds between the current
                               * timezone and UTC
                               */
    } Itdb_Device;

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

### itdb_device_free ()

    void                itdb_device_free                    (Itdb_Device *device);

Frees memory used by `device`

`device` : | an Itdb_Device

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

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

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

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

### itdb_device_get_sysinfo ()

    gchar*              itdb_device_get_sysinfo             (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

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

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

### itdb_device_get_ipod_info ()

    const Itdb_IpodInfo* itdb_device_get_ipod_info          (Itdb_Device *device);

Retrieve the Itdb_IpodInfo entry for this iPod

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

### itdb_device_supports_artwork ()

    gboolean            itdb_device_supports_artwork        (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.

### itdb_device_supports_photo ()

    gboolean            itdb_device_supports_photo          (Itdb_Device *device);

Indicates whether `device` can display photos or not.

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

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

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

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

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

### itdb_init_ipod ()

    gboolean            itdb_init_ipod                      (const gchar *mountpoint,
                                                             const gchar *model_number,
                                                             const gchar *ipod_name,
                                                             GError **error);

Initialise an iPod device from scratch. The function attempts to create a blank database, complete with master playlist and device information as well as the directory structure required for the type of iPod.

`mountpoint` : | the iPod mountpoint
`model_number` : | the iPod model number
`ipod_name` : | the name to give to the iPod. Will be displayed in gtkpod or itunes
`error` : | return location for a GError or NULL
Returns : | TRUE when successful, FALSE if a failure has occurred.

### 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_VIDEO_1,
        ITDB_IPOD_GENERATION_VIDEO_2,
        ITDB_IPOD_GENERATION_CLASSIC_1,
        ITDB_IPOD_GENERATION_TOUCH_1,
        /* The following 2 are no longer in use and should be removed */
        ITDB_IPOD_GENERATION_FIFTH,
        ITDB_IPOD_GENERATION_SIXTH,
    } Itdb_IpodGeneration;

### Itdb_IpodInfo

    typedef struct {
        /* model_number is abbreviated: if the first character is not
           numeric, it is ommited. e.g. "MA350 -> A350", "M9829 -> 9829" */
        const gchar *model_number;
        const double capacity;  /* in GB */
        const Itdb_IpodModel ipod_model;
        const Itdb_IpodGeneration ipod_generation;
        /* 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 guint musicdirs;
        /* reserved for future use */
        const gint32 reserved_int1;
        const gint32 reserved_int2;
        gconstpointer reserved1;
        gconstpointer reserved2;
    } Itdb_IpodInfo;

### 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_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_CLASSIC_SILVER,
        ITDB_IPOD_MODEL_CLASSIC_BLACK,
        ITDB_IPOD_MODEL_TOUCH_BLACK,
    } Itdb_IpodModel;

### Itdb_ArtworkFormat

    typedef struct {
    	ItdbThumbType type;
    	gint16 width;
    	gint16 height;
    	gint16 correlation_id;
            ItdbThumbFormat format;
            gint32 padding;
    } Itdb_ArtworkFormat;