Doxygen

docs/html/index.html

@@ -82,10 +82,11 @@ var searchBox = new SearchBox("searchBox", "search",false,'Search');
 <div class="textblock"><p>This document describes how to handle the Delta Chat core library.For general information about Delta Chat itself, see <a href="https://delta.chat">https://delta.chat</a> and <a href="https://github.com/deltachat">https://github.com/deltachat</a>.</p>
 <p>Let's start.</p>
 <p>First of all, you have to define a function that is called by the library on specific events (eg. when the configuration is done or when fresh messages arrive). Your function should look like the following:</p>
-<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>* nb, <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"><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>* mb = <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>(mb, <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>(mb, <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>(mb);</div></div><!-- fragment --><p>After that, you can send your first message:</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>
-<div class="fragment"><div class="line">uint32_t contact_id = <a class="code" href="structmrmailbox__t.html#aa089e97e7ca1add16c10d5cc0e902824">mrmailbox_create_contact</a>(mb, <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>(mb, contact_id);</div><div class="line"></div><div class="line"><a class="code" href="structmrmailbox__t.html#a3f9ac5fb9ff2dcbaafdddb5d955ac39b">mrmailbox_send_text_msg</a>(mb, 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>
+<p>However, now you can send your first message:</p>
-<div class="fragment"><div class="line">carray* msglist = <a class="code" href="structmrmailbox__t.html#a5d3be6ed21d43cc93f250a1e7faf979b">mrmailbox_get_chat_msgs</a>(mb, 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>(mb, 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">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">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>
 <p>Here are some additional, unsorted hints that may be useful. If you need any further assistance, please do not hesitate to contact us at <a href="#" onclick="location.href='mai'+'lto:'+'r10'+'s@'+'b44'+'t.'+'com'; return false;">r10s@<span style="display: none;">.nosp@m.</span>b44t<span style="display: none;">.nosp@m.</span>.com</a>.</p>

docs/html/structmrchat__t.html

@@ -141,7 +141,7 @@ char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </table>
 <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
 <div class="textblock"><p>An object representing a single chat in memory. </p>
-<p>Chat objects are created using eg. <a class="el" href="structmrmailbox__t.html#ad106b9c23b3a559b524a37bb5504e096" title="Get a chat object of type mrchat_t by a chat_id. ">mrmailbox_get_chat()</a> and are not updated on database changes; if you want an update, you have to recreate the object. </p>
+<p>Chat objects are created using eg. <a class="el" href="structmrmailbox__t.html#ad106b9c23b3a559b524a37bb5504e096" title="Get chat object by a chat ID. ">mrmailbox_get_chat()</a> and are not updated on database changes; if you want an update, you have to recreate the object. </p>
 </div><h2 class="groupheader">Member Function Documentation</h2>
 <a class="anchor" id="ae5c507c3944e38afe7584d59d9ece3cc"></a>
 <div class="memitem">
@@ -211,7 +211,7 @@ char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 <p>Free a chat object. </p>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
-    <tr><td class="paramname">chat</td><td>Chat object are returned eg. by <a class="el" href="structmrmailbox__t.html#ad106b9c23b3a559b524a37bb5504e096" title="Get a chat object of type mrchat_t by a chat_id. ">mrmailbox_get_chat()</a> or mrchat_new().</td></tr>
+    <tr><td class="paramname">chat</td><td>Chat object are returned eg. by <a class="el" href="structmrmailbox__t.html#ad106b9c23b3a559b524a37bb5504e096" title="Get chat object by a chat ID. ">mrmailbox_get_chat()</a> or mrchat_new().</td></tr>
   </table>
   </dd>
 </dl>

docs/html/structmrcontact__t.html

@@ -121,16 +121,14 @@ Public Attributes</h2></td></tr>
 <tr class="memitem:ab2ee31297c327e04ed14673adbd49716"><td class="memItemLeft" align="right" valign="top">uint32_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrcontact__t.html#ab2ee31297c327e04ed14673adbd49716">m_id</a></td></tr>
 <tr class="memdesc:ab2ee31297c327e04ed14673adbd49716"><td class="mdescLeft">&#160;</td><td class="mdescRight">The contact ID.  <a href="#ab2ee31297c327e04ed14673adbd49716">More...</a><br /></td></tr>
 <tr class="separator:ab2ee31297c327e04ed14673adbd49716"><td class="memSeparator" colspan="2">&#160;</td></tr>
-<tr class="memitem:a48fba862b41f7da3b8c6193c0554654b"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="a48fba862b41f7da3b8c6193c0554654b"></a>
+<tr class="memitem:a48fba862b41f7da3b8c6193c0554654b"><td class="memItemLeft" align="right" valign="top">char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrcontact__t.html#a48fba862b41f7da3b8c6193c0554654b">m_name</a></td></tr>
-char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrcontact__t.html#a48fba862b41f7da3b8c6193c0554654b">m_name</a></td></tr>
+<tr class="memdesc:a48fba862b41f7da3b8c6193c0554654b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Name given by the user to the contact.  <a href="#a48fba862b41f7da3b8c6193c0554654b">More...</a><br /></td></tr>
-<tr class="memdesc:a48fba862b41f7da3b8c6193c0554654b"><td class="mdescLeft">&#160;</td><td class="mdescRight">may be NULL or empty, this name should not be spreaded as it may be "Daddy" and so on; initially set to m_authname <br /></td></tr>
 <tr class="separator:a48fba862b41f7da3b8c6193c0554654b"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a559c848feee29d334098f9a581448e56"><td class="memItemLeft" align="right" valign="top">char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrcontact__t.html#a559c848feee29d334098f9a581448e56">m_authname</a></td></tr>
-<tr class="memdesc:a559c848feee29d334098f9a581448e56"><td class="mdescLeft">&#160;</td><td class="mdescRight">may be NULL or empty, this is the name authorized by the sender, only this name may be speaded to others, eg.  <a href="#a559c848feee29d334098f9a581448e56">More...</a><br /></td></tr>
+<tr class="memdesc:a559c848feee29d334098f9a581448e56"><td class="mdescLeft">&#160;</td><td class="mdescRight">Name authorized by the contact himself.  <a href="#a559c848feee29d334098f9a581448e56">More...</a><br /></td></tr>
 <tr class="separator:a559c848feee29d334098f9a581448e56"><td class="memSeparator" colspan="2">&#160;</td></tr>
-<tr class="memitem:aaedd60ba4cad97bb87ba5a55958341e5"><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="aaedd60ba4cad97bb87ba5a55958341e5"></a>
+<tr class="memitem:aaedd60ba4cad97bb87ba5a55958341e5"><td class="memItemLeft" align="right" valign="top">char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrcontact__t.html#aaedd60ba4cad97bb87ba5a55958341e5">m_addr</a></td></tr>
-char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrcontact__t.html#aaedd60ba4cad97bb87ba5a55958341e5">m_addr</a></td></tr>
+<tr class="memdesc:aaedd60ba4cad97bb87ba5a55958341e5"><td class="mdescLeft">&#160;</td><td class="mdescRight">The E-Mail-Address of the contact.  <a href="#aaedd60ba4cad97bb87ba5a55958341e5">More...</a><br /></td></tr>
-<tr class="memdesc:aaedd60ba4cad97bb87ba5a55958341e5"><td class="mdescLeft">&#160;</td><td class="mdescRight">may be NULL or empty <br /></td></tr>
 <tr class="separator:aaedd60ba4cad97bb87ba5a55958341e5"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:ac22d500e5c439b07c943ed2c7afb2a23"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrcontact__t.html#ac22d500e5c439b07c943ed2c7afb2a23">m_blocked</a></td></tr>
 <tr class="memdesc:ac22d500e5c439b07c943ed2c7afb2a23"><td class="mdescLeft">&#160;</td><td class="mdescRight">Blocked state.  <a href="#ac22d500e5c439b07c943ed2c7afb2a23">More...</a><br /></td></tr>
@@ -197,6 +195,21 @@ char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </div>
 </div>
 <h2 class="groupheader">Member Data Documentation</h2>
+<a class="anchor" id="aaedd60ba4cad97bb87ba5a55958341e5"></a>
+<div class="memitem">
+<div class="memproto">
+      <table class="memname">
+        <tr>
+          <td class="memname">char* mrcontact_t::m_addr</td>
+        </tr>
+      </table>
+</div><div class="memdoc">
+
+<p>The E-Mail-Address of the contact. </p>
+<p>May be NULL or empty. </p>
+
+</div>
+</div>
 <a class="anchor" id="a559c848feee29d334098f9a581448e56"></a>
 <div class="memitem">
 <div class="memproto">
@@ -207,8 +220,8 @@ char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
       </table>
 </div><div class="memdoc">
 
-<p>may be NULL or empty, this is the name authorized by the sender, only this name may be speaded to others, eg. </p>
+<p>Name authorized by the contact himself. </p>
-<p>in To:-lists; for displaying in the app, use m_name </p>
+<p>May be NULL or empty, this is the name authorized by the sender, only this name may be speaded to others, eg. in To:-lists; for displaying in the app, use <a class="el" href="structmrcontact__t.html#a48fba862b41f7da3b8c6193c0554654b" title="Name given by the user to the contact. ">m_name</a> </p>
 
 </div>
 </div>
@@ -223,7 +236,7 @@ char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </div><div class="memdoc">
 
 <p>Blocked state. </p>
-<p>1=contact is blocked, 0=contact is not blocked. </p>
+<p>1=contact is blocked, 0=contact is not blocked. To block or unblock a contact, use <a class="el" href="structmrmailbox__t.html#abb069358386b767a60444651195e0895" title="Block or unblock a contact. ">mrmailbox_block_contact()</a>. </p>
 
 </div>
 </div>
@@ -243,6 +256,22 @@ char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </ul>
 <p>Normal contact IDs are larger than these special ones (larger than MR_CONTACT_ID_LAST_SPECIAL). </p>
 
+</div>
+</div>
+<a class="anchor" id="a48fba862b41f7da3b8c6193c0554654b"></a>
+<div class="memitem">
+<div class="memproto">
+      <table class="memname">
+        <tr>
+          <td class="memname">char* mrcontact_t::m_name</td>
+        </tr>
+      </table>
+</div><div class="memdoc">
+
+<p>Name given by the user to the contact. </p>
+<p>Should be used for displaying everywhere and is editable by the user but must not be spreaded via mail (To:, CC: ...) as it as it may be sth. like "Daddy".</p>
+<p>May be NULL or empty, initially set to <a class="el" href="structmrcontact__t.html#a559c848feee29d334098f9a581448e56" title="Name authorized by the contact himself. ">m_authname</a> </p>
+
 </div>
 </div>
 <hr/>The documentation for this struct was generated from the following files:<ul>

docs/html/structmrmailbox__t.html

@@ -150,7 +150,7 @@ Public Member Functions</h2></td></tr>
 <tr class="memdesc:a4da10c87eb65bbf6c504979d75ec3b19"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get a list of chats.  <a href="#a4da10c87eb65bbf6c504979d75ec3b19">More...</a><br /></td></tr>
 <tr class="separator:a4da10c87eb65bbf6c504979d75ec3b19"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:ad106b9c23b3a559b524a37bb5504e096"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structmrchat__t.html">mrchat_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrmailbox__t.html#ad106b9c23b3a559b524a37bb5504e096">mrmailbox_get_chat</a> (<a class="el" href="structmrmailbox__t.html">mrmailbox_t</a> *mailbox, uint32_t chat_id)</td></tr>
-<tr class="memdesc:ad106b9c23b3a559b524a37bb5504e096"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get a chat object of type <a class="el" href="structmrchat__t.html" title="An object representing a single chat in memory. ">mrchat_t</a> by a chat_id.  <a href="#ad106b9c23b3a559b524a37bb5504e096">More...</a><br /></td></tr>
+<tr class="memdesc:ad106b9c23b3a559b524a37bb5504e096"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get chat object by a chat ID.  <a href="#ad106b9c23b3a559b524a37bb5504e096">More...</a><br /></td></tr>
 <tr class="separator:ad106b9c23b3a559b524a37bb5504e096"><td class="memSeparator" colspan="2">&#160;</td></tr>
 <tr class="memitem:a07cc8fe0cfd900a9449bffc4ca5a7a95"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structmrmailbox__t.html#a07cc8fe0cfd900a9449bffc4ca5a7a95">mrmailbox_marknoticed_chat</a> (<a class="el" href="structmrmailbox__t.html">mrmailbox_t</a> *mailbox, uint32_t chat_id)</td></tr>
 <tr class="memdesc:a07cc8fe0cfd900a9449bffc4ca5a7a95"><td class="mdescLeft">&#160;</td><td class="mdescRight">Mark all message in a chat as <em>noticed</em>.  <a href="#a07cc8fe0cfd900a9449bffc4ca5a7a95">More...</a><br /></td></tr>
@@ -581,7 +581,6 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 <li>Before your call this function, you should set at least <code>addr</code> and <code>mail_pw</code> using <a class="el" href="structmrmailbox__t.html#a19b3e9f5209bc326fc77f3944522e8ad" title="Configure the mailbox. ">mrmailbox_set_config()</a>.</li>
 <li><a class="el" href="structmrmailbox__t.html#a42ca741cc08785585f1dc74d515be5ef" title="Configure and connect a mailbox. ">mrmailbox_configure_and_connect()</a> may take a while, so it might be a good idea to let it run in a non-GUI-thread; to cancel the configuration progress, you can then use <a class="el" href="structmrmailbox__t.html#a8127c0e3f4cfda14fdfd7be9f43715ef" title="Signal the configure-process to stop. ">mrmailbox_configure_cancel()</a>.</li>
 <li>The function sends out a number of <a class="el" href="mrevent_8h.html#abb0881d4c7c887b8f371cedc471846b5" title="Inform about the configuration progress started by mrmailbox_configure_and_connect(). ">MR_EVENT_CONFIGURE_PROGRESS</a> events that may be used to create a progress bar or stuff like that.</li>
-<li>There is no need to call this every program start, the result is saved in the database.</li>
 </ul>
 <dl class="params"><dt>Parameters</dt><dd>
   <table class="params">
@@ -589,8 +588,9 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
   </table>
   </dd>
 </dl>
-<dl class="section return"><dt>Returns</dt><dd>1=configured and connected, 0=not configured, not explicitly connected, however, an existing connection may still be present </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>1=configured and connected, 0=not configured, not explicitly connected, however, an existing connection may still be present</dd></dl>
-
+<p>There is no need to call this every program start, the result is saved in the database. Instead, you can use <a class="el" href="structmrmailbox__t.html#a67eef5ffc3369b8ad09326471b0a266f" title="Connect to the mailbox using the configured settings. ">mrmailbox_connect()</a> which reuses the configuration and is much faster:</p>
+<div class="fragment"><div class="line"><span class="keywordflow">if</span>( <a class="code" href="structmrmailbox__t.html#aa6e325e49ecccfc96276db6c327dba94">mrmailbox_is_configured</a>(mailbox) ) {</div><div class="line">    <a class="code" href="structmrmailbox__t.html#a67eef5ffc3369b8ad09326471b0a266f">mrmailbox_connect</a>(mailbox); <span class="comment">// fast, reuse the configuration</span></div><div class="line">}</div><div class="line"><span class="keywordflow">else</span> {</div><div class="line">    <a class="code" href="structmrmailbox__t.html#a42ca741cc08785585f1dc74d515be5ef">mrmailbox_configure_and_connect</a>(mailbox); <span class="comment">// may take a while, typically started in a thread</span></div><div class="line">}</div></div><!-- fragment --> 
 </div>
 </div>
 <a class="anchor" id="a8127c0e3f4cfda14fdfd7be9f43715ef"></a>
@@ -1066,8 +1066,7 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
       </table>
 </div><div class="memdoc">
 
-<p>Get a chat object of type <a class="el" href="structmrchat__t.html" title="An object representing a single chat in memory. ">mrchat_t</a> by a chat_id. </p>
+<p>Get chat object by a chat ID. </p>
-<p>To access the <a class="el" href="structmrchat__t.html" title="An object representing a single chat in memory. ">mrchat_t</a> object, see <a class="el" href="mrchat_8h_source.html">mrchat.h</a> The result must be unref'd using <a class="el" href="structmrchat__t.html#a3b1befb4542c1bad915f2175c7c2a2b9" title="Free a chat object. ">mrchat_unref()</a>.</p>
 <dl class="params"><dt>Parameters</dt><dd>
   <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>
@@ -1075,7 +1074,7 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
   </table>
   </dd>
 </dl>
-<dl class="section return"><dt>Returns</dt><dd>A chat object, must be freed using <a class="el" href="structmrchat__t.html#a3b1befb4542c1bad915f2175c7c2a2b9" title="Free a chat object. ">mrchat_unref()</a> when done. </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>A chat object of the type <a class="el" href="structmrchat__t.html" title="An object representing a single chat in memory. ">mrchat_t</a>, must be freed using <a class="el" href="structmrchat__t.html#a3b1befb4542c1bad915f2175c7c2a2b9" title="Free a chat object. ">mrchat_unref()</a> when done. </dd></dl>
 
 </div>
 </div>
@@ -1878,14 +1877,14 @@ void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </div><div class="memdoc">
 
 <p>Check if the mailbox is already configured. </p>
-<p>Typically, for unconfigured mailboxes, the user is prompeted for to enter some settings and <a class="el" href="structmrmailbox__t.html#a42ca741cc08785585f1dc74d515be5ef" title="Configure and connect a mailbox. ">mrmailbox_configure_and_connect()</a> is called with them.</p>
+<p>Typically, for unconfigured mailboxes, the user is prompeted for to enter some settings and <a class="el" href="structmrmailbox__t.html#a42ca741cc08785585f1dc74d515be5ef" title="Configure and connect a mailbox. ">mrmailbox_configure_and_connect()</a> is called in a thread then.</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">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>
   </table>
   </dd>
 </dl>
-<dl class="section return"><dt>Returns</dt><dd>None </dd></dl>
+<dl class="section return"><dt>Returns</dt><dd>1=mailbox is configured and <a class="el" href="structmrmailbox__t.html#a67eef5ffc3369b8ad09326471b0a266f" title="Connect to the mailbox using the configured settings. ">mrmailbox_connect()</a> can be called directly as needed, 0=mailbox is not configured and a configuration by <a class="el" href="structmrmailbox__t.html#a42ca741cc08785585f1dc74d515be5ef" title="Configure and connect a mailbox. ">mrmailbox_configure_and_connect()</a> is required. </dd></dl>
 
 </div>
 </div>

docs/html/structmrmsg__t.html

@@ -396,7 +396,7 @@ char *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="st
 </div><div class="memdoc">
 
 <p>Chat ID the message belongs to. </p>
-<p>0 if unset. See <a class="el" href="structmrchat__t.html#a1591431716413350eaffce0b588e4911" title="Chat ID under which the chat is filed in the database. ">mrchat_t::m_id</a> for special IDs. Use <a class="el" href="structmrmailbox__t.html#ad106b9c23b3a559b524a37bb5504e096" title="Get a chat object of type mrchat_t by a chat_id. ">mrmailbox_get_chat()</a> to load details about the chat. </p>
+<p>0 if unset. See <a class="el" href="structmrchat__t.html#a1591431716413350eaffce0b588e4911" title="Chat ID under which the chat is filed in the database. ">mrchat_t::m_id</a> for special IDs. Use <a class="el" href="structmrmailbox__t.html#ad106b9c23b3a559b524a37bb5504e096" title="Get chat object by a chat ID. ">mrmailbox_get_chat()</a> to load details about the chat. </p>
 
 </div>
 </div>