<!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.13"/> <meta name="viewport" content="width=device-width, initial-scale=1"/> <title>libmtp: The audio/video album 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 id="projectalign" style="padding-left: 0.5em;"> <div id="projectname">libmtp  <span id="projectnumber">1.1.16</span> </div> </td> </tr> </tbody> </table> </div> <!-- end header part --> <!-- Generated by Doxygen 1.8.13 --> <script type="text/javascript" src="menudata.js"></script> <script type="text/javascript" src="menu.js"></script> <script type="text/javascript"> $(function() { initMenu('',false,false,'search.php','Search'); }); </script> <div id="main-nav"></div> </div><!-- top --> <div class="header"> <div class="summary"> <a href="#func-members">Functions</a> </div> <div class="headertitle"> <div class="title">The audio/video album 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:ga5083754634934f2bfe304e66dd679d31"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#ga5083754634934f2bfe304e66dd679d31">LIBMTP_new_album_t</a> (void)</td></tr> <tr class="separator:ga5083754634934f2bfe304e66dd679d31"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:ga59eeda2ae84ce07f2e69134d322c6c14"><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#ga59eeda2ae84ce07f2e69134d322c6c14">LIBMTP_destroy_album_t</a> (<a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> *)</td></tr> <tr class="separator:ga59eeda2ae84ce07f2e69134d322c6c14"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:gaf5286f0ef2b670357415e874c0b4ddef"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#gaf5286f0ef2b670357415e874c0b4ddef">LIBMTP_Get_Album_List</a> (<a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *)</td></tr> <tr class="separator:gaf5286f0ef2b670357415e874c0b4ddef"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:gaabdfcf73e4d8534fe7efd98501731098"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#gaabdfcf73e4d8534fe7efd98501731098">LIBMTP_Get_Album_List_For_Storage</a> (<a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, uint32_t const)</td></tr> <tr class="separator:gaabdfcf73e4d8534fe7efd98501731098"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:gae5f27a0d3bf5885cb32722fa401b675b"><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#gae5f27a0d3bf5885cb32722fa401b675b">LIBMTP_Get_Album</a> (<a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, uint32_t const)</td></tr> <tr class="separator:gae5f27a0d3bf5885cb32722fa401b675b"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:ga588192a48fdfc772dfe02a9c54b94109"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#ga588192a48fdfc772dfe02a9c54b94109">LIBMTP_Create_New_Album</a> (<a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, <a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> *const)</td></tr> <tr class="separator:ga588192a48fdfc772dfe02a9c54b94109"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:gaa450fa92015dc62ae770fd3792f33311"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#gaa450fa92015dc62ae770fd3792f33311">LIBMTP_Update_Album</a> (<a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, <a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> const *const)</td></tr> <tr class="separator:gaa450fa92015dc62ae770fd3792f33311"><td class="memSeparator" colspan="2"> </td></tr> <tr class="memitem:gaff1f64189550d75f737c3b8f3ff1cbb4"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__albums.html#gaff1f64189550d75f737c3b8f3ff1cbb4">LIBMTP_Set_Album_Name</a> (<a class="el" href="group__types.html#gac2e20fe8cf7ca4d2426e22865073db4f">LIBMTP_mtpdevice_t</a> *, <a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> *, const char *)</td></tr> <tr class="separator:gaff1f64189550d75f737c3b8f3ff1cbb4"><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 id="ga588192a48fdfc772dfe02a9c54b94109"></a> <h2 class="memtitle"><span class="permalink"><a href="#ga588192a48fdfc772dfe02a9c54b94109">◆ </a></span>LIBMTP_Create_New_Album()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int LIBMTP_Create_New_Album </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#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> *const </td> <td class="paramname"><em>metadata</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>This routine creates a new album based on the metadata supplied. If the <code>tracks</code> field of the metadata contains a track listing, these tracks will be added to the album. </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 new album on. </td></tr> <tr><td class="paramname">metadata</td><td>the metadata for the new album. If the function exits with success, the <code>album_id</code> field of this struct will contain the new ID of the album. <ul> <li> <code>metadata->parent_id</code> should be set to the parent (e.g. folder) to store this track 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. </li> <li> <code>metadata->storage_id</code> should be set to the desired storage (e.g. memory card or whatever your device presents) to store this track in. Setting this to 0 will store the track on the primary storage. </li> </ul> </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>0 on success, any other value means failure. </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#gaa450fa92015dc62ae770fd3792f33311">LIBMTP_Update_Album()</a> </dd> <dd> <a class="el" href="group__objects.html#gac867594319fa48a0d6077d17aaf66222">LIBMTP_Delete_Object()</a> </dd></dl> <p class="reference">References <a class="el" href="structLIBMTP__mtpdevice__struct.html#a93bbee4f3c0c9b54ca2d4741f4f7e4db">LIBMTP_mtpdevice_struct::default_album_folder</a>, <a class="el" href="structLIBMTP__mtpdevice__struct.html#ab3c299ac4308bb8eb8c405ae3b6c9572">LIBMTP_mtpdevice_struct::default_music_folder</a>, and <a class="el" href="structLIBMTP__album__struct.html#a23a12e56994f63f4ddc90818c6db70be">LIBMTP_album_struct::parent_id</a>.</p> </div> </div> <a id="ga59eeda2ae84ce07f2e69134d322c6c14"></a> <h2 class="memtitle"><span class="permalink"><a href="#ga59eeda2ae84ce07f2e69134d322c6c14">◆ </a></span>LIBMTP_destroy_album_t()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">void LIBMTP_destroy_album_t </td> <td>(</td> <td class="paramtype"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> * </td> <td class="paramname"><em>album</em></td><td>)</td> <td></td> </tr> </table> </div><div class="memdoc"> <p>This recursively deletes the memory for an album structure</p> <dl class="params"><dt>Parameters</dt><dd> <table class="params"> <tr><td class="paramname">album</td><td>structure to destroy </td></tr> </table> </dd> </dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#ga5083754634934f2bfe304e66dd679d31">LIBMTP_new_album_t()</a> </dd></dl> <p class="reference">References <a class="el" href="structLIBMTP__album__struct.html#ac310c8376aba3677471f9e3a46ce7152">LIBMTP_album_struct::artist</a>, <a class="el" href="structLIBMTP__album__struct.html#adc7e7d63735fd0ae4bc2b021e8d5de97">LIBMTP_album_struct::composer</a>, <a class="el" href="structLIBMTP__album__struct.html#aeb73b165ca2e8f7b33cbfc6ef55e98e2">LIBMTP_album_struct::genre</a>, <a class="el" href="structLIBMTP__album__struct.html#a7b3a34bd30d6f25d5c740e8b85d7bba5">LIBMTP_album_struct::name</a>, and <a class="el" href="structLIBMTP__album__struct.html#a36da4ae219a7792e838642a29735bf64">LIBMTP_album_struct::tracks</a>.</p> </div> </div> <a id="gae5f27a0d3bf5885cb32722fa401b675b"></a> <h2 class="memtitle"><span class="permalink"><a href="#gae5f27a0d3bf5885cb32722fa401b675b">◆ </a></span>LIBMTP_Get_Album()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a>* LIBMTP_Get_Album </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>albid</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>This function retrieves an individual album from 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 to get the album from. </td></tr> <tr><td class="paramname">albid</td><td>the unique ID of the album to retrieve. </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>a valid album metadata or NULL on failure. </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#gaf5286f0ef2b670357415e874c0b4ddef">LIBMTP_Get_Album_List()</a> </dd></dl> <p class="reference">References <a class="el" href="structLIBMTP__mtpdevice__struct.html#aca6eb02fe46e8da41adb54e048176b42">LIBMTP_mtpdevice_struct::params</a>.</p> </div> </div> <a id="gaf5286f0ef2b670357415e874c0b4ddef"></a> <h2 class="memtitle"><span class="permalink"><a href="#gaf5286f0ef2b670357415e874c0b4ddef">◆ </a></span>LIBMTP_Get_Album_List()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a>* LIBMTP_Get_Album_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 function returns a list of the albums available on 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 to get the album listing from. </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>an album list on success, else NULL. If there are no albums on the device, NULL will be returned as well. </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#gae5f27a0d3bf5885cb32722fa401b675b">LIBMTP_Get_Album()</a> </dd></dl> <p class="reference">References <a class="el" href="group__albums.html#gaabdfcf73e4d8534fe7efd98501731098">LIBMTP_Get_Album_List_For_Storage()</a>.</p> </div> </div> <a id="gaabdfcf73e4d8534fe7efd98501731098"></a> <h2 class="memtitle"><span class="permalink"><a href="#gaabdfcf73e4d8534fe7efd98501731098">◆ </a></span>LIBMTP_Get_Album_List_For_Storage()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a>* LIBMTP_Get_Album_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_id</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>This function returns a list of the albums available on the device. You can filter on the storage ID.</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 album listing from. </td></tr> <tr><td class="paramname">storage_id</td><td>ID of device storage (if null, all storages)</td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>an album list on success, else NULL. If there are no albums on the device, NULL will be returned as well. </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#gae5f27a0d3bf5885cb32722fa401b675b">LIBMTP_Get_Album()</a> </dd></dl> <p class="reference">References <a class="el" href="structLIBMTP__mtpdevice__struct.html#aca6eb02fe46e8da41adb54e048176b42">LIBMTP_mtpdevice_struct::params</a>.</p> <p class="reference">Referenced by <a class="el" href="group__albums.html#gaf5286f0ef2b670357415e874c0b4ddef">LIBMTP_Get_Album_List()</a>.</p> </div> </div> <a id="ga5083754634934f2bfe304e66dd679d31"></a> <h2 class="memtitle"><span class="permalink"><a href="#ga5083754634934f2bfe304e66dd679d31">◆ </a></span>LIBMTP_new_album_t()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname"><a class="el" href="group__types.html#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a>* LIBMTP_new_album_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 album metadata structure and allocates memory for it. Notice that if you add strings to this structure they will be freed by the corresponding <code>LIBMTP_destroy_album_t</code> operation later, so be careful of using strdup() when assigning strings.</p> <dl class="section return"><dt>Returns</dt><dd>a pointer to the newly allocated metadata structure. </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#ga59eeda2ae84ce07f2e69134d322c6c14">LIBMTP_destroy_album_t()</a> </dd></dl> <p class="reference">References <a class="el" href="structLIBMTP__album__struct.html#a7b84dc850f5f86b78a75404842243aba">LIBMTP_album_struct::album_id</a>.</p> </div> </div> <a id="gaff1f64189550d75f737c3b8f3ff1cbb4"></a> <h2 class="memtitle"><span class="permalink"><a href="#gaff1f64189550d75f737c3b8f3ff1cbb4">◆ </a></span>LIBMTP_Set_Album_Name()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int LIBMTP_Set_Album_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#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> * </td> <td class="paramname"><em>album</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 album. This simply means that the <code>PTP_OPC_ObjectFileName</code> property is updated, if this is supported by the device. The album filename should nominally end with an extension like ".alb".</p> <p>NOTE: if you want to change the metadata the device display about a playlist you must <em>not</em> use this function, use <code><a class="el" href="group__albums.html#gaa450fa92015dc62ae770fd3792f33311">LIBMTP_Update_Album()</a></code> instead!</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">album</td><td>the album metadata of the album 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> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#gaa450fa92015dc62ae770fd3792f33311">LIBMTP_Update_Album()</a> </dd></dl> </div> </div> <a id="gaa450fa92015dc62ae770fd3792f33311"></a> <h2 class="memtitle"><span class="permalink"><a href="#gaa450fa92015dc62ae770fd3792f33311">◆ </a></span>LIBMTP_Update_Album()</h2> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">int LIBMTP_Update_Album </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#ga7ce24b2d9a5c0761cbf49b59646d0a19">LIBMTP_album_t</a> const *const </td> <td class="paramname"><em>metadata</em> </td> </tr> <tr> <td></td> <td>)</td> <td></td><td></td> </tr> </table> </div><div class="memdoc"> <p>This routine updates an album based on the metadata supplied. If the <code>tracks</code> field of the metadata contains a track listing, these tracks will be added to the album in place of those already present, i.e. the previous track listing will be deleted. </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 new album on. </td></tr> <tr><td class="paramname">metadata</td><td>the metadata for the album to be updated. notice that the field <code>album_id</code> must contain the apropriate album ID. </td></tr> </table> </dd> </dl> <dl class="section return"><dt>Returns</dt><dd>0 on success, any other value means failure. </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="group__albums.html#ga588192a48fdfc772dfe02a9c54b94109">LIBMTP_Create_New_Album()</a> </dd> <dd> <a class="el" href="group__objects.html#gac867594319fa48a0d6077d17aaf66222">LIBMTP_Delete_Object()</a> </dd></dl> </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.13 </small></address> </body> </html>