Low-level functions

Low-level functions — Low-level functions which shouldn't be needed in normal situations

Functions

Description

These functions are not normally needed but are available to allow for finer control over the iPod database.

Functions

itdb_get_control_dir ()

gchar *
itdb_get_control_dir (const gchar *mountpoint);

Get the i*_Control directory. Observed values are 'iPod_Control' for standard iPods and 'iTunes/iTunes_Control' for mobile applications.

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the control dir or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_itunes_dir ()

gchar *
itdb_get_itunes_dir (const gchar *mountpoint);

Retrieve the iTunes directory (containing the iTunesDB) by first calling itdb_get_control_dir() and then adding 'iTunes'

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the iTunes directory or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_music_dir ()

gchar *
itdb_get_music_dir (const gchar *mountpoint);

Retrieve the Music directory (containing the Fnn dirs) by first calling itdb_get_control_dir() and then adding 'Music'

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the Music directory or NULL if non-existent. Must g_free() after use.


itdb_get_artwork_dir ()

gchar *
itdb_get_artwork_dir (const gchar *mountpoint);

Retrieve the Artwork directory (containing the ArtworDB) by first calling itdb_get_control_dir() and then adding 'Artwork'

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the Artwork directory or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_device_dir ()

gchar *
itdb_get_device_dir (const gchar *mountpoint);

Retrieve the Device directory (containing the SysInfo file) by first calling itdb_get_control_dir() and then adding 'Device'

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the Device directory or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_photos_dir ()

gchar *
itdb_get_photos_dir (const gchar *mountpoint);

Retrieve the Photo directory by first calling itdb_get_control_dir() and then adding 'Photos'

Parameters

mountpoint

mountpoint of iPod

 

Returns

path to the Artwork directory or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_itunesdb_path ()

gchar *
itdb_get_itunesdb_path (const gchar *mountpoint);

Retrieve a path to the iTunesDB

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the iTunesDB or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_itunessd_path ()

gchar *
itdb_get_itunessd_path (const gchar *mountpoint);

Retrieve a path to the iTunesSD

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the iTunesSD or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_itunescdb_path ()

gchar *
itdb_get_itunescdb_path (const gchar *mountpoint);

Retrieve a path to the iTunesCDB. The iTunesCDB is a compressed version of the iTunesDB which can be found on iPhones/iPod Touch with firmware 3.0

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the iTunesCDB or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_artworkdb_path ()

gchar *
itdb_get_artworkdb_path (const gchar *mountpoint);

Retrieve a path to the ArtworkDB

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the ArtworkDB or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_photodb_path ()

gchar *
itdb_get_photodb_path (const gchar *mountpoint);

Retrieve a path to the Photo DB

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the PhotoDB or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_photos_thumb_dir ()

gchar *
itdb_get_photos_thumb_dir (const gchar *mountpoint);

Retrieve the Photo Thumbnail directory by first calling itdb_get_control_dir() and then adding 'Photos/Thumbs'

Parameters

mountpoint

the iPod mountpoint

 

Returns

path to the Artwork directory or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_get_path ()

gchar *
itdb_get_path (const gchar *dir,
               const gchar *file);

Retrieve a path to the file in dir

Parameters

dir

a directory

 

file

a file

 

Returns

path to the file or NULL if non-existent. Must g_free() after use.

Since: 0.4.0


itdb_resolve_path ()

gchar *
itdb_resolve_path (const gchar *root,
                   const gchar * const *components);

Resolve the path to a track on the iPod

We start by assuming that the iPod mount point exists. Then, for each component c of track->ipod_path , we try to find an entry d in good_path that is case-insensitively equal to c. If we find d, we append d to good_path and make the result the new good_path. Otherwise, we quit and return NULL.

Parameters

root

in local encoding

 

components

in utf8

 

Returns

path to track on the iPod or NULL.


itdb_cp ()

gboolean
itdb_cp (const gchar *from_file,
         const gchar *to_file,
         GError **error);

Copy file from_file to to_file .

Parameters

from_file

source file

 

to_file

destination file

 

error

return location for a GError or NULL

 

Returns

TRUE on success, FALSE on error, in which case error is set accordingly.


itdb_cp_get_dest_filename ()

