Low-level functions

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

## Synopsis

    gchar *             itdb_get_control_dir                (const gchar *mountpoint);
    gchar *             itdb_get_itunes_dir                 (const gchar *mountpoint);
    gchar *             itdb_get_music_dir                  (const gchar *mountpoint);
    gchar *             itdb_get_artwork_dir                (const gchar *mountpoint);
    gchar *             itdb_get_device_dir                 (const gchar *mountpoint);
    gchar *             itdb_get_photos_dir                 (const gchar *mountpoint);
    gchar *             itdb_get_itunesdb_path              (const gchar *mountpoint);
    gchar *             itdb_get_itunessd_path              (const gchar *mountpoint);
    gchar *             itdb_get_itunescdb_path             (const gchar *mountpoint);
    gchar *             itdb_get_artworkdb_path             (const gchar *mountpoint);
    gchar *             itdb_get_photodb_path               (const gchar *mountpoint);
    gchar *             itdb_get_photos_thumb_dir           (const gchar *mountpoint);
    gchar *             itdb_get_path                       (const gchar *dir,
                                                             const gchar *file);
    gchar *             itdb_resolve_path                   (const gchar *root,
                                                             const gchar * const *components);
    gboolean            itdb_cp                             (const gchar *from_file,
                                                             const gchar *to_file,
                                                             GError **error);
    gchar *             itdb_cp_get_dest_filename           (Itdb_Track *track,
                                                             const gchar *mountpoint,
                                                             const gchar *filename,
                                                             GError **error);
    Itdb_Track *        itdb_cp_finalize                    (Itdb_Track *track,
                                                             const gchar *mountpoint,
                                                             const gchar *dest_filename,
                                                             GError **error);
    Itdb_iTunesDB *     itdb_parse_file                     (const gchar *filename,
                                                             GError **error);
    gboolean            itdb_write_file                     (Itdb_iTunesDB *itdb,
                                                             const gchar *filename,
                                                             GError **error);
    gboolean            itdb_shuffle_write                  (Itdb_iTunesDB *itdb,
                                                             GError **error);
    gboolean            itdb_shuffle_write_file             (Itdb_iTunesDB *itdb,
                                                             const gchar *filename,
                                                             GError **error);
    Itdb_iTunesDB *     itdb_duplicate                      (Itdb_iTunesDB *itdb);

## Description

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

## Details

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

`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'

`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'

`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'

`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'

`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'

`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

`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

`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

`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

`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

`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'

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

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

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

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

`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

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

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

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

`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

`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

`itdb` : | an Itdb_iTunesDB
Returns : | always return NULL since it's unimplemented