Doxygen

docs/html/index.html

@@ -85,7 +85,7 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');
 <div class="fragment"><div class="line"><span class="preprocessor">#include &lt;mrmailbox.h&gt;</span></div><div class="line"></div><div class="line">uintptr_t my_delta_handler(<a class="code" href="structmrmailbox__t.html">mrmailbox_t</a>* mailbox, <span class="keywordtype">int</span> event, uintptr_t data1, uintptr_t data2)</div><div class="line">{</div><div class="line">    <span class="keywordflow">return</span> 0; <span class="comment">// for unhandled events, it is always safe to return 0</span></div><div class="line">}</div></div><!-- fragment --><p>After that, you can create and configure a <a class="el" href="structmrmailbox__t.html" title="An object representing a single mailbox. ">mrmailbox_t</a> object easily as follows:</p>
 <div class="fragment"><div class="line"><a class="code" href="structmrmailbox__t.html">mrmailbox_t</a>* mailbox = <a class="code" href="structmrmailbox__t.html#a32825e3e0a1b16679580704a4b43db1a">mrmailbox_new</a>(my_delta_handler, NULL, NULL);</div><div class="line"></div><div class="line"><a class="code" href="structmrmailbox__t.html#a19b3e9f5209bc326fc77f3944522e8ad">mrmailbox_set_config</a>(mailbox, <span class="stringliteral">&quot;addr&quot;</span>,    <span class="stringliteral">&quot;alice@delta.chat&quot;</span>); <span class="comment">// use some real test credentials here</span></div><div class="line"><a class="code" href="structmrmailbox__t.html#a19b3e9f5209bc326fc77f3944522e8ad">mrmailbox_set_config</a>(mailbox, <span class="stringliteral">&quot;mail_pw&quot;</span>, <span class="stringliteral">&quot;***&quot;</span>);</div><div class="line"></div><div class="line"><a class="code" href="structmrmailbox__t.html#a42ca741cc08785585f1dc74d515be5ef">mrmailbox_configure_and_connect</a>(mailbox);</div></div><!-- fragment --><p><a class="el" href="structmrmailbox__t.html#a42ca741cc08785585f1dc74d515be5ef" title="Configure and connect a mailbox. ">mrmailbox_configure_and_connect()</a> may take a while and saves the result in the database. On subsequent starts, you can call <a class="el" href="structmrmailbox__t.html#a67eef5ffc3369b8ad09326471b0a266f" title="Connect to the mailbox using the configured settings. ">mrmailbox_connect()</a> instead if <a class="el" href="structmrmailbox__t.html#aa6e325e49ecccfc96276db6c327dba94" title="Check if the mailbox is already configured. ">mrmailbox_is_configured()</a> returns true.</p>
 <p>However, now you can send your first message:</p>
-<div class="fragment"><div class="line">uint32_t contact_id = <a class="code" href="structmrmailbox__t.html#aa089e97e7ca1add16c10d5cc0e902824">mrmailbox_create_contact</a>(mailbox, <span class="stringliteral">&quot;bob@delta.chat&quot;</span>); <span class="comment">// use a real testing address here</span></div><div class="line">uint32_t chat_id    = <a class="code" href="structmrmailbox__t.html#a1386ec2c091b936b65b25b50a302173d">mrmailbox_create_chat_by_contact_id</a>(mailbox, contact_id);</div><div class="line"></div><div class="line"><a class="code" href="structmrmailbox__t.html#a3f9ac5fb9ff2dcbaafdddb5d955ac39b">mrmailbox_send_text_msg</a>(mailbox, chat_id, <span class="stringliteral">&quot;Hi, here is my first message!&quot;</span>);</div></div><!-- fragment --><p>Now, go to the testing address (bob) and you should have received a normal email. Answer this email in any email program with "Got it!" and you will get the message from delta as follows:</p>
+<div class="fragment"><div class="line">uint32_t contact_id = <a class="code" href="structmrmailbox__t.html#aa089e97e7ca1add16c10d5cc0e902824">mrmailbox_create_contact</a>(mailbox, NULL, <span class="stringliteral">&quot;bob@delta.chat&quot;</span>); <span class="comment">// use a real testing address here</span></div><div class="line">uint32_t chat_id    = <a class="code" href="structmrmailbox__t.html#a1386ec2c091b936b65b25b50a302173d">mrmailbox_create_chat_by_contact_id</a>(mailbox, contact_id);</div><div class="line"></div><div class="line"><a class="code" href="structmrmailbox__t.html#a3f9ac5fb9ff2dcbaafdddb5d955ac39b">mrmailbox_send_text_msg</a>(mailbox, chat_id, <span class="stringliteral">&quot;Hi, here is my first message!&quot;</span>);</div></div><!-- fragment --><p>Now, go to the testing address (bob) and you should have received a normal email. Answer this email in any email program with "Got it!" and you will get the message from delta as follows:</p>
 <div class="fragment"><div class="line">carray* msglist = <a class="code" href="structmrmailbox__t.html#a5d3be6ed21d43cc93f250a1e7faf979b">mrmailbox_get_chat_msgs</a>(mailbox, chat_id, 0, 0);</div><div class="line"><span class="keywordflow">for</span>( <span class="keywordtype">size_t</span> i = 0; i &lt; carray_count(msglist); i++ )</div><div class="line">{</div><div class="line">    uint32_t msg_id = carray_get_uint32(msglist, i);</div><div class="line">    <a class="code" href="structmrmsg__t.html">mrmsg_t</a>* msg    = <a class="code" href="structmrmailbox__t.html#a9ef144244e7d86ba82ce3257abf14f13">mrmailbox_get_msg</a>(mailbox, msg_id);</div><div class="line"></div><div class="line">    printf(<span class="stringliteral">&quot;message %i: %s\n&quot;</span>, i+1, msg-&gt;<a class="code" href="structmrmsg__t.html#ae54dcd4036371597d7f8bbd75303527a">m_text</a>);</div><div class="line">}</div></div><!-- fragment --><p>This will output the following two lines:</p>
 <div class="fragment"><div class="line">Message 1: Hi, here is my first message!</div><div class="line">Message 2: Got it!</div></div><!-- fragment --><p>I think, you got the idea. For further reading, please dive into the <a class="el" href="structmrmailbox__t.html" title="An object representing a single mailbox. ">mrmailbox_t</a> class.</p>
 <h2>Further hints</h2>

