| 1 | <?xml version="1.0"?> |
| 2 | <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>rfc822</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.72.0"/><link rel="start" href="#rfc822" title="rfc822"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!-- |
| 3 | |
| 4 | Copyright 1998 - 2007 Double Precision, Inc. See COPYING for distribution |
| 5 | information. |
| 6 | |
| 7 | --></head><body><div class="refentry" lang="en" xml:lang="en"><a id="rfc822" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>rfc822 — RFC 822 parsing library</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 8 | #include <rfc822.h> |
| 9 | |
| 10 | #include <rfc2047.h> |
| 11 | |
| 12 | cc ... -lrfc822 |
| 13 | </pre></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id281685" shape="rect"> </a><h2>DESCRIPTION</h2><p> |
| 14 | The rfc822 library provides functions for parsing E-mail headers in the RFC |
| 15 | 822 format. This library also includes some functions to help with encoding |
| 16 | and decoding 8-bit text, as defined by RFC 2047.</p><p> |
| 17 | The format used by E-mail headers to encode sender and recipient |
| 18 | information is defined by |
| 19 | <a href="http://www.rfc-editor.org/rfc/rfc822.txt" target="_top" shape="rect">RFC 822</a> |
| 20 | (and its successor, |
| 21 | <a href="http://www.rfc-editor.org/rfc/rfc2822.txt" target="_top" shape="rect">RFC 2822</a>). |
| 22 | The format allows the actual E-mail |
| 23 | address and the sender/recipient name to be expressed together, for example: |
| 24 | <code class="literal">John Smith <jsmith@example.com></code></p><p> |
| 25 | The main purposes of the rfc822 library is to:</p><p> |
| 26 | 1) Parse a text string containing a list of RFC 822-formatted address into |
| 27 | its logical components: names and E-mail addresses.</p><p> |
| 28 | 2) Access those individual components.</p><p> |
| 29 | 3) Allow some limited modifications of the parsed structure, and then |
| 30 | convert it back into a text string.</p><div class="refsect2" lang="en" xml:lang="en"><a id="id282329" shape="rect"> </a><h3>Tokenizing an E-mail header</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 31 | struct rfc822t *tokens=rfc822t_alloc_new(const char *header, |
| 32 | void (*err_func)(const char *, int, void *), |
| 33 | void *func_arg); |
| 34 | |
| 35 | void rfc822t_free(tokens); |
| 36 | </pre></div><p> |
| 37 | The <code class="function">rfc822t_alloc_new</code>() function (superceeds |
| 38 | <code class="function">rfc822t_alloc</code>(), which is now |
| 39 | obsolete) accepts an E-mail <em class="parameter"><code>header</code></em>, and parses it into |
| 40 | individual tokens. This function allocates and returns a pointer to an |
| 41 | <span class="structname">rfc822t</span> |
| 42 | structure, which is later used by |
| 43 | <code class="function">rfc822a_alloc</code>() to extract |
| 44 | individual addresses from these tokens.</p><p> |
| 45 | If <em class="parameter"><code>err_func</code></em> argument, if not NULL, is a pointer |
| 46 | to a callback |
| 47 | function. The function is called in the event that the E-mail header is |
| 48 | corrupted to the point that it cannot even be parsed. This is a rare instance |
| 49 | -- most forms of corruption are still valid at least on the lexical level. |
| 50 | The only time this error is reported is in the event of mismatched |
| 51 | parenthesis, angle brackets, or quotes. The callback function receives the |
| 52 | <em class="parameter"><code>header</code></em> pointer, an index to the syntax error in the |
| 53 | header string, and the <em class="parameter"><code>func_arg</code></em> argument.</p><p> |
| 54 | The semantics of <em class="parameter"><code>err_func</code></em> are subject to change. It is recommended |
| 55 | to leave this argument as NULL in the current version of the library.</p><p> |
| 56 | <code class="function">rfc822t_alloc</code>() returns a pointer to a |
| 57 | dynamically-allocated <span class="structname">rfc822t</span> |
| 58 | structure. A NULL pointer is returned if there's insufficient memory to |
| 59 | allocate this structure. The <code class="function">rfc822t_free</code>() function |
| 60 | destroys |
| 61 | <span class="structname">rfc822t</span> structure and frees all |
| 62 | dynamically allocated memory.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> |
| 63 | Until <code class="function">rfc822t_free</code>() is called, the contents of |
| 64 | <em class="parameter"><code>header</code></em> MUST |
| 65 | NOT be destroyed or altered in any way. The contents of |
| 66 | <em class="parameter"><code>header</code></em> are not |
| 67 | modified by <code class="function">rfc822t_alloc</code>(), however the |
| 68 | <span class="structname">rfc822t</span> structure contains |
| 69 | pointers to portions of the supplied <em class="parameter"><code>header</code></em>, |
| 70 | and they must remain valid.</p></div></div><div class="refsect2" lang="en" xml:lang="en"><a id="id282672" shape="rect"> </a><h3>Extracting E-mail addresses</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 71 | struct rfc822a *addrs=rfc822a_alloc(struct rfc822t *tokens); |
| 72 | |
| 73 | void rfc822a_free(addrs); |
| 74 | </pre></div><p> |
| 75 | The <code class="function">rfc822a_alloc</code>() function returns a |
| 76 | dynamically-allocated <span class="structname">rfc822a</span> |
| 77 | structure, that contains individual addresses that were logically parsed |
| 78 | from a <span class="structname">rfc822t</span> structure. The |
| 79 | <code class="function">rfc822a_alloc</code>() function returns NULL if |
| 80 | there was insufficient memory to allocate the <span class="structname">rfc822a</span> structure. The |
| 81 | <code class="function">rfc822a_free</code>() function destroys the <span class="structname">rfc822a</span> function, and frees all |
| 82 | associated dynamically-allocated memory. The <span class="structname">rfc822t</span> structure passed |
| 83 | to <code class="function">rfc822a_alloc</code>() must not be destroyed before <code class="function">rfc822a_free</code>() destroys the |
| 84 | <span class="structname">rfc822a</span> structure.</p><p> |
| 85 | The <span class="structname">rfc822a</span> structure has the following fields:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 86 | struct rfc822a { |
| 87 | struct rfc822addr *addrs; |
| 88 | int naddrs; |
| 89 | } ; |
| 90 | </pre></div><p> |
| 91 | The <em class="structfield"><code>naddrs</code></em> field gives the number of |
| 92 | <span class="structname">rfc822addr</span> structures |
| 93 | that are pointed to by <em class="structfield"><code>addrs</code></em>, which is an array. |
| 94 | Each <span class="structname">rfc822addr</span> |
| 95 | structure represents either an address found in the original E-mail header, |
| 96 | <span class="emphasis"><em>or the contents of some legacy "syntactical sugar"</em></span>. |
| 97 | For example, the |
| 98 | following is a valid E-mail header:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 99 | To: recipient-list: tom@example.com, john@example.com; |
| 100 | </pre></div><p>Typically, all of this, except for "<code class="literal">To:</code>", |
| 101 | is tokenized by <code class="function">rfc822t_alloc</code>(), then parsed by |
| 102 | <code class="function">rfc822a_alloc</code>(). |
| 103 | "<code class="literal">recipient-list:</code>" and |
| 104 | the trailing semicolon is a legacy mailing list specification that is no |
| 105 | longer in widespread use, but must still must be accounted for. The resulting |
| 106 | <span class="structname">rfc822a</span> structure will have four |
| 107 | <span class="structname">rfc822addr</span> structures: one for |
| 108 | "<code class="literal">recipient-list:</code>"; |
| 109 | one for each address; and one for the trailing semicolon. |
| 110 | Each <span class="structname">rfc822a</span> structure has the following |
| 111 | fields:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 112 | struct rfc822addr { |
| 113 | struct rfc822token *tokens; |
| 114 | struct rfc822token *name; |
| 115 | } ; |
| 116 | </pre></div><p> |
| 117 | If <em class="structfield"><code>tokens</code></em> is a null pointer, this structure |
| 118 | represents some |
| 119 | non-address portion of the original header, such as |
| 120 | "<code class="literal">recipient-list:</code>" or a |
| 121 | semicolon. Otherwise it points to a structure that represents the E-mail |
| 122 | address in tokenized form.</p><p> |
| 123 | <em class="structfield"><code>name</code></em> either points to the tokenized form of a |
| 124 | non-address portion of |
| 125 | the original header, or to a tokenized form of the recipient's name. |
| 126 | <em class="structfield"><code>name</code></em> will be NULL if the recipient name was not provided. For the |
| 127 | following address: |
| 128 | <code class="literal">Tom Jones <tjones@example.com></code> - the |
| 129 | <em class="structfield"><code>tokens</code></em> field points to the tokenized form of |
| 130 | "<code class="literal">tjones@example.com</code>", |
| 131 | and <em class="structfield"><code>name</code></em> points to the tokenized form of |
| 132 | "<code class="literal">Tom Jones</code>".</p><p> |
| 133 | Each <span class="structname">rfc822token</span> structure contains the following |
| 134 | fields:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 135 | struct rfc822token { |
| 136 | struct rfc822token *next; |
| 137 | int token; |
| 138 | const char *ptr; |
| 139 | int len; |
| 140 | } ; |
| 141 | </pre></div><p> |
| 142 | The <em class="structfield"><code>next</code></em> pointer builds a linked list of all |
| 143 | tokens in this name or |
| 144 | address. The possible values for the <em class="structfield"><code>token</code></em> field |
| 145 | are:</p><div class="variablelist"><dl><dt><span class="term">0x00</span></dt><dd><p> |
| 146 | This is a simple atom - a sequence of non-special characters that |
| 147 | is delimited by whitespace or special characters (see below).</p></dd><dt><span class="term">0x22</span></dt><dd><p> |
| 148 | The value of the ascii quote - this is a quoted string.</p></dd><dt><span class="term">Open parenthesis: '('</span></dt><dd><p> |
| 149 | This is an old style comment. A deprecated form of E-mail |
| 150 | addressing uses - for example - |
| 151 | "<code class="literal">john@example.com (John Smith)</code>" instead of |
| 152 | "<code class="literal">John Smith <john@example.com></code>". |
| 153 | This old-style notation defined |
| 154 | parenthesized content as arbitrary comments. |
| 155 | The <span class="structname">rfc822token</span> with |
| 156 | <em class="structfield"><code>token</code></em> set to '(' is created for the contents of |
| 157 | the entire comment.</p></dd><dt><span class="term">Symbols: '<', '>', '@', and many others</span></dt><dd><p> |
| 158 | The remaining possible values of <em class="structfield"><code>token</code></em> include all |
| 159 | the characters in RFC 822 headers that have special significance.</p></dd></dl></div><p> |
| 160 | When a <span class="structname">rfc822token</span> structure does not represent a |
| 161 | special character, the <em class="structfield"><code>ptr</code></em> field points to a text |
| 162 | string giving its contents. |
| 163 | The contents are NOT null-terminated, the <em class="structfield"><code>len</code></em> |
| 164 | field contains the number of characters included. |
| 165 | The macro rfc822_is_atom(token) indicates whether |
| 166 | <em class="structfield"><code>ptr</code></em> and <em class="structfield"><code>len</code></em> are used for |
| 167 | the given <em class="structfield"><code>token</code></em>. |
| 168 | Currently <code class="function">rfc822_is_atom</code>() returns true if |
| 169 | <em class="structfield"><code>token</code></em> is a zero byte, '<code class="literal">"</code>', or |
| 170 | '<code class="literal">(</code>'.</p><p> |
| 171 | Note that it's possible that <em class="structfield"><code>len</code></em> might be zero. |
| 172 | This happens with null addresses used as return addresses for delivery status |
| 173 | notifications.</p></div><div class="refsect2" lang="en" xml:lang="en"><a id="id325457" shape="rect"> </a><h3>Working with E-mail addresses</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 174 | void rfc822_deladdr(struct rfc822a *addrs, int index); |
| 175 | |
| 176 | void rfc822tok_print(const struct rfc822token *list, |
| 177 | void (*func)(char, void *), void *func_arg); |
| 178 | |
| 179 | void rfc822_print(const struct rfc822a *addrs, |
| 180 | void (*print_func)(char, void *), |
| 181 | void (*print_separator)(const char *, void *), void *callback_arg); |
| 182 | |
| 183 | void rfc822_addrlist(const struct rfc822a *addrs, |
| 184 | void (*print_func)(char, void *), |
| 185 | void *callback_arg); |
| 186 | |
| 187 | void rfc822_namelist(const struct rfc822a *addrs, |
| 188 | void (*print_func)(char, void *), |
| 189 | void *callback_arg); |
| 190 | |
| 191 | void rfc822_praddr(const struct rfc822a *addrs, |
| 192 | int index, |
| 193 | void (*print_func)(char, void *), |
| 194 | void *callback_arg); |
| 195 | |
| 196 | void rfc822_prname(const struct rfc822a *addrs, |
| 197 | int index, |
| 198 | void (*print_func)(char, void *), |
| 199 | void *callback_arg); |
| 200 | |
| 201 | void rfc822_prname_orlist(const struct rfc822a *addrs, |
| 202 | int index, |
| 203 | void (*print_func)(char, void *), |
| 204 | void *callback_arg); |
| 205 | |
| 206 | char *rfc822_gettok(const struct rfc822token *list); |
| 207 | char *rfc822_getaddrs(const struct rfc822a *addrs); |
| 208 | char *rfc822_getaddr(const struct rfc822a *addrs, int index); |
| 209 | char *rfc822_getname(const struct rfc822a *addrs, int index); |
| 210 | char *rfc822_getname_orlist(const struct rfc822a *addrs, int index); |
| 211 | |
| 212 | char *rfc822_getaddrs_wrap(const struct rfc822a *, int); |
| 213 | </pre></div><p> |
| 214 | These functions are used to work with individual addresses that are parsed |
| 215 | by <code class="function">rfc822a_alloc</code>().</p><p> |
| 216 | <code class="function">rfc822_deladdr</code>() removes a single |
| 217 | <span class="structname">rfc822addr</span> structure, whose |
| 218 | <em class="parameter"><code>index</code></em> is given, from the address array in |
| 219 | <span class="structname">rfc822addr</span>. |
| 220 | <em class="structfield"><code>naddrs</code></em> is decremented by one.</p><p> |
| 221 | <code class="function">rfc822tok_print</code>() converts a tokenized |
| 222 | <em class="parameter"><code>list</code></em> of <span class="structname">rfc822token</span> |
| 223 | objects into a text string. The callback function, |
| 224 | <em class="parameter"><code>func</code></em>, is called one |
| 225 | character at a time, for every character in the tokenized objects. An |
| 226 | arbitrary pointer, <em class="parameter"><code>func_arg</code></em>, is passed unchanged as |
| 227 | the additional argument to the callback function. |
| 228 | <code class="function">rfc822tok_print</code>() is not usually the most |
| 229 | convenient and efficient function, but it has its uses.</p><p> |
| 230 | <code class="function">rfc822_print</code>() takes an entire |
| 231 | <span class="structname">rfc822a</span> structure, and uses the |
| 232 | callback functions to print the contained addresses, in their original form, |
| 233 | separated by commas. The function pointed to by |
| 234 | <em class="parameter"><code>print_func</code></em> is used to |
| 235 | print each individual address, one character at a time. Between the |
| 236 | addresses, the <em class="parameter"><code>print_separator</code></em> function is called to |
| 237 | print the address separator, usually the string ", ". |
| 238 | The <em class="parameter"><code>callback_arg</code></em> argument is passed |
| 239 | along unchanged, as an additional argument to these functions.</p><p> |
| 240 | The functions <code class="function">rfc822_addrlist</code>() and |
| 241 | <code class="function">rfc822_namelist</code>() also print the |
| 242 | contents of the entire <span class="structname">rfc822a</span> structure, but in a |
| 243 | different way. |
| 244 | <code class="function">rfc822_addrlist</code>() prints just the actual E-mail |
| 245 | addresses, not the recipient |
| 246 | names or comments. Each E-mail address is followed by a newline character. |
| 247 | <code class="function">rfc822_namelist</code>() prints just the names or comments, |
| 248 | followed by newlines.</p><p> |
| 249 | The functions <code class="function">rfc822_praddr</code>() and |
| 250 | <code class="function">rfc822_prname</code>() are just like |
| 251 | <code class="function">rfc822_addrlist</code>() and |
| 252 | <code class="function">rfc822_namelist</code>(), except that they print a single name |
| 253 | or address in the <span class="structname">rfc822a</span> structure, given its |
| 254 | <em class="parameter"><code>index</code></em>. The |
| 255 | functions <code class="function">rfc822_gettok</code>(), |
| 256 | <code class="function">rfc822_getaddrs</code>(), <code class="function">rfc822_getaddr</code>(), |
| 257 | and <code class="function">rfc822_getname</code>() are equivalent to |
| 258 | <code class="function">rfc822tok_print</code>(), <code class="function">rfc822_print</code>(), |
| 259 | <code class="function">rfc822_praddr</code>() and <code class="function">rfc822_prname</code>(), |
| 260 | but, instead of using a callback function |
| 261 | pointer, these functions write the output into a dynamically allocated buffer. |
| 262 | That buffer must be destroyed by <code class="function">free</code>(3) after use. |
| 263 | These functions will |
| 264 | return a null pointer in the event of a failure to allocate memory for the |
| 265 | buffer.</p><p> |
| 266 | <code class="function">rfc822_prname_orlist</code>() is similar to |
| 267 | <code class="function">rfc822_prname</code>(), except that it will |
| 268 | also print the legacy RFC822 group list syntax (which are also parsed by |
| 269 | <code class="function">rfc822a_alloc</code>()). <code class="function">rfc822_praddr</code>() |
| 270 | will print an empty string for an index |
| 271 | that corresponds to a group list name (or terminated semicolon). |
| 272 | <code class="function">rfc822_prname</code>() will also print an empty string. |
| 273 | <code class="function">rfc822_prname_orlist</code>() will |
| 274 | instead print either the name of the group list, or a single string ";". |
| 275 | <code class="function">rfc822_getname_orlist</code>() will instead save it into a |
| 276 | dynamically allocated buffer.</p><p> |
| 277 | The function <code class="function">rfc822_getaddrs_wrap</code>() is similar to |
| 278 | <code class="function">rfc822_getaddrs</code>(), except |
| 279 | that the generated text is wrapped on or about the 73rd column, using |
| 280 | newline characters.</p></div><div class="refsect2" lang="en" xml:lang="en"><a id="id325796" shape="rect"> </a><h3>Working with dates</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 281 | time_t timestamp=rfc822_parsedt(const char *datestr) |
| 282 | const char *datestr=rfc822_mkdate(time_t timestamp); |
| 283 | void rfc822_mkdate_buf(time_t timestamp, char *buffer); |
| 284 | </pre></div><p> |
| 285 | These functions convert between timestamps and dates expressed in the |
| 286 | <code class="literal">Date:</code> E-mail header format.</p><p> |
| 287 | <code class="function">rfc822_parsedt</code>() returns the timestamp corresponding to |
| 288 | the given date string (0 if there was a syntax error).</p><p> |
| 289 | <code class="function">rfc822_mkdate</code>() returns a date string corresponding to |
| 290 | the given timestamp. |
| 291 | <code class="function">rfc822_mkdate_buf</code>() writes the date string into the |
| 292 | given buffer instead, |
| 293 | which must be big enough to accommodate it.</p></div><div class="refsect2" lang="en" xml:lang="en"><a id="id325849" shape="rect"> </a><h3>Working with 8-bit MIME-encoded headers</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 294 | int error=rfc2047_decode(const char *text, |
| 295 | int (*callback_func)(const char *, int, const char *, void *), |
| 296 | void *callback_arg); |
| 297 | |
| 298 | extern char *str=rfc2047_decode_simple(const char *text); |
| 299 | |
| 300 | extern char *str=rfc2047_decode_enhanced(const char *text, |
| 301 | const char *charset); |
| 302 | |
| 303 | void rfc2047_print(const struct rfc822a *a, |
| 304 | const char *charset, |
| 305 | void (*print_func)(char, void *), |
| 306 | void (*print_separator)(const char *, void *), void *); |
| 307 | |
| 308 | |
| 309 | char *buffer=rfc2047_encode_str(const char *string, |
| 310 | const char *charset); |
| 311 | |
| 312 | int error=rfc2047_encode_callback(const char *string, |
| 313 | const char *charset, |
| 314 | int (*func)(const char *, size_t, void *), |
| 315 | void *callback_arg); |
| 316 | |
| 317 | char *buffer=rfc2047_encode_header(const struct rfc822a *a, |
| 318 | const char *charset); |
| 319 | </pre></div><p> |
| 320 | These functions provide additional logic to encode or decode 8-bit content |
| 321 | in 7-bit RFC 822 headers, as specified in RFC 2047.</p><p> |
| 322 | <code class="function">rfc2047_decode</code>() is a basic RFC 2047 decoding function. |
| 323 | It receives a |
| 324 | pointer to some 7bit RFC 2047-encoded text, and a callback function. The |
| 325 | callback function is repeatedly called. Each time it's called it receives a |
| 326 | piece of decoded text. The arguments are: a pointer to a text fragment, number |
| 327 | of bytes in the text fragment, followed by a pointer to the character set of |
| 328 | the text fragment. The character set pointer is NULL for portions of the |
| 329 | original text that are not RFC 2047-encoded.</p><p> |
| 330 | The callback function also receives <em class="parameter"><code>callback_arg</code></em>, as |
| 331 | its last |
| 332 | argument. If the callback function returns a non-zero value, |
| 333 | <code class="function">rfc2047_decode</code>() |
| 334 | terminates, returning that value. Otherwise, |
| 335 | <code class="function">rfc2047_decode</code>() returns 0 after |
| 336 | a successful decoding. <code class="function">rfc2047_decode</code>() returns -1 if it |
| 337 | was unable to allocate sufficient memory.</p><p> |
| 338 | <code class="function">rfc2047_decode_simple</code>() and |
| 339 | <code class="function">rfc2047_decode_enhanced</code>() are alternatives to |
| 340 | <code class="function">rfc2047_decode</code>() which forego a callback function, and |
| 341 | return the decoded text |
| 342 | in a dynamically-allocated memory buffer. The buffer must be |
| 343 | <code class="function">free</code>(3)-ed after |
| 344 | use. <code class="function">rfc2047_decode_simple</code>() discards all character set |
| 345 | specifications, and |
| 346 | merely decodes any 8-bit text. <code class="function">rfc2047_decode_enhanced</code>() |
| 347 | is a compromise to |
| 348 | discarding all character set information. The local character set being used |
| 349 | is specified as the second argument to |
| 350 | <code class="function">rfc2047_decode_enhanced</code>(). Any RFC |
| 351 | 2047-encoded text in a different character set will be prefixed by the name of |
| 352 | the character set, in brackets, in the resulting output.</p><p> |
| 353 | <code class="function">rfc2047_decode_simple</code>() and |
| 354 | <code class="function">rfc2047_decode_enhanced</code>() return a null pointer |
| 355 | if they are unable to allocate sufficient memory.</p><p> |
| 356 | The <code class="function">rfc2047_print</code>() function is equivalent to |
| 357 | <code class="function">rfc822_print</code>(), followed by |
| 358 | <code class="function">rfc2047_decode_enhanced</code>() on the result. The callback |
| 359 | functions are used in |
| 360 | an identical fashion, except that they receive text that's already |
| 361 | decoded.</p><p> |
| 362 | The function <code class="function">rfc2047_encode_str</code>() takes a |
| 363 | <em class="parameter"><code>string</code></em> and <em class="parameter"><code>charset</code></em> |
| 364 | being the name of the local character set, then encodes any 8-bit portions of |
| 365 | <em class="parameter"><code>string</code></em> using RFC 2047 encoding. |
| 366 | <code class="function">rfc2047_encode_str</code>() returns a |
| 367 | dynamically-allocated buffer with the result, which must be |
| 368 | <code class="function">free</code>(3)-ed after |
| 369 | use, or NULL if there was insufficient memory to allocate the buffer.</p><p> |
| 370 | The function <code class="function">rfc2047_encode_callback</code>() is similar to |
| 371 | <code class="function">rfc2047_encode_str</code>() |
| 372 | except that the callback function is repeatedly called to received the |
| 373 | encoding string. Each invocation of the callback function receives a pointer |
| 374 | to a portion of the encoded text, the number of characters in this portion, |
| 375 | and <em class="parameter"><code>callback_arg</code></em>.</p><p> |
| 376 | The function <code class="function">rfc2047_encode_header</code>() is basically |
| 377 | equivalent to <code class="function">rfc822_getaddrs</code>(), followed by |
| 378 | <code class="function">rfc2047_encode_str</code>();</p></div><div class="refsect2" lang="en" xml:lang="en"><a id="id326091" shape="rect"> </a><h3>Working with subjects</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
| 379 | char *basesubj=rfc822_coresubj(const char *subj); |
| 380 | |
| 381 | char *basesubj=rfc822_coresubj_nouc(const char *subj); |
| 382 | </pre></div><p> |
| 383 | This function takes the contents of the subject header, and returns the |
| 384 | "core" subject header that's used in the specification of the IMAP THREAD |
| 385 | function. This function is designed to strip all subject line artifacts that |
| 386 | might've been added in the process of forwarding or replying to a message. |
| 387 | Currently, <code class="function">rfc822_coresubj</code>() performs the following transformations:</p><div class="variablelist"><dl><dt><span class="term">Whitespace</span></dt><dd><p>Leading and trailing whitespace is removed. Consecutive |
| 388 | whitespace characters are collapsed into a single whitespace character. |
| 389 | All whitespace characters are replaced by a space.</p></dd><dt><span class="term">Re:, (fwd) [foo]</span></dt><dd><p> |
| 390 | These artifacts (and several others) are removed from |
| 391 | the subject line.</p></dd></dl></div><p>Note that this function does NOT do MIME decoding. In order to |
| 392 | implement IMAP THREAD, it is necessary to call something like |
| 393 | <code class="function">rfc2047_decode</code>() before |
| 394 | calling <code class="function">rfc822_coresubj</code>().</p><p> |
| 395 | This function returns a pointer to a dynamically-allocated buffer, which |
| 396 | must be <code class="function">free</code>(3)-ed after use.</p><p> |
| 397 | <code class="function">rfc822_coresubj_nouc</code>() is like |
| 398 | <code class="function">rfc822_coresubj</code>(), except that the subject |
| 399 | is not converted to uppercase.</p></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="id326194" shape="rect"> </a><h2>SEE ALSO</h2><p> |
| 400 | <a href="rfc2045.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">rfc2045</span>(3)</span></a>, |
| 401 | <a href="reformail.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">reformail</span>(1)</span></a>, |
| 402 | <a href="reformime.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">reformime</span>(1)</span></a>.</p></div></div></body></html> |