gchar *
itdb_cp_get_dest_filename (Itdb_Track *track,
                           const gchar *mountpoint,
                           const gchar *filename,
                           GError **error);

Creates a valid filename on the iPod where filename can be copied.

You must provide either track or mountpoint . Providing track is not thread-safe (accesses track->itdb->device and may even write to track->itdb->device). Providing mountpoint is thread-safe but slightly slower because the number of music directories is counted each time the function is called.

You can use itdb_cp() to copy the track to the iPod or implement your own copy function. After the file was copied you have to call itdb_cp_finalize() to obtain relevant update information for Itdb_Track.

Parameters

track

track to transfer or NULL

 

mountpoint

mountpoint of your iPod or NULL

 

filename

the source file

 

error

return location for a GError or NULL

 

Returns

a valid filename on the iPod where filename can be copied or NULL in case of an error. In that case error is set accordingly. You must free the filename when it is no longer needed.

Since: 0.5.0


itdb_cp_finalize ()

Itdb_Track *
itdb_cp_finalize (Itdb_Track *track,
                  const gchar *mountpoint,
                  const gchar *dest_filename,
                  GError **error);

Updates information in track necessary for the iPod.

You must supply either track or mountpoint . If track == NULL, a new track structure is created that must be freed with itdb_track_free() when it is no longer needed.

The following track fields are updated:

  • ipod_path
  • filetype_marker
  • transferred
  • size

Parameters

track

track to update or NULL

 

mountpoint

mountpoint of your iPod or NULL

 

dest_filename

the name of the file on the iPod copied to

 

error

return location for a GError or NULL

 

Returns

on success a pointer to the Itdb_Track item passed or a new Itdb_Track item if track was NULL. In the latter case you must free the memory using itdb_track_free() when the item is no longer used. If an error occurs NULL is returned and error is set accordingly. Errors occur when dest_filename cannot be accessed or the mountpoint is not set.

Since: 0.5.0


itdb_parse_file ()

Itdb_iTunesDB *
itdb_parse_file (const gchar *filename,
                 GError **error);

Same as itunesdb_parse(), but filename is specified directly.

Parameters

filename

path to a file in iTunesDB format

 

error

return location for a GError or NULL

 

Returns

a newly allocated Itdb_iTunesDB struct holding the tracks and the playlists present in filename , NULL if filename isn't a parsable iTunesDB file. If non-NULL, the Itdb_iTunesDB is to be freed with itdb_free() when it's no longer needed


itdb_write_file ()

gboolean
itdb_write_file (Itdb_iTunesDB *itdb,
                 const gchar *filename,
                 GError **error);

Write the content of itdb to filename . If filename is NULL, it attempts to write to itdb->filename .

Parameters

itdb

the Itdb_iTunesDB to save

 

filename

filename to save itdb to

 

error

return location for a GError or NULL

 

Returns

TRUE if all went well, FALSE otherwise


itdb_shuffle_write ()

gboolean
itdb_shuffle_write (Itdb_iTunesDB *itdb,
                    GError **error);

Write out an iTunesSD for the Shuffle.

First reassigns unique IDs to all tracks. An existing "Play Counts" file is renamed to "Play Counts.bak" if the export was successful. An existing "OTGPlaylistInfo" file is removed if the export was successful. itdb->mountpoint must point to the mount point of the iPod, e.g. "/mnt/ipod" and be in local encoding.

Parameters

itdb

the Itdb_iTunesDB to write to disk

 

error

return location for a GError or NULL

 

Returns

TRUE on success, FALSE on error, in which case error is set accordingly.


itdb_shuffle_write_file ()

gboolean
itdb_shuffle_write_file (Itdb_iTunesDB *itdb,
                         const gchar *filename,
                         GError **error);

Do the actual writing to the iTunesSD

Parameters

itdb

the Itdb_iTunesDB to write to disk

 

filename

file to write to, cannot be NULL

 

error

return location for a GError or NULL

 

Returns

TRUE on success, FALSE on error, in which case error is set accordingly.


itdb_duplicate ()

Itdb_iTunesDB *
itdb_duplicate (Itdb_iTunesDB *itdb);

Duplicate itdb FIXME: not implemented yet

Parameters

itdb

an Itdb_iTunesDB

 

Returns

always return NULL since it's unimplemented

Types and Values