Commit | Line | Data |
---|---|---|
d9898ee8 | 1 | <?xml version="1.0"?> |
b0322a85 | 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" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"/><link rel="home" href="#idm247873168272" 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"/><!-- |
d9898ee8 | 3 | |
b0322a85 | 4 | Copyright 1998 - 2009 Double Precision, Inc. See COPYING for distribution |
d9898ee8 | 5 | information. |
6 | ||
b0322a85 | 7 | --></head><body><div class="refentry"><a id="idm247873168272" 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"> |
d9898ee8 | 8 | #include <rfc822.h> |
9 | ||
10 | #include <rfc2047.h> | |
11 | ||
12 | cc ... -lrfc822 | |
b0322a85 | 13 | </pre></div></div><div class="refsect1"><a id="idm247873116928" shape="rect"> </a><h2>DESCRIPTION</h2><p> |
d9898ee8 | 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 | |
8d138742 | 19 | <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc822.txt" target="_top" shape="rect">RFC 822</a> |
d9898ee8 | 20 | (and its successor, |
8d138742 | 21 | <a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2822.txt" target="_top" shape="rect">RFC 2822</a>). |
d9898ee8 | 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 | |
b0322a85 | 30 | convert it back into a text string.</p><div class="refsect2"><a id="idm247873111200" shape="rect"> </a><h3>Tokenizing an E-mail header</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
d9898ee8 | 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>, | |
b0322a85 | 70 | and they must remain valid.</p></div></div><div class="refsect2"><a id="idm247873153904" shape="rect"> </a><h3>Extracting E-mail addresses</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
d9898ee8 | 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 | |
b0322a85 | 145 | are:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">0x00</span></dt><dd><p> |
d9898ee8 | 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 | |
b0322a85 | 173 | notifications.</p></div><div class="refsect2"><a id="idm247867853536" shape="rect"> </a><h3>Working with E-mail addresses</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
d9898ee8 | 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 | |
b0322a85 | 280 | newline characters.</p></div><div class="refsect2"><a id="idm247867812992" shape="rect"> </a><h3>Working with dates</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
d9898ee8 | 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, | |
b0322a85 | 293 | which must be big enough to accommodate it.</p></div><div class="refsect2"><a id="idm247867806656" shape="rect"> </a><h3>Working with 8-bit MIME-encoded headers</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
d9898ee8 | 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 | |
b0322a85 | 378 | <code class="function">rfc2047_encode_str</code>();</p></div><div class="refsect2"><a id="idm247867777760" shape="rect"> </a><h3>Working with subjects</h3><div class="informalexample"><pre class="programlisting" xml:space="preserve"> |
d9898ee8 | 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. | |
b0322a85 | 387 | Currently, <code class="function">rfc822_coresubj</code>() performs the following transformations:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Whitespace</span></dt><dd><p>Leading and trailing whitespace is removed. Consecutive |
d9898ee8 | 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 | |
b0322a85 | 399 | is not converted to uppercase.</p></div></div><div class="refsect1"><a id="idm247867765456" shape="rect"> </a><h2>SEE ALSO</h2><p> |
8d138742 CE |
400 | <a class="ulink" href="rfc2045.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">rfc2045</span>(3)</span></a>, |
401 | <a class="ulink" href="reformail.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">reformail</span>(1)</span></a>, | |
402 | <a class="ulink" href="reformime.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">reformime</span>(1)</span></a>.</p></div></div></body></html> |