Device

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

Functions

Types and Values

Description

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

Functions

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

Parameters

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)

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.

.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

device

an Itdb_Device

 

Returns

true if device can play videos.

Since: 0.7.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

Parameters

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


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

Parameters

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


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

Parameters

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_device_read_sysinfo ()

gboolean
itdb_device_read_sysinfo (Itdb_Device *device);

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

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.

.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Types and Values

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;
    int iphone_sync_nest_level;
} Itdb_Device;

Structure representing an iPod device

Members

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;

Private data passed as is to libimobiledevice by itdb_start/stop_sync

 

int iphone_sync_nest_level;

   

Since: 0.4.0


struct Itdb_IpodInfo

struct Itdb_IpodInfo {
    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;
};

Structure representing information about an iPod

Members

const gchar *model_number;

The model number. This is abbreviated. If the first character is not numeric, it is omitted. 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


enum Itdb_IpodGeneration

iPod generation information

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

Members

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

Second Generation iPod Touch

 

ITDB_IPOD_GENERATION_IPHONE_2

Second Generation iPhone (aka iPhone 3G)

 

ITDB_IPOD_GENERATION_IPHONE_3

Third Generation iPhone (aka iPhone 3GS)

 

ITDB_IPOD_GENERATION_CLASSIC_3

Third Generation iPod Classic

 

ITDB_IPOD_GENERATION_NANO_5

Fifth Generation iPod Nano (with camera)

 

ITDB_IPOD_GENERATION_TOUCH_3

Third Generation iPod Touch

 

ITDB_IPOD_GENERATION_IPAD_1

   

ITDB_IPOD_GENERATION_IPHONE_4

   

ITDB_IPOD_GENERATION_TOUCH_4

   

ITDB_IPOD_GENERATION_NANO_6

   

Since: 0.4.0


enum Itdb_IpodModel

iPod model information

Members

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

iPod Touch (Silver)

 

ITDB_IPOD_MODEL_SHUFFLE_BLACK

iPod Shuffle (Black)

 

ITDB_IPOD_MODEL_IPHONE_WHITE

iPhone (White)

 

ITDB_IPOD_MODEL_IPHONE_BLACK

iPhone (Black)

 

ITDB_IPOD_MODEL_SHUFFLE_GOLD

   

ITDB_IPOD_MODEL_SHUFFLE_STAINLESS

   

ITDB_IPOD_MODEL_IPAD

   

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;
        gint color_adjustment;
        gdouble gamma;
        gint associated_format;
        gint row_bytes_alignment;
} 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.

Members

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)

 

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)

 

gint row_bytes_alignment;