<!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"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.6"/>
<title>libmtp: The folder management API.</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">libmtp
 <span id="projectnumber">1.1.9</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.6 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<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="examples.html"><span>Examples</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">The folder management API.</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga41ca45f32991139137f9895ebb3fe2e0"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">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 class="separator:ga41ca45f32991139137f9895ebb3fe2e0"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gafa7e48d4a9f0cbccf0f0d126dc769d6c"><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="group__types.html#ga1c9860c6a73573226b55e4c5093040de">LIBMTP_folder_t</a> *)</td></tr>
<tr class="separator:gafa7e48d4a9f0cbccf0f0d126dc769d6c"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga37f9714e570baccaf7af42070ad3025f"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">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="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *)</td></tr>
<tr class="separator:ga37f9714e570baccaf7af42070ad3025f"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga8caef6bc8509f5e79691547a7ba49868"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">LIBMTP_folder_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__folders.html#ga8caef6bc8509f5e79691547a7ba49868">LIBMTP_Get_Folder_List_For_Storage</a> (<a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, uint32_t const)</td></tr>
<tr class="separator:ga8caef6bc8509f5e79691547a7ba49868"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga8c33717535ac6857f1de4ec459829a96"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">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="group__types.html#ga1c9860c6a73573226b55e4c5093040de">LIBMTP_folder_t</a> *, uint32_t const)</td></tr>
<tr class="separator:ga8c33717535ac6857f1de4ec459829a96"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:gaae978fbe5de151bf34ba239355e83a99"><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="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, char *, uint32_t, uint32_t)</td></tr>
<tr class="separator:gaae978fbe5de151bf34ba239355e83a99"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga0ae4801cb30d03795d4439d98b1b4bca"><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="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, <a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">LIBMTP_folder_t</a> *, const char *)</td></tr>
<tr class="separator:ga0ae4801cb30d03795d4439d98b1b4bca"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="gaae978fbe5de151bf34ba239355e83a99"></a>
<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="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">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>
</tr>
<tr>
<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 class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">device</td><td>a pointer to the device to create the folder on. </td></tr>
<tr><td class="paramname">name</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 class="paramname">parent_id</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 class="paramname">storage_id</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="section return"><dt>Returns</dt><dd>id to new folder or 0 if an error occured </dd></dl>
<p>References <a class="el" href="device-flags_8h.html#a009f4afd1f5c4d2dd65dc275b9130dc9">DEVICE_FLAG_BROKEN_SEND_OBJECT_PROPLIST</a>, <a class="el" href="structLIBMTP__mtpdevice__struct.html#aca6eb02fe46e8da41adb54e048176b42">LIBMTP_mtpdevice_struct::params</a>, <a class="el" href="unicode_8c.html#a2bda980f6207cb48ca2e8103f07dfb58">strip_7bit_from_utf8()</a>, and <a class="el" href="structLIBMTP__mtpdevice__struct.html#a5560f6638d9626ab26a2be48e9585ad1">LIBMTP_mtpdevice_struct::usbinfo</a>.</p>
</div>
</div>
<a class="anchor" id="gafa7e48d4a9f0cbccf0f0d126dc769d6c"></a>
<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="group__types.html#ga1c9860c6a73573226b55e4c5093040de">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 class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">folder</td><td>folder structure to destroy </td></tr>
</table>
</dd>
</dl>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__folders.html#ga41ca45f32991139137f9895ebb3fe2e0">LIBMTP_new_folder_t()</a> </dd></dl>
<p>References <a class="el" href="structLIBMTP__folder__struct.html#a62cb2380be7cf422b4994081e6d1794a">LIBMTP_folder_struct::child</a>, <a class="el" href="group__folders.html#gafa7e48d4a9f0cbccf0f0d126dc769d6c">LIBMTP_destroy_folder_t()</a>, <a class="el" href="structLIBMTP__folder__struct.html#ab75c793c818e9258e9f953589c435c20">LIBMTP_folder_struct::name</a>, and <a class="el" href="structLIBMTP__folder__struct.html#a0f17c5efb1dca0428d6282aa5d634c39">LIBMTP_folder_struct::sibling</a>.</p>
<p>Referenced by <a class="el" href="group__folders.html#gafa7e48d4a9f0cbccf0f0d126dc769d6c">LIBMTP_destroy_folder_t()</a>, and <a class="el" href="group__folders.html#ga8caef6bc8509f5e79691547a7ba49868">LIBMTP_Get_Folder_List_For_Storage()</a>.</p>
</div>
</div>
<a class="anchor" id="ga8c33717535ac6857f1de4ec459829a96"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">LIBMTP_folder_t</a>* LIBMTP_Find_Folder </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">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>
</tr>
<tr>
<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 class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">folderlist</td><td>list of folders to search id of folder to look for </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>a folder or NULL if not found </dd></dl>
<p>References <a class="el" href="structLIBMTP__folder__struct.html#a62cb2380be7cf422b4994081e6d1794a">LIBMTP_folder_struct::child</a>, <a class="el" href="structLIBMTP__folder__struct.html#a01cc1f244c7af1ea71f9f4feb015d034">LIBMTP_folder_struct::folder_id</a>, <a class="el" href="group__folders.html#ga8c33717535ac6857f1de4ec459829a96">LIBMTP_Find_Folder()</a>, and <a class="el" href="structLIBMTP__folder__struct.html#a0f17c5efb1dca0428d6282aa5d634c39">LIBMTP_folder_struct::sibling</a>.</p>
<p>Referenced by <a class="el" href="group__folders.html#ga8c33717535ac6857f1de4ec459829a96">LIBMTP_Find_Folder()</a>.</p>
</div>
</div>
<a class="anchor" id="ga37f9714e570baccaf7af42070ad3025f"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">LIBMTP_folder_t</a>* LIBMTP_Get_Folder_List </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">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 class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">device</td><td>a pointer to the device to get the folder listing for. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>a list of folders </dd></dl>
<p>References <a class="el" href="group__folders.html#ga8caef6bc8509f5e79691547a7ba49868">LIBMTP_Get_Folder_List_For_Storage()</a>.</p>
</div>
</div>
<a class="anchor" id="ga8caef6bc8509f5e79691547a7ba49868"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">LIBMTP_folder_t</a>* LIBMTP_Get_Folder_List_For_Storage </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> * </td>
<td class="paramname"><em>device</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint32_t const </td>
<td class="paramname"><em>storage</em> </td>
</tr>
<tr>
<td></td>
<td>)</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 class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">device</td><td>a pointer to the device to get the folder listing for. </td></tr>
<tr><td class="paramname">storage</td><td>a storage ID to get the folder list from </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>a list of folders </dd></dl>
<p>References <a class="el" href="structLIBMTP__folder__struct.html#a62cb2380be7cf422b4994081e6d1794a">LIBMTP_folder_struct::child</a>, <a class="el" href="structLIBMTP__folder__struct.html#a01cc1f244c7af1ea71f9f4feb015d034">LIBMTP_folder_struct::folder_id</a>, <a class="el" href="group__folders.html#gafa7e48d4a9f0cbccf0f0d126dc769d6c">LIBMTP_destroy_folder_t()</a>, <a class="el" href="group__folders.html#ga41ca45f32991139137f9895ebb3fe2e0">LIBMTP_new_folder_t()</a>, <a class="el" href="structLIBMTP__folder__struct.html#ab75c793c818e9258e9f953589c435c20">LIBMTP_folder_struct::name</a>, <a class="el" href="structLIBMTP__mtpdevice__struct.html#aca6eb02fe46e8da41adb54e048176b42">LIBMTP_mtpdevice_struct::params</a>, <a class="el" href="structLIBMTP__folder__struct.html#a86d5a8990f20c2d298cae9a6ab9c6f52">LIBMTP_folder_struct::parent_id</a>, <a class="el" href="structLIBMTP__folder__struct.html#a0f17c5efb1dca0428d6282aa5d634c39">LIBMTP_folder_struct::sibling</a>, and <a class="el" href="structLIBMTP__folder__struct.html#aed4feacc92138d292fbc030a213a7392">LIBMTP_folder_struct::storage_id</a>.</p>
<p>Referenced by <a class="el" href="group__folders.html#ga37f9714e570baccaf7af42070ad3025f">LIBMTP_Get_Folder_List()</a>.</p>
</div>
</div>
<a class="anchor" id="ga41ca45f32991139137f9895ebb3fe2e0"></a>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__types.html#ga1c9860c6a73573226b55e4c5093040de">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="section return"><dt>Returns</dt><dd>a pointer to the newly allocated folder structure. </dd></dl>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="group__folders.html#gafa7e48d4a9f0cbccf0f0d126dc769d6c">LIBMTP_destroy_folder_t()</a> </dd></dl>
<p>References <a class="el" href="structLIBMTP__folder__struct.html#a01cc1f244c7af1ea71f9f4feb015d034">LIBMTP_folder_struct::folder_id</a>.</p>
<p>Referenced by <a class="el" href="group__folders.html#ga8caef6bc8509f5e79691547a7ba49868">LIBMTP_Get_Folder_List_For_Storage()</a>.</p>
</div>
</div>
<a class="anchor" id="ga0ae4801cb30d03795d4439d98b1b4bca"></a>
<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="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">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="group__types.html#ga1c9860c6a73573226b55e4c5093040de">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>
</tr>
<tr>
<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 class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">device</td><td>a pointer to the device that contains the file. </td></tr>
<tr><td class="paramname">folder</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 class="paramname">newname</td><td>the new name for this object. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success, any other value means failure. </dd></dl>
<p>References <a class="el" href="structLIBMTP__folder__struct.html#a01cc1f244c7af1ea71f9f4feb015d034">LIBMTP_folder_struct::folder_id</a>, and <a class="el" href="structLIBMTP__folder__struct.html#ab75c793c818e9258e9f953589c435c20">LIBMTP_folder_struct::name</a>.</p>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.6
</small></address>
</body>
</html>
