Main Page | Class List | File List | Class Members | File Members

ipod.h File Reference

Mid-level C interface to the iPod. More...

#include <ipod/ipod_file_utils.h>

Go to the source code of this file.

Typedefs

typedef void * ipod_t
 an iPod
typedef void * ipod_track_t
 a track on an iPod
typedef void * ipod_playlist_t
 a playlist on an iPod
typedef void * ipod_track_item_t
 a track reference in a playlist on an iPod
typedef void * ipod_eq_preset_t
 an equalizer preset on the iPod

Functions

int ipod_discover (char ***path_array)
 Return a count and array of paths to mounted iPods.
ipod_t ipod_new (const char *path)
 Read the databases for the iPod at the given mount point.
void ipod_flush (ipod_t ipod)
 Write the database if required.
void ipod_free (ipod_t ipod)
 Flush the databases and close the iPod.
uint32_t ipod_version (ipod_t ipod)
 Return the version of the database on the iPod.
void ipod_disk_usage (ipod_t ipod, uint64_t *total, uint64_t *free)
 Report the total and available disk space on the iPod.
unsigned int ipod_track_count (ipod_t ipod)
 Return the number of audio tracks on the iod.
ipod_track_t ipod_track_get_by_index (ipod_t ipod, unsigned int index)
 get the audio track for the given index
ipod_track_t ipod_track_get_by_track_id (ipod_t ipod, uint32_t track_id)
 get the audio track with the given unique track ID
void ipod_track_free (ipod_track_t track)
 free the audio track structure
ipod_track_t ipod_track_add (ipod_t ipod)
 Add a new, empty track structure to the iPod.
ipod_track_t ipod_track_add_from (ipod_t ipod, const char *filePath)
 Add a track from an mp3, m4a or wav audio file to the iPod.
void ipod_track_remove (ipod_track_t track)
 Remove a track from the iPod.
char * ipod_track_get_text (ipod_track_t track, int tag, char *s)
 Get an attribute text string from the track.
void ipod_track_set_text (ipod_track_t track, int tag, const char *s)
 Set an attribute text string for the track.
int ipod_track_has_text (ipod_track_t track, int tag)
 Determine if a track has a particular text attribute.
uint32_t ipod_track_get_attribute (ipod_track_t track, int tag)
 Get a numerical attribute of a track.
void ipod_track_set_attribute (ipod_track_t track, int tag, uint32_t value)
 Set a numerical attribute of a track.
void ipod_track_upload (ipod_track_t track, const char *filePath, ipod_file_transfer_func callback, void *userData)
 Upload an audio file corresponding to the track.
void ipod_track_download (ipod_track_t track, const char *filePath, ipod_file_transfer_func callback, void *userData)
 Download an audio file corresponding to the track.
unsigned int ipod_playlist_count (ipod_t ipod)
 Return the number of playlists on the iPod.
ipod_playlist_t ipod_playlist_get_by_index (ipod_t ipod, unsigned int index)
 get the playlist for the given index
void ipod_playlist_free (ipod_playlist_t playlist)
 free the playlist structure
ipod_playlist_t ipod_playlist_add (ipod_t ipod)
 Add a new, empty playlist structure to the iPod.
void ipod_playlist_remove (ipod_playlist_t playlist)
 Remove a playlist from the iPod.
char * ipod_playlist_get_text (ipod_playlist_t playlist, int tag, char *s)
 Get an attribute text string from the playlist.
void ipod_playlist_set_text (ipod_playlist_t playlist, int tag, const char *s)
 Set an attribute text string for the playlist.
int ipod_playlist_has_text (ipod_playlist_t playlist, int tag)
 Determine if a playlist has a particular text attribute.
uint32_t ipod_playlist_get_attribute (ipod_playlist_t playlist, int tag)
 Get a numerical attribute of a playlist.
void ipod_playlist_set_attribute (ipod_playlist_t playlist, int tag, uint32_t value)
 Set a numerical attribute of a playlist.
unsigned int ipod_track_item_count (ipod_playlist_t playlist)
 Return the number of track items in the playlist.
