<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libmtp: The folder management API.</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.2 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>The folder management API.</h1><table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__folders.html#ga41ca45f32991139137f9895ebb3fe2e0">LIBMTP_new_folder_t</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__folders.html#gafa7e48d4a9f0cbccf0f0d126dc769d6c">LIBMTP_destroy_folder_t</a> (<a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> *)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__folders.html#ga37f9714e570baccaf7af42070ad3025f">LIBMTP_Get_Folder_List</a> (<a class="el" href="structLIBMTP__mtpdevice__struct.html">LIBMTP_mtpdevice_t</a> *)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__folders.html#ga8c33717535ac6857f1de4ec459829a96">LIBMTP_Find_Folder</a> (<a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> *, uint32_t const)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">uint32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__folders.html#gaae978fbe5de151bf34ba239355e83a99">LIBMTP_Create_Folder</a> (<a class="el" href="structLIBMTP__mtpdevice__struct.html">LIBMTP_mtpdevice_t</a> *, char *, uint32_t, uint32_t)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__folders.html#ga0ae4801cb30d03795d4439d98b1b4bca">LIBMTP_Set_Folder_Name</a> (<a class="el" href="structLIBMTP__mtpdevice__struct.html">LIBMTP_mtpdevice_t</a> *, <a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> *, const char *)</td></tr>
</table>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="gaae978fbe5de151bf34ba239355e83a99"></a><!-- doxytag: member="libmtp.h::LIBMTP_Create_Folder" ref="gaae978fbe5de151bf34ba239355e83a99" args="(LIBMTP_mtpdevice_t *, char *, uint32_t, uint32_t)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">uint32_t LIBMTP_Create_Folder </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structLIBMTP__mtpdevice__struct.html">LIBMTP_mtpdevice_t</a> * </td>
<td class="paramname"> <em>device</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>name</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t </td>
<td class="paramname"> <em>parent_id</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t </td>
<td class="paramname"> <em>storage_id</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>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".</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>device</em> </td><td>a pointer to the device to create the folder on. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>name</em> </td><td>the name of the new folder. Note this can be modified if the device does not support all the characters in the name. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>parent_id</em> </td><td>id of parent folder to add the new folder to, or 0 to put it in the root directory. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>storage_id</em> </td><td>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. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>id to new folder or 0 if an error occured </dd></dl>
<p>References <a class="el" href="libmtp_8h_source.html#l00580">LIBMTP_mtpdevice_struct::params</a>, <a class="el" href="unicode_8c_source.html#l00151">strip_7bit_from_utf8()</a>, and <a class="el" href="libmtp_8h_source.html#l00585">LIBMTP_mtpdevice_struct::usbinfo</a>.</p>
</div>
</div>
<a class="anchor" id="gafa7e48d4a9f0cbccf0f0d126dc769d6c"></a><!-- doxytag: member="libmtp.h::LIBMTP_destroy_folder_t" ref="gafa7e48d4a9f0cbccf0f0d126dc769d6c" args="(LIBMTP_folder_t *)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void LIBMTP_destroy_folder_t </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> * </td>
<td class="paramname"> <em>folder</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This recursively deletes the memory for a folder structure. This shall typically be called on a top-level folder list to detsroy the entire folder tree.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>folder</em> </td><td>folder structure to destroy </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__folders.html#ga41ca45f32991139137f9895ebb3fe2e0">LIBMTP_new_folder_t()</a> </dd></dl>
<p>References <a class="el" href="libmtp_8h_source.html#l00704">LIBMTP_folder_struct::child</a>, <a class="el" href="libmtp_8c_source.html#l06480">LIBMTP_destroy_folder_t()</a>, <a class="el" href="libmtp_8h_source.html#l00702">LIBMTP_folder_struct::name</a>, and <a class="el" href="libmtp_8h_source.html#l00703">LIBMTP_folder_struct::sibling</a>.</p>
<p>Referenced by <a class="el" href="libmtp_8c_source.html#l06480">LIBMTP_destroy_folder_t()</a>, and <a class="el" href="libmtp_8c_source.html#l06579">LIBMTP_Get_Folder_List()</a>.</p>
</div>
</div>
<a class="anchor" id="ga8c33717535ac6857f1de4ec459829a96"></a><!-- doxytag: member="libmtp.h::LIBMTP_Find_Folder" ref="ga8c33717535ac6857f1de4ec459829a96" args="(LIBMTP_folder_t *, uint32_t const)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a>* LIBMTP_Find_Folder </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> * </td>
<td class="paramname"> <em>folderlist</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t </td>
<td class="paramname"> <em>id</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Helper function. Returns a folder structure for a specified id.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>folderlist</em> </td><td>list of folders to search id of folder to look for </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a folder or NULL if not found </dd></dl>
<p>References <a class="el" href="libmtp_8h_source.html#l00704">LIBMTP_folder_struct::child</a>, <a class="el" href="libmtp_8h_source.html#l00699">LIBMTP_folder_struct::folder_id</a>, <a class="el" href="libmtp_8c_source.html#l06511">LIBMTP_Find_Folder()</a>, and <a class="el" href="libmtp_8h_source.html#l00703">LIBMTP_folder_struct::sibling</a>.</p>
<p>Referenced by <a class="el" href="libmtp_8c_source.html#l06511">LIBMTP_Find_Folder()</a>.</p>
</div>
</div>
<a class="anchor" id="ga37f9714e570baccaf7af42070ad3025f"></a><!-- doxytag: member="libmtp.h::LIBMTP_Get_Folder_List" ref="ga37f9714e570baccaf7af42070ad3025f" args="(LIBMTP_mtpdevice_t *)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a>* LIBMTP_Get_Folder_List </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structLIBMTP__mtpdevice__struct.html">LIBMTP_mtpdevice_t</a> * </td>
<td class="paramname"> <em>device</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This returns a list of all folders available on the current MTP device.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>device</em> </td><td>a pointer to the device to get the folder listing for. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a list of folders </dd></dl>
<p>References <a class="el" href="libmtp_8h_source.html#l00704">LIBMTP_folder_struct::child</a>, <a class="el" href="libmtp_8h_source.html#l00699">LIBMTP_folder_struct::folder_id</a>, <a class="el" href="libmtp_8c_source.html#l06480">LIBMTP_destroy_folder_t()</a>, <a class="el" href="libmtp_8c_source.html#l06457">LIBMTP_new_folder_t()</a>, <a class="el" href="libmtp_8h_source.html#l00702">LIBMTP_folder_struct::name</a>, <a class="el" href="libmtp_8h_source.html#l00580">LIBMTP_mtpdevice_struct::params</a>, <a class="el" href="libmtp_8h_source.html#l00700">LIBMTP_folder_struct::parent_id</a>, <a class="el" href="libmtp_8h_source.html#l00703">LIBMTP_folder_struct::sibling</a>, and <a class="el" href="libmtp_8h_source.html#l00701">LIBMTP_folder_struct::storage_id</a>.</p>
</div>
</div>
<a class="anchor" id="ga41ca45f32991139137f9895ebb3fe2e0"></a><!-- doxytag: member="libmtp.h::LIBMTP_new_folder_t" ref="ga41ca45f32991139137f9895ebb3fe2e0" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a>* LIBMTP_new_folder_t </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>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 <code>LIBMTP_folder_track_t</code> operation later, so be careful of using strdup() when assigning strings, e.g.:</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>a pointer to the newly allocated folder structure. </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__folders.html#gafa7e48d4a9f0cbccf0f0d126dc769d6c">LIBMTP_destroy_folder_t()</a> </dd></dl>
<p>References <a class="el" href="libmtp_8h_source.html#l00699">LIBMTP_folder_struct::folder_id</a>.</p>
<p>Referenced by <a class="el" href="libmtp_8c_source.html#l06579">LIBMTP_Get_Folder_List()</a>.</p>
</div>
</div>
<a class="anchor" id="ga0ae4801cb30d03795d4439d98b1b4bca"></a><!-- doxytag: member="libmtp.h::LIBMTP_Set_Folder_Name" ref="ga0ae4801cb30d03795d4439d98b1b4bca" args="(LIBMTP_mtpdevice_t *, LIBMTP_folder_t *, const char *)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int LIBMTP_Set_Folder_Name </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structLIBMTP__mtpdevice__struct.html">LIBMTP_mtpdevice_t</a> * </td>
<td class="paramname"> <em>device</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structLIBMTP__folder__struct.html">LIBMTP_folder_t</a> * </td>
<td class="paramname"> <em>folder</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>newname</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This function renames a single folder. This simply means that the PTP_OPC_ObjectFileName property is updated, if this is supported by the device.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>device</em> </td><td>a pointer to the device that contains the file. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>folder</em> </td><td>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. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>newname</em> </td><td>the new name for this object. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success, any other value means failure. </dd></dl>
<p>References <a class="el" href="libmtp_8h_source.html#l00699">LIBMTP_folder_struct::folder_id</a>, and <a class="el" href="libmtp_8h_source.html#l00702">LIBMTP_folder_struct::name</a>.</p>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.2 </small></address>
</body>
</html>
