d9898ee8 |
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> |