NAME
libmtp - The track management API.
Functions
LIBMTP_track_t * LIBMTP_new_track_t (void)
void LIBMTP_destroy_track_t (LIBMTP_track_t *)
LIBMTP_track_t * LIBMTP_Get_Tracklisting (LIBMTP_mtpdevice_t *)
LIBMTP_track_t * LIBMTP_Get_Tracklisting_With_Callback
(LIBMTP_mtpdevice_t *, LIBMTP_progressfunc_t const, void const
*const)
LIBMTP_track_t * LIBMTP_Get_Tracklisting_With_Callback_For_Storage
(LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_progressfunc_t const,
void const *const)
LIBMTP_track_t * LIBMTP_Get_Trackmetadata (LIBMTP_mtpdevice_t *,
uint32_t const)
int LIBMTP_Get_Track_To_File (LIBMTP_mtpdevice_t *, uint32_t, char
const *const, LIBMTP_progressfunc_t const, void const *const)
int LIBMTP_Get_Track_To_File_Descriptor (LIBMTP_mtpdevice_t *, uint32_t
const, int const, LIBMTP_progressfunc_t const, void const *const)
int LIBMTP_Get_Track_To_Handler (LIBMTP_mtpdevice_t *, uint32_t const,
MTPDataPutFunc, void *, LIBMTP_progressfunc_t const, void const
*const)
int LIBMTP_Send_Track_From_File (LIBMTP_mtpdevice_t *, char const
*const, LIBMTP_track_t *const, LIBMTP_progressfunc_t const, void
const *const)
int LIBMTP_Send_Track_From_File_Descriptor (LIBMTP_mtpdevice_t *, int
const, LIBMTP_track_t *const, LIBMTP_progressfunc_t const, void
const *const)
int LIBMTP_Send_Track_From_Handler (LIBMTP_mtpdevice_t *,
MTPDataGetFunc, void *, LIBMTP_track_t *const,
LIBMTP_progressfunc_t const, void const *const)
int LIBMTP_Update_Track_Metadata (LIBMTP_mtpdevice_t *, LIBMTP_track_t
const *const)
int LIBMTP_Track_Exists (LIBMTP_mtpdevice_t *, uint32_t)
int LIBMTP_Set_Track_Name (LIBMTP_mtpdevice_t *, LIBMTP_track_t *,
const char *)
Function Documentation
void LIBMTP_destroy_track_t (LIBMTP_track_t * track) This destroys a track
metadata structure and deallocates the memory used by it, including any
strings. Never use a track metadata structure again after calling this
function on it.
Parameters:
track the track metadata to destroy.
See also:
LIBMTP_new_track_t()
References LIBMTP_track_struct::album, LIBMTP_track_struct::artist,
LIBMTP_track_struct::composer, LIBMTP_track_struct::date,
LIBMTP_track_struct::filename, LIBMTP_track_struct::genre, and
LIBMTP_track_struct::title.
Referenced by LIBMTP_Get_Tracklisting_With_Callback_For_Storage(), and
LIBMTP_Get_Trackmetadata().
int LIBMTP_Get_Track_To_File (LIBMTP_mtpdevice_t * device, uint32_t const
id, char const *const path, LIBMTP_progressfunc_t const callback,
void const *const data) This gets a track off the device to a file
identified by a filename. This is actually just a wrapper for the
LIBMTP_Get_Track_To_File() function.
Parameters:
device a pointer to the device to get the track from.
id the track ID of the track to retrieve.
path a filename to use for the retrieved track.
callback a progress indicator function or NULL to ignore.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
0 if the transfer was successful, any other value means failure.
See also:
LIBMTP_Get_Track_To_File_Descriptor()
References LIBMTP_Get_File_To_File().
int LIBMTP_Get_Track_To_File_Descriptor (LIBMTP_mtpdevice_t * device,
uint32_t const id, int const fd, LIBMTP_progressfunc_t const
callback, void const *const data) This gets a track off the device to
a file identified by a file descriptor. This is actually just a wrapper
for the LIBMTP_Get_File_To_File_Descriptor() function.
Parameters:
device a pointer to the device to get the track from.
id the track ID of the track to retrieve.
fd a file descriptor to write the track to.
callback a progress indicator function or NULL to ignore.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
0 if the transfer was successful, any other value means failure.
See also:
LIBMTP_Get_Track_To_File()
References LIBMTP_Get_File_To_File_Descriptor().
int LIBMTP_Get_Track_To_Handler (LIBMTP_mtpdevice_t * device, uint32_t
const id, MTPDataPutFunc put_func, void * priv, LIBMTP_progressfunc_t
const callback, void const *const data) This gets a track off the
device to a handler function. This is actually just a wrapper for the
LIBMTP_Get_File_To_Handler() function.
Parameters:
device a pointer to the device to get the track from.
id the track ID of the track to retrieve.
put_func the function to call when we have data.
priv the user-defined pointer that is passed to put_func.
callback a progress indicator function or NULL to ignore.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
0 if the transfer was successful, any other value means failure.
References LIBMTP_Get_File_To_Handler().
LIBMTP_track_t* LIBMTP_Get_Tracklisting (LIBMTP_mtpdevice_t * device) THIS
FUNCTION IS DEPRECATED. PLEASE UPDATE YOUR CODE IN ORDER NOT TO USE IT.
See also:
LIBMTP_Get_Tracklisting_With_Callback()
References LIBMTP_Get_Tracklisting_With_Callback().
LIBMTP_track_t* LIBMTP_Get_Tracklisting_With_Callback (LIBMTP_mtpdevice_t *
device, LIBMTP_progressfunc_t const callback, void const *const data)
This returns a long list of all tracks available on the current MTP
device. Tracks include multimedia objects, both music tracks and video
tracks. Typical usage:
LIBMTP_track_t *tracklist;
tracklist = LIBMTP_Get_Tracklisting_With_Callback(device, callback, data);
while (tracklist != NULL) {
LIBMTP_track_t *tmp;
// Do something on each element in the list here...
tmp = tracklist;
tracklist = tracklist->next;
LIBMTP_destroy_track_t(tmp);
}
If you want to group your track listing by storage (per storage unit)
or arrange tracks into folders, you must dereference the storage_id
and/or parent_id field of the returned LIBMTP_track_t struct. To
arrange by folders or files you typically have to create the proper
trees by calls to LIBMTP_Get_Storage() and/or LIBMTP_Get_Folder_List()
first.
Parameters:
device a pointer to the device to get the track listing for.
callback a function to be called during the tracklisting retrieveal
for displaying progress bars etc, or NULL if you don't want any
callbacks.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
a list of tracks that can be followed using the next field of the
LIBMTP_track_t data structure. Each of the metadata tags must be
freed after use, and may contain only partial metadata information,
i.e. one or several fields may be NULL or 0.
See also:
LIBMTP_Get_Trackmetadata()
References LIBMTP_Get_Tracklisting_With_Callback_For_Storage().
Referenced by LIBMTP_Get_Tracklisting().
LIBMTP_track_t* LIBMTP_Get_Tracklisting_With_Callback_For_Storage
(LIBMTP_mtpdevice_t * device, uint32_t const storage_id,
LIBMTP_progressfunc_t const callback, void const *const data) This
returns a long list of all tracks available on the current MTP device.
Tracks include multimedia objects, both music tracks and video tracks.
Typical usage:
LIBMTP_track_t *tracklist;
tracklist = LIBMTP_Get_Tracklisting_With_Callback_For_Storage(device, storage_id, callback, data);
while (tracklist != NULL) {
LIBMTP_track_t *tmp;
// Do something on each element in the list here...
tmp = tracklist;
tracklist = tracklist->next;
LIBMTP_destroy_track_t(tmp);
}
If you want to group your track listing by storage (per storage unit)
or arrange tracks into folders, you must dereference the storage_id
and/or parent_id field of the returned LIBMTP_track_t struct. To
arrange by folders or files you typically have to create the proper
trees by calls to LIBMTP_Get_Storage() and/or LIBMTP_Get_Folder_List()
first.
Parameters:
device a pointer to the device to get the track listing for.
storage_id ID of device storage (if null, no filter)
callback a function to be called during the tracklisting retrieveal
for displaying progress bars etc, or NULL if you don't want any
callbacks.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
a list of tracks that can be followed using the next field of the
LIBMTP_track_t data structure. Each of the metadata tags must be
freed after use, and may contain only partial metadata information,
i.e. one or several fields may be NULL or 0.
See also:
LIBMTP_Get_Trackmetadata()
References LIBMTP_track_struct::filename,
LIBMTP_track_struct::filesize, LIBMTP_track_struct::filetype,
LIBMTP_track_struct::item_id, LIBMTP_destroy_track_t(),
LIBMTP_FILETYPE_IS_TRACK, LIBMTP_new_track_t(),
LIBMTP_track_struct::modificationdate, LIBMTP_track_struct::next,
LIBMTP_mtpdevice_struct::params, LIBMTP_track_struct::parent_id,
LIBMTP_track_struct::storage_id, and LIBMTP_mtpdevice_struct::usbinfo.
Referenced by LIBMTP_Get_Tracklisting_With_Callback().
LIBMTP_track_t* LIBMTP_Get_Trackmetadata (LIBMTP_mtpdevice_t * device,
uint32_t const trackid) This function retrieves the metadata for a
single track off the device.
Do not call this function repeatedly! The track handles are linearly
searched O(n) and the call may involve (slow) USB traffic, so use
LIBMTP_Get_Tracklisting() and cache the tracks, preferably as an
efficient data structure such as a hash list.
Parameters:
device a pointer to the device to get the track metadata from.
trackid the object ID of the track that you want the metadata for.
Returns:
a track metadata entry on success or NULL on failure.
See also:
LIBMTP_Get_Tracklisting()
References LIBMTP_track_struct::filename,
LIBMTP_track_struct::filesize, LIBMTP_track_struct::filetype,
LIBMTP_track_struct::item_id, LIBMTP_destroy_track_t(),
LIBMTP_FILETYPE_IS_TRACK, LIBMTP_new_track_t(),
LIBMTP_track_struct::modificationdate, LIBMTP_mtpdevice_struct::params,
LIBMTP_track_struct::parent_id, LIBMTP_track_struct::storage_id, and
LIBMTP_mtpdevice_struct::usbinfo.
LIBMTP_track_t* LIBMTP_new_track_t (void) This creates a new track metadata
structure and allocates memory for it. Notice that if you add strings
to this structure they will be freed by the corresponding
LIBMTP_destroy_track_t operation later, so be careful of using strdup()
when assigning strings, e.g.:
LIBMTP_track_t *track = LIBMTP_new_track_t();
track->title = strdup(titlestr);
....
LIBMTP_destroy_track_t(track);
Returns:
a pointer to the newly allocated metadata structure.
See also:
LIBMTP_destroy_track_t()
References LIBMTP_track_struct::item_id.
Referenced by LIBMTP_Get_Tracklisting_With_Callback_For_Storage(), and
LIBMTP_Get_Trackmetadata().
int LIBMTP_Send_Track_From_File (LIBMTP_mtpdevice_t * device, char const
*const path, LIBMTP_track_t *const metadata, LIBMTP_progressfunc_t
const callback, void const *const data) This function sends a track
from a local file to an MTP device. A filename and a set of metadata
must be given as input.
Parameters:
device a pointer to the device to send the track to.
path the filename of a local file which will be sent.
metadata a track metadata set to be written along with the file.
After this call the field metadata->item_id will contain the new
track ID. Other fields such as the metadata->filename,
metadata->parent_id or metadata->storage_id may also change during
this operation due to device restrictions, so do not rely on the
contents of this struct to be preserved in any way.
o metadata->parent_id should be set to the parent (e.g. folder) to
store this track in. Since some devices are a bit picky about
where files are placed, a default folder will be chosen if libmtp
has detected one for the current filetype and this parameter is
set to 0. If this is 0 and no default folder can be found, the
file will be stored in the root folder.
o metadata->storage_id should be set to the desired storage (e.g.
memory card or whatever your device presents) to store this track
in. Setting this to 0 will store the track on the primary
storage.
callback a progress indicator function or NULL to ignore.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
0 if the transfer was successful, any other value means failure.
See also:
LIBMTP_Send_Track_From_File_Descriptor()
LIBMTP_Send_File_From_File()
LIBMTP_Delete_Object()
References LIBMTP_Send_Track_From_File_Descriptor().
int LIBMTP_Send_Track_From_File_Descriptor (LIBMTP_mtpdevice_t * device,
int const fd, LIBMTP_track_t *const metadata, LIBMTP_progressfunc_t
const callback, void const *const data) This function sends a track
from a file descriptor to an MTP device. A filename and a set of
metadata must be given as input.
Parameters:
device a pointer to the device to send the track to.
fd the filedescriptor for a local file which will be sent.
metadata a track metadata set to be written along with the file.
After this call the field metadata->item_id will contain the new
track ID. Other fields such as the metadata->filename,
metadata->parent_id or metadata->storage_id may also change during
this operation due to device restrictions, so do not rely on the
contents of this struct to be preserved in any way.
o metadata->parent_id should be set to the parent (e.g. folder) to
store this track in. Since some devices are a bit picky about
where files are placed, a default folder will be chosen if libmtp
has detected one for the current filetype and this parameter is
set to 0. If this is 0 and no default folder can be found, the
file will be stored in the root folder.
o metadata->storage_id should be set to the desired storage (e.g.
memory card or whatever your device presents) to store this track
in. Setting this to 0 will store the track on the primary
storage.
callback a progress indicator function or NULL to ignore.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
0 if the transfer was successful, any other value means failure.
See also:
LIBMTP_Send_Track_From_File()
LIBMTP_Delete_Object()
References LIBMTP_track_struct::filename, LIBMTP_file_struct::filename,
LIBMTP_track_struct::filesize, LIBMTP_file_struct::filesize,
LIBMTP_file_struct::filetype, LIBMTP_track_struct::filetype,
LIBMTP_track_struct::item_id, LIBMTP_file_struct::item_id,
LIBMTP_FILETYPE_IS_TRACK, LIBMTP_Send_File_From_File_Descriptor(),
LIBMTP_Update_Track_Metadata(), LIBMTP_file_struct::next,
LIBMTP_mtpdevice_struct::params, LIBMTP_track_struct::parent_id,
LIBMTP_file_struct::parent_id, LIBMTP_track_struct::storage_id,
LIBMTP_file_struct::storage_id, and LIBMTP_mtpdevice_struct::usbinfo.
Referenced by LIBMTP_Send_Track_From_File().
int LIBMTP_Send_Track_From_Handler (LIBMTP_mtpdevice_t * device,
MTPDataGetFunc get_func, void * priv, LIBMTP_track_t *const metadata,
LIBMTP_progressfunc_t const callback, void const *const data) This
function sends a track from a handler function to an MTP device. A
filename and a set of metadata must be given as input.
Parameters:
device a pointer to the device to send the track to.
get_func the function to call when we have data.
priv the user-defined pointer that is passed to get_func.
metadata a track metadata set to be written along with the file.
After this call the field metadata->item_id will contain the new
track ID. Other fields such as the metadata->filename,
metadata->parent_id or metadata->storage_id may also change during
this operation due to device restrictions, so do not rely on the
contents of this struct to be preserved in any way.
o metadata->parent_id should be set to the parent (e.g. folder) to
store this track in. Since some devices are a bit picky about
where files are placed, a default folder will be chosen if libmtp
has detected one for the current filetype and this parameter is
set to 0. If this is 0 and no default folder can be found, the
file will be stored in the root folder.
o metadata->storage_id should be set to the desired storage (e.g.
memory card or whatever your device presents) to store this track
in. Setting this to 0 will store the track on the primary
storage.
callback a progress indicator function or NULL to ignore.
data a user-defined pointer that is passed along to the progress
function in order to pass along some user defined data to the
progress updates. If not used, set this to NULL.
Returns:
0 if the transfer was successful, any other value means failure.
See also:
LIBMTP_Send_Track_From_File()
LIBMTP_Delete_Object()
References LIBMTP_track_struct::filename, LIBMTP_file_struct::filename,
LIBMTP_track_struct::filesize, LIBMTP_file_struct::filesize,
LIBMTP_file_struct::filetype, LIBMTP_track_struct::filetype,
LIBMTP_track_struct::item_id, LIBMTP_file_struct::item_id,
LIBMTP_FILETYPE_IS_TRACK, LIBMTP_Send_File_From_Handler(),
LIBMTP_Update_Track_Metadata(), LIBMTP_file_struct::next,
LIBMTP_mtpdevice_struct::params, LIBMTP_track_struct::parent_id,
LIBMTP_file_struct::parent_id, LIBMTP_track_struct::storage_id,
LIBMTP_file_struct::storage_id, and LIBMTP_mtpdevice_struct::usbinfo.
int LIBMTP_Set_Track_Name (LIBMTP_mtpdevice_t * device, LIBMTP_track_t *
track, const char * newname) This function renames a single track. This
simply means that the PTP_OPC_ObjectFileName property is updated, if
this is supported by the device.
Parameters:
device a pointer to the device that contains the file.
track the track metadata of the track to rename. On success, the
filename member is updated. Be aware, that this name can be
different than newname depending of device restrictions.
newname the new filename for this object.
Returns:
0 on success, any other value means failure.
References LIBMTP_track_struct::filename,
LIBMTP_track_struct::filetype, and LIBMTP_track_struct::item_id.
int LIBMTP_Track_Exists (LIBMTP_mtpdevice_t * device, uint32_t const id)
Helper function. This indicates if a track exists on the device
Parameters:
device a pointer to the device to get the track from.
id the track ID of the track to retrieve.
Returns:
TRUE (!=0) if the track exists, FALSE (0) if not
References LIBMTP_mtpdevice_struct::params.
int LIBMTP_Update_Track_Metadata (LIBMTP_mtpdevice_t * device,
LIBMTP_track_t const *const metadata) This function updates the MTP
track object metadata on a single file identified by an object ID.
Parameters:
device a pointer to the device to update the track metadata on.
metadata a track metadata set to be written to the file. notice
that the track_id field of the metadata structure must be correct
so that the function can update the right file. If some properties
of this metadata are set to NULL (strings) or 0 (numerical values)
they will be discarded and the track will not be tagged with these
blank values.
Returns:
0 on success, any other value means failure. If some or all of the
properties fail to update we will still return success. On some
devices (notably iRiver T30) properties that exist cannot be
updated.
References LIBMTP_track_struct::album, LIBMTP_track_struct::artist,
LIBMTP_track_struct::bitrate, LIBMTP_track_struct::bitratetype,
LIBMTP_track_struct::composer, LIBMTP_track_struct::date,
LIBMTP_track_struct::duration, LIBMTP_track_struct::filetype,
LIBMTP_track_struct::genre, LIBMTP_track_struct::item_id,
LIBMTP_track_struct::nochannels, LIBMTP_mtpdevice_struct::params,
LIBMTP_track_struct::rating, LIBMTP_track_struct::samplerate,
LIBMTP_track_struct::title, LIBMTP_track_struct::tracknumber,
LIBMTP_mtpdevice_struct::usbinfo, LIBMTP_track_struct::usecount, and
LIBMTP_track_struct::wavecodec.
Referenced by LIBMTP_Send_Track_From_File_Descriptor(), and
LIBMTP_Send_Track_From_Handler().
Author
Generated automatically by Doxygen for libmtp from the source code.