libmtp: The track management API.

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()

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()

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()

LIBMTP_track_t* LIBMTP_Get_Tracklisting ( LIBMTP_mtpdevice_t * device )

This returns a long list of all tracks available on the current MTP device. Typical usage:

 LIBMTP_track_t *tracklist;

 tracklist = LIBMTP_Get_Tracklisting(device);
 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);
 }

Parameters:

device

a pointer to the device to get the track listing for.

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()

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()

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()

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,
		uint32_t const	parenthandle
	)

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.
	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.
	parenthandle	the parent (e.g. folder) to store this file 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.

Returns:: 0 if the transfer was successful, any other value means failure.

See also:: LIBMTP_Send_Track_From_File_Descriptor()
LIBMTP_Delete_Object()

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,
		uint32_t const	parenthandle
	)

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 `item_id` will contain the new track ID.
	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.
	parenthandle	the parent (e.g. folder) to store this file 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.

Returns:: 0 if the transfer was successful, any other value means failure.

See also:: LIBMTP_Send_Track_From_File()
LIBMTP_Delete_Object()

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 (1) if the track exists, FALSE (0) if not

int LIBMTP_Update_Track_Metadata	(	LIBMTP_mtpdevice_t *	device,
		LIBMTP_track_t const *const	metadata
	)

This function updates the MTP 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.


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_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_Send_Track_From_File (LIBMTP_mtpdevice_t , char const const, LIBMTP_track_t const, LIBMTP_progressfunc_t const, void const const, uint32_t const)
int	LIBMTP_Send_Track_From_File_Descriptor (LIBMTP_mtpdevice_t , int const, LIBMTP_track_t const, LIBMTP_progressfunc_t const, void const *const, uint32_t const)
int	LIBMTP_Update_Track_Metadata (LIBMTP_mtpdevice_t , LIBMTP_track_t const const)
int	LIBMTP_Track_Exists (LIBMTP_mtpdevice_t *, uint32_t)

The track management API.

Functions

Function Documentation