ipod_track_item_t ipod_track_item_get_by_index (ipod_playlist_t playlist, unsigned int index)
 get the track item for the given index
void ipod_track_item_free (ipod_track_item_t trackItem)
 free the track item structure
ipod_track_item_t ipod_track_item_add (ipod_playlist_t playlist)
 Add a new, empty track item structure to the iPod.
void ipod_track_item_remove (ipod_track_item_t trackItem)
 Remove a track item from a playlist.
uint32_t ipod_track_item_get_attribute (ipod_track_item_t trackItem, int tag)
 Get a numerical attribute of a track item.
void ipod_track_item_set_attribute (ipod_track_item_t trackItem, int tag, uint32_t value)
 Set a numerical attribute of a track item.
unsigned int ipod_eq_preset_count (ipod_t ipod)
 Return the number of EQ presets on the iPod.
ipod_eq_preset_t ipod_eq_preset_get_by_index (ipod_t ipod, unsigned int index)
 get the EQ preset for the given index
void ipod_eq_preset_free (ipod_eq_preset_t preset)
 free the EQ preset structure
ipod_eq_preset_t ipod_eq_preset_add (ipod_t ipod)
 Add a new, empty EQ preset structure to the iPod.
void ipod_eq_preset_remove (ipod_eq_preset_t preset)
 Remove an EQ preset from the iPod.
char * ipod_eq_preset_get_text (ipod_eq_preset_t preset, int tag, char *s)
 Get an attribute text string from the EQ preset.
void ipod_eq_preset_set_text (ipod_eq_preset_t preset, int tag, const char *s)
 Set an attribute text string for the EQ preset.
int ipod_eq_preset_has_text (ipod_eq_preset_t preset, int tag)
 Determine if an EQ preset has a particular text attribute.
int32_t ipod_eq_preset_get_attribute (ipod_eq_preset_t preset, int tag)
 Get a numerical attribute of an EQ preset.
void ipod_eq_preset_set_attribute (ipod_eq_preset_t preset, int tag, int32_t value)
 Set a numerical attribute of an EQ preset.
void ipod_report (void)
 Prints out various internal statistics for debugging.


Detailed Description

Mid-level C interface to the iPod.


Function Documentation

int ipod_discover char ***  path_array  ) 
 

Return a count and array of paths to mounted iPods.

This function scans the /mnt directory looking for mounted iPods and returns an array of strings which are absolute paths to each mount point

Parameters:
path_array a pointer to a pointer in which to store an array of strings
Returns:
the number of mounted iPods
The caller is reponsible for freeing the array and its elements

void ipod_disk_usage ipod_t  ipod,
uint64_t *  total,
uint64_t *  free
 

Report the total and available disk space on the iPod.

Parameters:
ipod the iPod
total a pointer to a 64-bit integer which will contain the total storage in bytes
free a pointer to a 64-bit integer which will contain the available space in bytes

ipod_eq_preset_t ipod_eq_preset_add ipod_t  ipod  ) 
 

Add a new, empty EQ preset structure to the iPod.

Subsequent calls should be made to add the various text and number attributes to the EQ preset.

Parameters:
ipod the iPod on which to add the EQ preset
Returns:
an EQ preset structure

unsigned int ipod_eq_preset_count ipod_t  ipod  ) 
 

Return the number of EQ presets on the iPod.

Parameters:
ipod the iPod
Returns:
the number of EQ presets on the iPod

void ipod_eq_preset_free ipod_eq_preset_t  preset  ) 
 

free the EQ preset structure

This method just frees the wrapper structure - the EQ preset itself in not removed from the iPod

Parameters:
preset the EQ preset structure to be freed

int32_t ipod_eq_preset_get_attribute ipod_eq_preset_t  preset,
int  tag
 

Get a numerical attribute of an EQ preset.

Parameters:
preset the EQ preset from which to fetch the attribute
tag the identifier for the attribute to be retrieved
Returns:
the current value of the attribute

ipod_eq_preset_t ipod_eq_preset_get_by_index ipod_t  ipod,
unsigned int  index
 

