libmtp  0.1.4
Functions
The file management API.

Functions

LIBMTP_file_tLIBMTP_new_file_t (void)
 
void LIBMTP_destroy_file_t (LIBMTP_file_t *)
 
char const * LIBMTP_Get_Filetype_Description (LIBMTP_filetype_t)
 
LIBMTP_file_tLIBMTP_Get_Filelisting (LIBMTP_mtpdevice_t *)
 
LIBMTP_file_tLIBMTP_Get_Filelisting_With_Callback (LIBMTP_mtpdevice_t *, LIBMTP_progressfunc_t const, void const *const)
 
LIBMTP_file_tLIBMTP_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)
 
LIBMTP_filesampledata_tLIBMTP_new_filesampledata_t (void)
 
void LIBMTP_destroy_filesampledata_t (LIBMTP_filesampledata_t *)
 
int LIBMTP_Get_Representative_Sample_Format (LIBMTP_mtpdevice_t *, LIBMTP_filetype_t const, LIBMTP_filesampledata_t **)
 
int LIBMTP_Send_Representative_Sample (LIBMTP_mtpdevice_t *, uint32_t const, LIBMTP_filesampledata_t *)
 

Detailed Description

Function Documentation

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
filethe file metadata to destroy.
See Also
LIBMTP_new_file_t()

References LIBMTP_file_struct::filename.

void LIBMTP_destroy_filesampledata_t ( LIBMTP_filesampledata_t sample)

This destroys a file sample metadata type.

Parameters
samplethe file sample metadata to be destroyed.

References LIBMTP_filesampledata_struct::data.

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
devicea pointer to the device to get the track from.
idthe file ID of the file to retrieve.
patha filename to use for the retrieved file.
callbacka progress indicator function or NULL to ignore.
dataa 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()

References LIBMTP_Get_File_To_File_Descriptor().

Referenced by LIBMTP_Get_Track_To_File().

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
devicea pointer to the device to get the file from.
idthe file ID of the file to retrieve.
fda local file descriptor to write the file to.
callbacka progress indicator function or NULL to ignore.
dataa 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()

References LIBMTP_mtpdevice_struct::params, and LIBMTP_mtpdevice_struct::usbinfo.

Referenced by LIBMTP_Get_File_To_File(), and LIBMTP_Get_Track_To_File_Descriptor().

LIBMTP_file_t* LIBMTP_Get_Filelisting ( LIBMTP_mtpdevice_t device)

THIS FUNCTION IS DEPRECATED. PLEASE UPDATE YOUR CODE IN ORDER NOT TO USE IT.

See Also
LIBMTP_Get_Filelisting_With_Callback()

References LIBMTP_Get_Filelisting_With_Callback().

LIBMTP_file_t* LIBMTP_Get_Filelisting_With_Callback ( LIBMTP_mtpdevice_t device,
LIBMTP_progressfunc_t const  callback,
void const *const  data 
)

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

LIBMTP_file_t *filelist;
filelist = LIBMTP_Get_Filelisting_With_Callback(device, callback, data);
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
devicea pointer to the device to get the file listing for.
callbacka function to be called during the tracklisting retrieveal for displaying progress bars etc, or NULL if you don't want any callbacks.
dataa 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 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()

References LIBMTP_file_struct::filename, LIBMTP_file_struct::filesize, LIBMTP_file_struct::filetype, LIBMTP_file_struct::item_id, LIBMTP_new_file_t(), LIBMTP_file_struct::next, LIBMTP_mtpdevice_struct::params, and LIBMTP_file_struct::parent_id.

Referenced by LIBMTP_Get_Filelisting().

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
devicea pointer to the device to get the file metadata from.
fileidthe 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()

References LIBMTP_file_struct::filename, LIBMTP_file_struct::filesize, LIBMTP_file_struct::filetype, LIBMTP_file_struct::item_id, LIBMTP_new_file_t(), LIBMTP_mtpdevice_struct::params, and LIBMTP_file_struct::parent_id.

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
intypethe libmtp internal filetype to get a description for.
Returns
a string representing the filetype, this must NOT be free():ed by the caller!

References filemap_struct::description, and filemap_struct::id.