docs/html/structmrchat__t.html

@@ -226,7 +226,9 @@ Public Attributes</h2></td></tr>
 </div><div class="memdoc">
 
 <p>Flag for the archived state. </p>
-<p>1=chat archived, 0=chat not archived.</p>
+<p>0=normal chat, not archived, not sticky.</p>
+<p>1=chat archived</p>
+<p>2=chat sticky (reserved for future use, if you do not support this value, just treat the chat as a normal one)</p>
 <p>To archive or unarchive chats, use <a class="el" href="structmrmailbox__t.html#a8e04e43dacbe3128afd71e1d6c1b0911" title="Archive or unarchive a chat. ">mrmailbox_archive_chat()</a>. If chats are archived, this should be shown in the UI by a little icon or text, eg. the search will also return archived chats. </p>
 
 </div>

docs/html/structmrmailbox__t.html

@@ -355,7 +355,8 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </div><div class="memdoc">
 
 <p>Add a number of contacts. </p>
-<p>The contacts must be added as</p>
+<p>Typically used to add the whole address book from the OS. As names here are typically not well formatted, we call <a class="el" href="structmrcontact__t.html#ad906207191f0cfd62e408dbc82a156cf" title="Normalize a name in-place. ">mrcontact_normalize_name()</a> for each name given.</p>
+<p>To add a single contact entered by the user, you should prefer <a class="el" href="structmrmailbox__t.html#aa089e97e7ca1add16c10d5cc0e902824" title="Add a single contact. ">mrmailbox_create_contact()</a></p>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">mailbox</td><td>the mailbox object as created by <a class="el" href="structmrmailbox__t.html#a32825e3e0a1b16679580704a4b43db1a" title="Create a new mailbox object. ">mrmailbox_new()</a>.</td></tr>
@@ -449,7 +450,7 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
   <table class="params">
     <tr><td class="paramname">mailbox</td><td>The mailbox object as returned from <a class="el" href="structmrmailbox__t.html#a32825e3e0a1b16679580704a4b43db1a" title="Create a new mailbox object. ">mrmailbox_new()</a>.</td></tr>
     <tr><td class="paramname">chat_id</td><td>The ID of the chat to archive or unarchive.</td></tr>
-    <tr><td class="paramname">archive</td><td>1=archive chat, 0=unarchive chat</td></tr>
+    <tr><td class="paramname">archive</td><td>1=archive chat, 0=unarchive chat, all other values are reserved for future use</td></tr>
   </table>
   </dd>
 </dl>
@@ -715,11 +716,12 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </div><div class="memdoc">
 
 <p>Add a single contact. </p>
-<p>and return the ID.</p>
+<p>We assume, the contact name, if any, is entered by the user and is used "as is" therefore, <a class="el" href="structmrcontact__t.html#ad906207191f0cfd62e408dbc82a156cf" title="Normalize a name in-place. ">mrcontact_normalize_name()</a> is <em>not</em> called for the name.</p>
+<p>To add a number of contacts, see <a class="el" href="structmrmailbox__t.html#a25720ea41355cc32cc93aa45709937d6" title="Add a number of contacts. ">mrmailbox_add_address_book()</a></p>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
     <tr><td class="paramname">mailbox</td><td>The mailbox object as created by <a class="el" href="structmrmailbox__t.html#a32825e3e0a1b16679580704a4b43db1a" title="Create a new mailbox object. ">mrmailbox_new()</a>.</td></tr>
-    <tr><td class="paramname">name</td><td>Name of the contact to add.</td></tr>
+    <tr><td class="paramname">name</td><td>Name of the contact to add. If you do not know the name belonging to the address, you can give NULL here.</td></tr>
     <tr><td class="paramname">addr</td><td>E-mail-address of the contact to add. If the email address already exists, the name is updated and the origin is increased to "manually created".</td></tr>
   </table>
   </dd>