get the EQ preset for the given index

Parameters:
ipod the iPod
index the index of the EQ preset to be returned
Returns:
the EQ preset

char* ipod_eq_preset_get_text ipod_eq_preset_t  preset,
int  tag,
char *  s
 

Get an attribute text string from the EQ preset.

Parameters:
preset the EQ preset from which to fetch the attribute
tag the identifier for the attribute to be retrieved (IPOD_TITLE is the only tag currently supported)
s (optional) a string allocated on the heap in which to store the resulting text. If the parameter is NULL, then a new string is allocated on the heap, otherwise the string is reallocated to the size of the attribute.
Returns:
a string on the heap encoded in UTF-8
  char *title = ipod_string_new();
  title = ipod_eq_preset_get_text(preset,IPOD_TITLE,title);
  printf("The preset name is %s\n",title);
  ipod_string_free(title);

int ipod_eq_preset_has_text ipod_eq_preset_t  preset,
int  tag
 

Determine if an EQ preset has a particular text attribute.

Parameters:
preset the EQ preset for which to test the attribute
tag the identifier for the attribute to be tested (IPOD_TITLE si the only tag currently supported)
Returns:
0 if the attribute is missing, 1 otherwise

void ipod_eq_preset_remove ipod_eq_preset_t  preset  ) 
 

Remove an EQ preset from the iPod.

Parameters:
preset the EQ preset to be removed

void ipod_eq_preset_set_attribute ipod_eq_preset_t  preset,
int  tag,
int32_t  value
 

Set a numerical attribute of an EQ preset.

Parameters:
preset the EQ preset for which to set the attribute
tag the identifier for the attribute to be set
value the new value for the attribute

void ipod_eq_preset_set_text ipod_eq_preset_t  preset,
int  tag,
const char *  s
 

Set an attribute text string for the EQ preset.

Parameters:
preset the EQ preset for which to set the attribute
tag the identifier for the attribute to be set (IPOD_TITLE is the only tag currently supported
s the text encoded in UTF-8 to be assigned to the attribute
 ipod_eq_preset_set_text(preset,IPOD_TITLE,"Boombox");

void ipod_flush ipod_t  ipod  ) 
 

Write the database if required.

Parameters:
ipod the iPod to be flushed

void ipod_free ipod_t  ipod  ) 
 

Flush the databases and close the iPod.

Parameters:
ipod the iPod to be freed

ipod_t ipod_new const char *  path  ) 
 

Read the databases for the iPod at the given mount point.

Parameters:
path an absolute path to the iPod's mount point
Returns:
a reference to the iPod that is used in subsequent calls

ipod_playlist_t ipod_playlist_add ipod_t  ipod  ) 
 

Add a new, empty playlist structure to the iPod.

Subsequent calls should be made to add the various text and number attributes to the playlist.

Parameters:
ipod the iPod on which to add the playlist
Returns:
a playlist structure

unsigned int ipod_playlist_count ipod_t  ipod  ) 
 

Return the number of playlists on the iPod.

Parameters:
ipod the iPod
Returns:
the number of playlists on the iPod

void ipod_playlist_free ipod_playlist_t  playlist  ) 
 

free the playlist structure

This method just frees the wrapper structure - the playlist itself in not removed from the iPod database

Parameters:
playlist the playlist structure to be freed

uint32_t ipod_playlist_get_attribute ipod_playlist_t  playlist,
int  tag
 

Get a numerical attribute of a playlist.

Parameters:
playlist the playlist from which to fetch the attribute
tag the identifier for the attribute to be retrieved
Returns:
the current value of the attribute

ipod_playlist_t ipod_playlist_get_by_index ipod_t  ipod,
unsigned int  index
 

get the playlist for the given index

Parameters:
ipod the iPod
index the index of the playlist to be returned
Returns:
the playlist

char* ipod_playlist_get_text ipod_playlist_t  playlist,
int  tag,
char *  s
 

Get an attribute text string from the playlist.

