File handling functions

## File handling functions File handling functions — Managing files on the iPod |

## Synopsis

    gboolean            itdb_cp_track_to_ipod               (Itdb_Track *track,
                                                             const gchar *filename,
                                                             GError **error);
    void                itdb_filename_fs2ipod               (gchar *filename);
    void                itdb_filename_ipod2fs               (gchar *ipod_file);
    gchar *             itdb_filename_on_ipod               (Itdb_Track *track);
    gint                itdb_musicdirs_number               (Itdb_iTunesDB *itdb);
    gboolean            itdb_rename_files                   (const gchar *mp,
                                                             GError **error);
    gboolean            itdb_start_sync                     (Itdb_iTunesDB *itdb);
    gboolean            itdb_stop_sync                      (Itdb_iTunesDB *itdb);

## Description

These functions are for copying, renaming, and retrieving information about the files and directories on the iPod.

## Details

### itdb_cp_track_to_ipod ()

    gboolean            itdb_cp_track_to_ipod               (Itdb_Track *track,
                                                             const gchar *filename,
                                                             GError **error);

Copy one track to the iPod. The PC filename is `filename` and is taken literally.

The mountpoint of the iPod (in local encoding) must have been set with `itdb_set_mountpoint()` (done automatically when reading an iTunesDB).

If `track->transferred` is set to TRUE, nothing is done. Upon successful transfer `track->transferred` is set to TRUE.

For storage, the directories "F00 ... Fnn" will be used randomly.

The filename is constructed as "libgpod`random_number`" and copied to `track->ipod_path`. If this file already exists, `random_number` is adjusted until an unused filename is found.

If `track->ipod_path` is already set, this one will be used instead. If a file with this name already exists, it will be overwritten.

`track->filetype_marker` is set according to the filename extension

`track` : | the Itdb_Track to copy (containing `filename` metadata)
`filename` : | the source file
`error` : | return location for a GError or NULL
Returns : | TRUE on success, FALSE on error, in which case `error` is set accordingly.

### itdb_filename_fs2ipod ()

    void                itdb_filename_fs2ipod               (gchar *filename);

Convert string from casual PC file name to iPod iTunesDB format using ':' instead of G_DIR_SEPARATOR_S (i.e. slashes on Unix-like systems). `ipod_file` is modified in place.

`filename` : | a 'PC-style' filename (eg /iPod_Control/Music/f00/test.mp3)

### itdb_filename_ipod2fs ()

    void                itdb_filename_ipod2fs               (gchar *ipod_file);

Convert string from from iPod iTunesDB format to casual PC file name using G_DIR_SEPARATOR (ie slashes on Unix-like systems) instead of ':'. `ipod_file` is modified in place.

`ipod_file` : | a 'PC-style' filename (eg /iPod_Control/Music/f00/test.mp3)

### itdb_filename_on_ipod ()

    gchar *             itdb_filename_on_ipod               (Itdb_Track *track);

Get the full iPod filename as stored in `track`.

### Note

NULL is returned when the file does not exist.

### Note

This code works around a problem on some systems (see `itdb_resolve_path()`) and might return a filename with different case than the original filename. Don't copy it back to `track` if you can avoid it.

`track` : | an Itdb_Track
Returns : | full filename to `track` on the iPod or NULL if no filename is set in `track`. Must be freed with `g_free()` after use.

### itdb_musicdirs_number ()

    gint                itdb_musicdirs_number               (Itdb_iTunesDB *itdb);

Determine the number of F.. directories in iPod_Control/Music.

If `itdb->musicdirs` is already set, simply return the previously determined number. Otherwise count the directories first and set `itdb->musicdirs`.

`itdb` : | an Itdb_iTunesDB
Returns : | max number of directories in iPod_Control/Music

Since 0.1.3

### itdb_rename_files ()

    gboolean            itdb_rename_files                   (const gchar *mp,
                                                             GError **error);

Renames/removes some files on the iPod (Playcounts, OTG semaphore). May have to be called if you write the iTunesDB not directly to the iPod but to some other location and then manually copy the file from there to the iPod.

`mp` : | mount point of the iPod
`error` : | return location for a GError or NULL
Returns : | FALSE on error and sets `error` accordingly

### itdb_start_sync ()

    gboolean            itdb_start_sync                     (Itdb_iTunesDB *itdb);

Hints libgpod that a series of file copies/database saves/... is about to start. On regular iPods, this does nothing (but is safe to be used), but on iPhones and iPod Touch this makes sure the "Sync in progress" screen is shown for the whole duration of the writing process.

Calls to itdb_start_sync must be paired with calls to itdb_stop_sync. Nesting is allowed.

`itdb` : | the Itdb_iTunesDB that is being sync'ed
Returns : | TRUE on success, FALSE on error

### itdb_stop_sync ()

    gboolean            itdb_stop_sync                      (Itdb_iTunesDB *itdb);

Hints libgpod that the series of file copies/database saves/... started with itdb_start_sync is finished. On regular iPods, this does nothing (but is safe to be used). On iPhones and iPod Touch this will hide the "Sync in progress" screen.

Calls to itdb_stop_sync must be paired with calls to itdb_start_sync. Nesting is allowed, and only the final itdb_stop_sync will actually stop the sync.

`itdb` : | the Itdb_iTunesDB that is being sync'ed
Returns : | TRUE on success, FALSE on error