<html>
<head>
<title>MAPIClientLibraries 0.8 API Documentation</title>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
<link href="apidocs.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="website">
<div class="header"></div>
<div id="middle_side">
<div id="right_side_home">
<!-- Generated by Doxygen 1.5.9 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</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>
<div class="contents">
<h1>fetchmail.c</h1>This example shows how to fetch mail from the server.We initialize MAPI library with the profiles database path, retrieve the default profile name and open connections to both the Exchange message store provider (EMSMDB) and Exchange Address Book provider (EMSABP).<h2><a class="anchor" name="ex-fetchmail-openstore">
Open the message store</a></h2>
Now we have opened a connection to the Exchange message store provider, we can open the user mailbox store with <a class="el" href="IMAPISession_8c.html#4fdd3c5db64deb2173a9bc921aee2dfd">OpenMsgStore()</a> This function will return a set of pre-defined folder unique IDs (stored on double values) and a <em>pointer</em> to the upper object we can access in MAPI hierarchy.<h2><a class="anchor" name="ex-fetchmail-openinbox">
Opening the Inbox folder</a></h2>
We now open the Inbox folder. Since <a class="el" href="IMAPISession_8c.html#4fdd3c5db64deb2173a9bc921aee2dfd">OpenMsgStore()</a> returns a set of <em>common</em> folders identifiers we store in the message store object (obj_store), we can retrieve them using the convenient <a class="el" href="simple__mapi_8c.html#fd821395dac16d9491e8cecd9743ff95">GetDefaultFolder()</a> function. This function doesn't generate any network traffic, but returns the folder identifier associated with the constant passed as argument (here olFolderInbox).<p>
We could have used MAPI tables and <a class="el" href="IMAPIContainer_8c.html#abf483e456de9d3621464537e9367445">GetHierarchyTable()</a> function to find Inbox folder identifier. We would have had to retrieve the Top Information Store hierarchy table, customize the view with PR_FID (Folder ID MAPI property) and PR_DISPLAY_NAME, find the IPM_SUBTREE folder identifier, open it, retrieve the Hierarchy Table, call <a class="el" href="IMAPITable_8c.html#266cd7f791acf5d9721f5e9e8ac5d49f">SetColumns()</a> with PR_FID and finally browse table rows until we found the Inbox folder.folders to store emails within IPM_SUBTREE folder hierarchy.<h2><a class="anchor" name="ex-fetchmail-retrievecontentstable">
Retrieve contents table</a></h2>
Once the Inbox folder is opened, we can call <a class="el" href="IMAPIContainer_8c.html#45f243bea0975066cc0112c57951e8a2">GetContentsTable()</a> to create the view needed to list all the children objects. In the current example we suppose we will only retrieve IPM.Post objects (emails).<h2><a class="anchor" name="ex-fetchmail-customview">
Customizing the MAPI view</a></h2>
We now customize the MAPI view and set the columns with the property tags we want to access: PR_FID (Folder Identifier) and PR_MID (Message identifier). MAPI uses unique and permanent identifiers to classify objects. These identifiers are double values (8 bytes) and never change until you move the object to another location.<p>
We now enter the last step of the fetching process:<p>
<ul>
<li>Call <a class="el" href="IMAPITable_8c.html#c40c37ca1ee53f09c1ce9639fa7eaa53">QueryPosition()</a> to retrieve the current cursor position in the contents table. The function returns the approximate fractional position with a Numerator and Denominator. Denominator is the total number of rows in the table.</li><li>Recursively call <a class="el" href="IMAPITable_8c.html#e5890f112bb41a03f6ecbe90a16687c4">QueryRows()</a> with the TBL_ADVANCE flag to fetch table rows.</li><li>Iterate through QueryRows results</li><li>Retrieve columns values for each row with the convenient find_SPropValue_data()</li><li>Open the message given its folder and message ids.</li><li>Call <a class="el" href="IMAPIProp_8c.html#e216a092d1517c67db706536631404ff">GetPropsAll()</a> rather than <a class="el" href="IMAPIProp_8c.html#d71fddaae9ab98871ffe4fec3938a704">GetProps()</a> to retrieve all properties associated with a given object</li><li>Call one of OpenChange mapidump API function to display nice messages dump on standard output.</li></ul>
<p>
We finally release mapi objects and clean up the MAPI library before returning<p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <libmapi/libmapi.h></span>
<span class="preprocessor">#define DEFAULT_PROFDB "%s/.openchange/profiles.ldb"</span>
<span class="preprocessor"></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> *argv[])
{
<span class="keyword">enum</span> MAPISTATUS retval;
TALLOC_CTX *mem_ctx;
<span class="keyword">struct </span>mapi_session *session = NULL;
mapi_object_t obj_store;
mapi_object_t obj_folder;
mapi_object_t obj_table;
mapi_object_t obj_message;
<span class="keyword">struct </span>mapi_SPropValue_array props_all;
<span class="keyword">struct </span>SRowSet rowset;
<span class="keyword">struct </span>SPropTagArray *SPropTagArray;
mapi_id_t id_inbox;
mapi_id_t *fid, *mid;
<span class="keywordtype">char</span> *profname;
<span class="keywordtype">char</span> *profdb;
uint32_t Numerator;
uint32_t Denominator;
uint32_t i;
mem_ctx = talloc_named(NULL, 0, <span class="stringliteral">"fetchmail"</span>);
<span class="comment">/* Initialize MAPI */</span>
profdb = talloc_asprintf(mem_ctx, DEFAULT_PROFDB, getenv(<span class="stringliteral">"HOME"</span>));
retval = <a name="a0"></a><a class="code" href="cdo__mapi_8c.html#cd55ca55043b2a1c025c370725f1292a">MAPIInitialize</a>(profdb);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Find Default Profile */</span>
retval = <a name="a1"></a><a class="code" href="IProfAdmin_8c.html#3e503caa812de7ec2d53f03f53ee4ca1">GetDefaultProfile</a>(&profname);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Log on EMSMDB and NSPI */</span>
retval = <a name="a2"></a><a class="code" href="cdo__mapi_8c.html#2a42a622654ad8f1020d152028efe67b">MapiLogonEx</a>(&session, profname, NULL);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Open Message Store */</span>
<a name="a3"></a><a class="code" href="mapi__object_8c.html#f49c3130b8cb47f741ff652fc53c1364">mapi_object_init</a>(&obj_store);
retval = <a name="a4"></a><a class="code" href="IMAPISession_8c.html#4fdd3c5db64deb2173a9bc921aee2dfd">OpenMsgStore</a>(session, &obj_store);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Find Inbox default folder */</span>
retval = <a name="a5"></a><a class="code" href="simple__mapi_8c.html#fd821395dac16d9491e8cecd9743ff95">GetDefaultFolder</a>(&obj_store, &id_inbox, olFolderInbox);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Open Inbox folder */</span>
<a class="code" href="mapi__object_8c.html#f49c3130b8cb47f741ff652fc53c1364">mapi_object_init</a>(&obj_folder);
retval = <a name="a6"></a><a class="code" href="IMsgStore_8c.html#8b90a95da815aaed2c2728c2599007c1">OpenFolder</a>(&obj_store, id_inbox, &obj_folder);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Retrieve Inbox content table */</span>
<a class="code" href="mapi__object_8c.html#f49c3130b8cb47f741ff652fc53c1364">mapi_object_init</a>(&obj_table);
retval = <a name="a7"></a><a class="code" href="IMAPIContainer_8c.html#45f243bea0975066cc0112c57951e8a2">GetContentsTable</a>(&obj_folder, &obj_table, 0x0, NULL);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Create the MAPI table view */</span>
SPropTagArray = set_SPropTagArray(mem_ctx, 0x2, PR_FID, PR_MID);
retval = <a name="a8"></a><a class="code" href="IMAPITable_8c.html#266cd7f791acf5d9721f5e9e8ac5d49f">SetColumns</a>(&obj_table, SPropTagArray);
<a name="a9"></a><a class="code" href="IUnknown_8c.html#52246b3bbc755db550d9d13e772dd479">MAPIFreeBuffer</a>(SPropTagArray);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
talloc_free(mem_ctx);
<span class="comment">/* Get current cursor position */</span>
retval = <a name="a10"></a><a class="code" href="IMAPITable_8c.html#c40c37ca1ee53f09c1ce9639fa7eaa53">QueryPosition</a>(&obj_table, &Numerator, &Denominator);
MAPI_RETVAL_IF(retval, retval, mem_ctx);
<span class="comment">/* Iterate through rows */</span>
<span class="keywordflow">while</span> ((retval = <a name="a11"></a><a class="code" href="IMAPITable_8c.html#e5890f112bb41a03f6ecbe90a16687c4">QueryRows</a>(&obj_table, Denominator, TBL_ADVANCE, &rowset))
!= -1 && rowset.cRows) {
<span class="keywordflow">for</span> (i = 0; i < rowset.cRows; i++) {
fid = (mapi_id_t *)find_SPropValue_data(&(rowset.aRow[i]), PR_FID);
mid = (mapi_id_t *)find_SPropValue_data(&(rowset.aRow[i]), PR_MID);
<a class="code" href="mapi__object_8c.html#f49c3130b8cb47f741ff652fc53c1364">mapi_object_init</a>(&obj_message);
retval = <a name="a12"></a><a class="code" href="IStoreFolder_8c.html#7b8869cb8d75ee0820b89bda12bea92c">OpenMessage</a>(&obj_store, *fid, *mid, &obj_message, 0x0);
<span class="keywordflow">if</span> (retval != MAPI_E_NOT_FOUND) {
retval = <a name="a13"></a><a class="code" href="IMAPIProp_8c.html#e216a092d1517c67db706536631404ff">GetPropsAll</a>(&obj_message, &props_all);
<a name="a14"></a><a class="code" href="mapidump_8c.html#9be627dc83377ae3bba27e6fa6367e16">mapidump_message</a>(&props_all, NULL);
<a name="a15"></a><a class="code" href="mapi__object_8c.html#de2b4701fae8a110c476b894834831b9">mapi_object_release</a>(&obj_message);
}
}
}
<span class="comment">/* Release MAPI objects */</span>
<a class="code" href="mapi__object_8c.html#de2b4701fae8a110c476b894834831b9">mapi_object_release</a>(&obj_table);
<a class="code" href="mapi__object_8c.html#de2b4701fae8a110c476b894834831b9">mapi_object_release</a>(&obj_folder);
<a name="a16"></a><a class="code" href="IMSProvider_8c.html#9cd81eb7c3d90eda00c82f2d48915c2f">Logoff</a>(&obj_store);
<span class="comment">/* Uninitialize MAPI */</span>
<a name="a17"></a><a class="code" href="cdo__mapi_8c.html#b8230cc080e782e318a090786c3253de">MAPIUninitialize</a>();
<span class="keywordflow">return</span> (0);
}
</pre></div> </div>
</div>
<br/>
<table style="clear:both; margin: 0.5em auto; width:80%; text-align: center; background-color:#f8f8f8; border:2px solid #e0e0e0; padding:5px;">
<tr>
<td>
<img alt="Creative Commons License" src="CC_SomeRightsReserved.png" width="90" height="30" border="0" /><br />
<img alt="Creative Commons Attribution icon" src="24px-Cc-by_white.svg.png" width="24" height="24" border="0" />
<img alt="Creative Commons Share Alike icon" src="24px-Cc-sa_white.svg.png" width="24" height="24" border="0" />
</td>
<td> <i><strong class="selflink">This content</strong> is licensed under the Creative Commons<br />
Attribution ShareAlike License v. 3.0:<br />
<a href="http://creativecommons.org/licenses/by-sa/3.0/" class="external free" title="http://creativecommons.org/licenses/by-sa/3.0/" rel="nofollow">http://creativecommons.org/licenses/by-sa/3.0/</a></i>
</td></tr></table>
<br/>
</div>
</div>
</body>
</html>