int LIBMTP_Get_Representative_Sample_Format ( LIBMTP_mtpdevice_t device,
LIBMTP_filetype_t const  filetype,
LIBMTP_filesampledata_t **  sample 
)

This routine figures out whether a certain filetype supports representative samples (small thumbnail images) or not. This typically applies to JPEG files, MP3 files and Album abstract playlists, but in theory any filetype could support representative samples.

Parameters
devicea pointer to the device which is to be examined.
thefiletype to examine, and return the representative sample properties for.
samplethis will contain a new sample type with the fields filled in with suitable default values. For example, the supported sample type will be set, the supported height and width will be set to max values if it is an image sample, and duration will also be given some suitable default value which should not be exceeded on audio samples. If the device does not support samples for this filetype, this pointer will be NULL. If it is not NULL, the user must destroy this struct with LIBMTP_destroy_filesampledata_t() after use.
Returns
0 on success, any other value means failure.
See Also
LIBMTP_Send_Representative_Sample()
LIBMTP_Create_New_Album()

References LIBMTP_filesampledata_struct::duration, LIBMTP_filesampledata_struct::filetype, LIBMTP_filesampledata_struct::height, LIBMTP_new_filesampledata_t(), LIBMTP_mtpdevice_struct::params, and LIBMTP_filesampledata_struct::width.

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

References LIBMTP_file_struct::filename.

Referenced by LIBMTP_Get_Filelisting_With_Callback(), and LIBMTP_Get_Filemetadata().

LIBMTP_filesampledata_t* LIBMTP_new_filesampledata_t ( void  )

This creates a new sample data 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_sampledata_t operation later, so be careful of using strdup() when assigning strings.

Returns
a pointer to the newly allocated metadata structure.
See Also
LIBMTP_destroy_sampledata_t()

References LIBMTP_filesampledata_struct::height.

Referenced by LIBMTP_Get_Representative_Sample_Format().

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
devicea pointer to the device to send the track to.
paththe filename of a local file which will be sent.
filedataa file strtuct to pass in info about the file. After this call the field item_id will contain the new file ID.
callbacka progress indicator function or NULL to ignore.
dataa 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.
parenthandlethe 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()

References LIBMTP_Send_File_From_File_Descriptor().

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
devicea pointer to the device to send the file to.
fdthe filedescriptor for a local file which will be sent.
filedataa file strtuct to pass in info about the file. After this call the field item_id will contain the new track ID.
callbacka progress indicator function or NULL to ignore.
dataa 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.
parenthandlethe 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()

References LIBMTP_mtpdevice_struct::default_music_folder, LIBMTP_mtpdevice_struct::default_organizer_folder, LIBMTP_mtpdevice_struct::default_picture_folder, LIBMTP_mtpdevice_struct::default_text_folder, LIBMTP_mtpdevice_struct::default_video_folder, LIBMTP_file_struct::filename, LIBMTP_file_struct::filesize, LIBMTP_file_struct::filetype, LIBMTP_file_struct::item_id, LIBMTP_mtpdevice_struct::params, and LIBMTP_mtpdevice_struct::usbinfo.

Referenced by LIBMTP_Send_File_From_File().

int LIBMTP_Send_Representative_Sample ( LIBMTP_mtpdevice_t device,
uint32_t const  id,
LIBMTP_filesampledata_t sampledata 
)

This routine sends representative sample data for an object. This uses the RepresentativeSampleData property of the album, if the device supports it. The data should be of a format acceptable to the player (for iRiver and Creative, this seems to be JPEG) and must not be too large. (for a Creative, max seems to be about 20KB.) TODO: there must be a way to find the max size for an ObjectPropertyValue.

Parameters
devicea pointer to the device which the object is on.
idunique id of the object to set artwork for.
datapointer to an array of uint8_t containing the representative sample data.
sizenumber of bytes in the sample.
Returns
0 on success, any other value means failure.
See Also
LIBMTP_Get_Representative_Sample_Format()
LIBMTP_Create_New_Album()

References LIBMTP_filesampledata_struct::data, LIBMTP_filesampledata_struct::duration, LIBMTP_filesampledata_struct::filetype, LIBMTP_filesampledata_struct::height, LIBMTP_mtpdevice_struct::params, LIBMTP_filesampledata_struct::size, and LIBMTP_filesampledata_struct::width.