.TH "folders" 3 "Version 1.1.21" "libmtp" \" -*- nroff -*-
.ad l
.nh
.SH NAME
libmtp \- folders
.SH SYNOPSIS
.br
.PP
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBLIBMTP_folder_t\fP * \fBLIBMTP_new_folder_t\fP (void)"
.br
.ti -1c
.RI "void \fBLIBMTP_destroy_folder_t\fP (\fBLIBMTP_folder_t\fP *)"
.br
.ti -1c
.RI "\fBLIBMTP_folder_t\fP * \fBLIBMTP_Get_Folder_List\fP (\fBLIBMTP_mtpdevice_t\fP *)"
.br
.ti -1c
.RI "\fBLIBMTP_folder_t\fP * \fBLIBMTP_Get_Folder_List_For_Storage\fP (\fBLIBMTP_mtpdevice_t\fP *, uint32_t const)"
.br
.ti -1c
.RI "\fBLIBMTP_folder_t\fP * \fBLIBMTP_Find_Folder\fP (\fBLIBMTP_folder_t\fP *, uint32_t const)"
.br
.ti -1c
.RI "uint32_t \fBLIBMTP_Create_Folder\fP (\fBLIBMTP_mtpdevice_t\fP *, char *, uint32_t, uint32_t)"
.br
.ti -1c
.RI "int \fBLIBMTP_Set_Folder_Name\fP (\fBLIBMTP_mtpdevice_t\fP *, \fBLIBMTP_folder_t\fP *, const char *)"
.br
.in -1c
.SH "Detailed Description"
.PP 

.SH "Function Documentation"
.PP 
.SS "uint32_t LIBMTP_Create_Folder (\fBLIBMTP_mtpdevice_t\fP * device, char * name, uint32_t parent_id, uint32_t storage_id)"
This create a folder on the current MTP device\&. The PTP name for a folder is 'association'\&. The PTP/MTP devices does not have an internal 'folder' concept really, it contains a flat list of all files and some file are 'associations' that other files and folders may refer to as its 'parent'\&.
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device to create the folder on\&. 
.br
\fIname\fP the name of the new folder\&. Note this can be modified if the device does not support all the characters in the name\&. 
.br
\fIparent_id\fP id of parent folder to add the new folder to, or 0xFFFFFFFF to put it in the root directory\&. 
.br
\fIstorage_id\fP id of the storage to add this new folder to\&. notice that you cannot mismatch storage id and parent id: they must both be on the same storage! Pass in 0 if you want to create this folder on the default storage\&. 
.RE
.PP
\fBReturns\fP
.RS 4
id to new folder or 0 if an error occurred 
.RE
.PP

.PP
References \fBDEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST\fP, \fBLIBMTP_mtpdevice_struct::params\fP, \fBstrip_7bit_from_utf8()\fP, and \fBLIBMTP_mtpdevice_struct::usbinfo\fP\&.
.SS "void LIBMTP_destroy_folder_t (\fBLIBMTP_folder_t\fP * folder)"
This recursively deletes the memory for a folder structure\&. This shall typically be called on a top-level folder list to destroy the entire folder tree\&.
.PP
\fBParameters\fP
.RS 4
\fIfolder\fP folder structure to destroy 
.RE
.PP
\fBSee also\fP
.RS 4
\fBLIBMTP_new_folder_t()\fP 
.RE
.PP

.PP
References \fBLIBMTP_folder_struct::child\fP, \fBLIBMTP_destroy_folder_t()\fP, \fBLIBMTP_folder_struct::name\fP, and \fBLIBMTP_folder_struct::sibling\fP\&.
.PP
Referenced by \fBLIBMTP_destroy_folder_t()\fP, and \fBLIBMTP_Get_Folder_List_For_Storage()\fP\&.
.SS "\fBLIBMTP_folder_t\fP * LIBMTP_Find_Folder (\fBLIBMTP_folder_t\fP * folderlist, uint32_t id)"
Helper function\&. Returns a folder structure for a specified id\&.
.PP
\fBParameters\fP
.RS 4
\fIfolderlist\fP list of folders to search @id id of folder to look for 
.RE
.PP
\fBReturns\fP
.RS 4
a folder or NULL if not found 
.RE
.PP

.PP
References \fBLIBMTP_folder_struct::child\fP, \fBLIBMTP_folder_struct::folder_id\fP, \fBLIBMTP_Find_Folder()\fP, and \fBLIBMTP_folder_struct::sibling\fP\&.
.PP
Referenced by \fBLIBMTP_Find_Folder()\fP\&.
.SS "\fBLIBMTP_folder_t\fP * LIBMTP_Get_Folder_List (\fBLIBMTP_mtpdevice_t\fP * device)"
This returns a list of all folders available on the current MTP device\&.
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device to get the folder listing for\&. 
.RE
.PP
\fBReturns\fP
.RS 4
a list of folders 
.RE
.PP

.PP
References \fBLIBMTP_Get_Folder_List_For_Storage()\fP\&.
.SS "\fBLIBMTP_folder_t\fP * LIBMTP_Get_Folder_List_For_Storage (\fBLIBMTP_mtpdevice_t\fP * device, uint32_t const storage)"
This returns a list of all folders available on the current MTP device\&.
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device to get the folder listing for\&. 
.br
\fIstorage\fP a storage ID to get the folder list from 
.RE
.PP
\fBReturns\fP
.RS 4
a list of folders 
.RE
.PP

.PP
References \fBLIBMTP_folder_struct::child\fP, \fBLIBMTP_folder_struct::folder_id\fP, \fBLIBMTP_destroy_folder_t()\fP, \fBLIBMTP_new_folder_t()\fP, \fBLIBMTP_folder_struct::name\fP, \fBLIBMTP_mtpdevice_struct::params\fP, \fBLIBMTP_folder_struct::parent_id\fP, \fBLIBMTP_folder_struct::sibling\fP, and \fBLIBMTP_folder_struct::storage_id\fP\&.
.PP
Referenced by \fBLIBMTP_Get_Folder_List()\fP\&.
.SS "\fBLIBMTP_folder_t\fP * LIBMTP_new_folder_t (void)"
This creates a new folder structure and allocates memory for it\&. Notice that if you add strings to this structure they will be freed by the corresponding \fCLIBMTP_folder_track_t\fP operation later, so be careful of using strdup() when assigning strings, e\&.g\&.:
.PP
\fBReturns\fP
.RS 4
a pointer to the newly allocated folder structure\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBLIBMTP_destroy_folder_t()\fP 
.RE
.PP

.PP
References \fBLIBMTP_folder_struct::folder_id\fP\&.
.PP
Referenced by \fBLIBMTP_Get_Folder_List_For_Storage()\fP\&.
.SS "int LIBMTP_Set_Folder_Name (\fBLIBMTP_mtpdevice_t\fP * device, \fBLIBMTP_folder_t\fP * folder, const char * newname)"
This function renames a single folder\&. This simply means that the PTP_OPC_ObjectFileName property is updated, if this is supported by the device\&.
.PP
\fBParameters\fP
.RS 4
\fIdevice\fP a pointer to the device that contains the file\&. 
.br
\fIfolder\fP the folder metadata of the folder to rename\&. On success, the name member is updated\&. Be aware, that this name can be different than newname depending of device restrictions\&. 
.br
\fInewname\fP the new name for this object\&. 
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, any other value means failure\&. 
.RE
.PP

.PP
References \fBLIBMTP_folder_struct::folder_id\fP, and \fBLIBMTP_folder_struct::name\fP\&.
.SH "Author"
.PP 
Generated automatically by Doxygen for libmtp from the source code\&.