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

---