Parameters:
playlist the playlist from which to fetch the attribute
tag the identifier for the attribute to be retrieved (IPOD_TITLE is the only tag currently supported)
s (optional) a string allocated on the heap in which to store the resulting text. If the parameter is NULL, then a new string is allocated on the heap, otherwise the string is reallocated to the size of the attribute.
Returns:
a string on the heap encoded in UTF-8
  char *title = ipod_string_new();
  title = ipod_playlist_get_text(playlist,IPOD_TITLE,title);
  printf("The playlist title is %s\n",title);
  ipod_string_free(title);

int ipod_playlist_has_text ipod_playlist_t  playlist,
int  tag
 

Determine if a playlist has a particular text attribute.

Parameters:
playlist the playlist for which to test the attribute
tag the identifier for the attribute to be tested (IPOD_TITLE si the only tag currently supported)
Returns:
0 if the attribute is missing, 1 otherwise

void ipod_playlist_remove ipod_playlist_t  playlist  ) 
 

Remove a playlist from the iPod.

Parameters:
playlist the playlist to be removed

void ipod_playlist_set_attribute ipod_playlist_t  playlist,
int  tag,
uint32_t  value
 

Set a numerical attribute of a playlist.

Parameters:
playlist the playlist for which to set the attribute
tag the identifier for the attribute to be set
value the new value for the attribute

void ipod_playlist_set_text ipod_playlist_t  playlist,
int  tag,
const char *  s
 

Set an attribute text string for the playlist.

Parameters:
playlist the playlist for which to set the attribute
tag the identifier for the attribute to be set (IPOD_TITLE is the only tag currently supported
s the text encoded in UTF-8 to be assigned to the attribute
 ipod_playlist_set_text(playlist,IPOD_TITLE,"Favorites");

ipod_track_t ipod_track_add ipod_t  ipod  ) 
 

Add a new, empty track structure to the iPod.

Subsequent calls should be made to add the various text and number attributes to the track.

Parameters:
ipod the iPod on which to add the track
Returns:
a track structure

ipod_track_t ipod_track_add_from ipod_t  ipod,
const char *  filePath
 

Add a track from an mp3, m4a or wav audio file to the iPod.

This method will add a new track to the iPod and create the attribute information based on the contents of the supplied audio file. It will extract ID3 tags and other metaiinformation as appropriate, and will analyse the file for sample rate, bitrate, duration, etc. It understands .mp3, .m4a, and .wav files. For mp3 files, it will extract tags in ID3v1, ID3v1.1, ID3v2.2, ID3v2.3 and ID3v4 format, and handles text tags in ISO-8859-1, UTF-16-BOM, UTF-16BE and UTF-8

Parameters:
ipod the iPod
filePath the path to an mp3, m4a or wav file
Returns:
a track structure

unsigned int ipod_track_count ipod_t  ipod  ) 
 

Return the number of audio tracks on the iod.

Parameters:
ipod the iPod
Returns:
the number of audio tracks on the iPod

void ipod_track_download ipod_track_t  track,
const char *  filePath,
ipod_file_transfer_func  callback,
void *  userData
 

Download an audio file corresponding to the track.

Parameters:
track the track associated with the file
filePath the path to the destination to which the track will be downloaded
callback a function to be called during the diwnload to report progress information
userData a pointer to data to be sent as a parameter for the callback

void ipod_track_free ipod_track_t  track  ) 
 

free the audio track structure

This method just frees the wrapper structure - the track itself in not removed from the iPod database

Parameters:
track the audio track structure to be freed

uint32_t ipod_track_get_attribute ipod_track_t  track,
int  tag
 

Get a numerical attribute of a track.

Parameters:
track the track from which to fetch the attribute
tag the identifier for the attribute to be retrieved
Returns:
the current value of the attribute

ipod_track_t ipod_track_get_by_index ipod_t  ipod,
unsigned int  index
 

get the audio track for the given index

Parameters:
ipod the iPod
index the index of the audio track to be returned
Returns:
the audio track

ipod_track_t ipod_track_get_by_track_id ipod_t  ipod,
uint32_t  track_id
 

get the audio track with the given unique track ID

