libmtp: The file management API.

void LIBMTP_destroy_file_t ( LIBMTP_file_t * file )

This destroys a file metadata structure and deallocates the memory used by it, including any strings. Never use a file metadata structure again after calling this function on it.

Parameters:

file

the file metadata to destroy.

See also:: LIBMTP_new_file_t()

int LIBMTP_Get_File_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 file off the device to a local file identified by a filename.

Parameters:

	device	a pointer to the device to get the track from.
	id	the file ID of the file to retrieve.
	path	a filename to use for the retrieved 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.

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

See also:: LIBMTP_Get_File_To_File_Descriptor()

int LIBMTP_Get_File_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 file off the device to a file identified by a file descriptor.

This function can potentially be used for streaming files off the device for playback or broadcast for example, by downloading the file into a stream sink e.g. a socket.

Parameters:

	device	a pointer to the device to get the file from.
	id	the file ID of the file to retrieve.
	fd	a local file descriptor to write the file 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_File_To_File()

LIBMTP_file_t* LIBMTP_Get_Filelisting ( LIBMTP_mtpdevice_t * device )

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

 LIBMTP_file_t *filelist;

 filelist = LIBMTP_Get_Filelisting(device);
 while (filelist != NULL) {
   LIBMTP_file_t *tmp;

   // Do something on each element in the list here...
   tmp = filelist;
   filelist = filelist->next;
   LIBMTP_destroy_file_t(tmp);
 }

Parameters:

device

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

Returns:: a list of files that can be followed using the next field of the LIBMTP_file_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_Filemetadata()

LIBMTP_file_t* LIBMTP_Get_Filemetadata	(	LIBMTP_mtpdevice_t *	device,
		uint32_t const	fileid
	)

This function retrieves the metadata for a single file off the device.

Do not call this function repeatedly! The file handles are linearly searched O(n) and the call may involve (slow) USB traffic, so use LIBMTP_Get_Filelisting() and cache the file, preferably as an efficient data structure such as a hash list.

Parameters:

	device	a pointer to the device to get the file metadata from.
	fileid	the object ID of the file that you want the metadata for.

Returns:: a metadata entry on success or NULL on failure.

See also:: LIBMTP_Get_Filelisting()

char const* LIBMTP_Get_Filetype_Description ( LIBMTP_filetype_t intype )

This helper function returns a textual description for a libmtp file type to be used in dialog boxes etc.

Parameters:

intype

the libmtp internal filetype to get a description for.

Returns:: a string representing the filetype, this must NOT be free():ed by the caller!

LIBMTP_file_t* LIBMTP_new_file_t ( void )

This creates a new file 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_file_t operation later, so be careful of using strdup() when assigning strings, e.g.:

 LIBMTP_file_t *file = LIBMTP_new_file_t();
 file->filename = strdup(namestr);
 ....
 LIBMTP_destroy_file_t(file);

Returns:: a pointer to the newly allocated metadata structure.

See also:: LIBMTP_destroy_file_t()

int LIBMTP_Send_File_From_File	(	LIBMTP_mtpdevice_t *	device,
		char const *const	path,
		LIBMTP_file_t *const	filedata,
		LIBMTP_progressfunc_t const	callback,
		void const *const	data,
		uint32_t const	parenthandle
	)

This function sends 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.
	filedata	a file strtuct to pass in info about the file. After this call the field `item_id` will contain the new file 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_File_From_File_Descriptor()
LIBMTP_Delete_Object()

int LIBMTP_Send_File_From_File_Descriptor	(	LIBMTP_mtpdevice_t *	device,
		int const	fd,
		LIBMTP_file_t *const	filedata,
		LIBMTP_progressfunc_t const	callback,
		void const *const	data,
		uint32_t const	parenthandle
	)

This function sends a generic file from a file descriptor to an MTP device. A filename and a set of metadata must be given as input.

This can potentially be used for sending in a stream of unknown length. Set filedata->filesize = (uint64_t) -1 to make libmtp send some dummy length to the device and just accept a stream up to some device-determined max length. There is not guarantee this will work on all devices... Remember to set correct metadata for the track with LIBMTP_Update_Track_Metadata() afterwards if it's a music file. (This doesn't seem to work very well right now.)

Parameters:

	device	a pointer to the device to send the file to.
	fd	the filedescriptor for a local file which will be sent.
	filedata	a file strtuct to pass in info about 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_File_From_File()
LIBMTP_Delete_Object()


Functions
LIBMTP_file_t *	LIBMTP_new_file_t (void)
void	LIBMTP_destroy_file_t (LIBMTP_file_t *)
char const *	LIBMTP_Get_Filetype_Description (LIBMTP_filetype_t)
LIBMTP_file_t *	LIBMTP_Get_Filelisting (LIBMTP_mtpdevice_t *)
LIBMTP_file_t *	LIBMTP_Get_Filemetadata (LIBMTP_mtpdevice_t *, uint32_t const)
int	LIBMTP_Get_File_To_File (LIBMTP_mtpdevice_t , uint32_t, char const const, LIBMTP_progressfunc_t const, void const *const)
int	LIBMTP_Get_File_To_File_Descriptor (LIBMTP_mtpdevice_t , uint32_t const, int const, LIBMTP_progressfunc_t const, void const const)
int	LIBMTP_Send_File_From_File (LIBMTP_mtpdevice_t , char const const, LIBMTP_file_t const, LIBMTP_progressfunc_t const, void const const, uint32_t const)
int	LIBMTP_Send_File_From_File_Descriptor (LIBMTP_mtpdevice_t , int const, LIBMTP_file_t const, LIBMTP_progressfunc_t const, void const *const, uint32_t const)

The file management API.

Functions

Function Documentation