Parameters:
ipod the iPod
track_id the track ID of the audio track to be returned
Returns:
the audio track

char* ipod_track_get_text ipod_track_t  track,
int  tag,
char *  s
 

Get an attribute text string from the track.

Parameters:
track the track from which to fetch the attribute
tag the identifier for the attribute to be retrieved
s (optional) a string allocated on the heap in which to store the resulting text. If the parameter is NULL, then a new string is allocated on the heap, otherwise the string is reallocated to the size of the attribute.
Returns:
a string on the heap encoded in UTF-8
  char *title = ipod_string_new();
  title = ipod_track_get_text(track,IPOD_TITLE,title);
  printf("The title is %s\n",title);
  ipod_string_free(title);

int ipod_track_has_text ipod_track_t  track,
int  tag
 

Determine if a track has a particular text attribute.

Parameters:
track the track for which to test the attribute
tag the identifier for the attribute to be tested
Returns:
0 if the attribute is missing, 1 otherwise

ipod_track_item_t ipod_track_item_add ipod_playlist_t  playlist  ) 
 

Add a new, empty track item structure to the iPod.

Subsequent calls should be made to add the various number attributes to the track item.

Parameters:
playlist the playlist to which to add the track item
Returns:
a track item structure

unsigned int ipod_track_item_count ipod_playlist_t  playlist  ) 
 

Return the number of track items in the playlist.

Parameters:
playlist the playlist
Returns:
the number of track items in the playlist

void ipod_track_item_free ipod_track_item_t  trackItem  ) 
 

free the track item structure

This method just frees the wrapper structure - the track item itself in not removed from the playlist

Parameters:
trackItem the track item structure to be freed

uint32_t ipod_track_item_get_attribute ipod_track_item_t  trackItem,
int  tag
 

Get a numerical attribute of a track item.

Parameters:
trackItem the track item from which to fetch the attribute
tag the identifier for the attribute to be retrieved
Returns:
the current value of the attribute

ipod_track_item_t ipod_track_item_get_by_index ipod_playlist_t  playlist,
unsigned int  index
 

get the track item for the given index

Parameters:
playlist the playlist
index the index of the track item to be returned
Returns:
the track item

void ipod_track_item_remove ipod_track_item_t  trackItem  ) 
 

Remove a track item from a playlist.

Parameters:
trackItem the track item to be removed

void ipod_track_item_set_attribute ipod_track_item_t  trackItem,
int  tag,
uint32_t  value
 

Set a numerical attribute of a track item.

Parameters:
trackItem the track item for which to set the attribute
tag the identifier for the attribute to be set
value the new value for the attribute

void ipod_track_remove ipod_track_t  track  ) 
 

Remove a track from the iPod.

The track will be removed from all playlists, and the corresponding audio file will be removed from the iPod's storage

Parameters:
track the track to be removed

void ipod_track_set_attribute ipod_track_t  track,
int  tag,
uint32_t  value
 

Set a numerical attribute of a track.

Parameters:
track the track for which to set the attribute
tag the identifier for the attribute to be set
value the new value for the attribute

void ipod_track_set_text ipod_track_t  track,
int  tag,
const char *  s
 

Set an attribute text string for the track.

Parameters:
track the track for which to set the attribute
tag the identifier for the attribute to be set
s the text encoded in UTF-8 to be assigned to the attribute
 ipod_track_set_text(track,IPOD_TITLE,"Dead Puppies");

void ipod_track_upload ipod_track_t  track,
const char *  filePath,
ipod_file_transfer_func  callback,
void *  userData
 

Upload an audio file corresponding to the track.

Parameters:
track the track to be associated with the file
filePath the path to the audio file to be uploaded
callback a function to be called during the upload to report progress information
userData a pointer to data to be sent as a parameter for the callback

uint32_t ipod_version ipod_t  ipod  ) 
 

Return the version of the database on the iPod.

Parameters:
ipod the iPod
Returns:
the version number of the database


Generated on Tue Dec 13 14:55:22 2005 for libipod by  doxygen 1.3.9.1