Back to index

courier  0.68.2
rfc822.h
Go to the documentation of this file.
00001 /*
00002 */
00003 #ifndef       rfc822_h
00004 #define       rfc822_h
00005 
00006 /*
00007 ** Copyright 1998 - 2009 Double Precision, Inc.
00008 ** See COPYING for distribution information.
00009 */
00010 
00011 #if    HAVE_CONFIG_H
00012 #include      "../rfc822/config.h" /* VPATH build */
00013 #endif
00014 
00015 #include      <time.h>
00016 
00017 #ifdef  __cplusplus
00018 extern "C" {
00019 #endif
00020 
00021 #define RFC822_SPECIALS "()<>[]:;@\\,.\""
00022 
00023 /*
00024 ** The text string we want to parse is first tokenized into an array of
00025 ** struct rfc822token records.  'ptr' points into the original text
00026 ** string, and 'len' has how many characters from 'ptr' belongs to this
00027 ** token.
00028 */
00029 
00030 struct rfc822token {
00031        struct rfc822token *next;   /* Unused by librfc822, for use by
00032                                    ** clients */
00033        int token;
00034 /*
00035   Values for token:
00036 
00037   '(' - comment
00038   '"' - quoted string
00039   '<', '>', '@', ',', ';', ':', '.', '[', ']', '%', '!', '=', '?', '/' - RFC atoms.
00040   0   - atom
00041 */
00042 
00043 #define       rfc822_is_atom(p)    ( (p) == 0 || (p) == '"' || (p) == '(' )
00044 
00045        const char *ptr;     /* Pointer to value for the token. */
00046        int len;             /* Length of token value */
00047 } ;
00048 
00049 /*
00050 ** After the struct rfc822token array is built, it is used to create
00051 ** the rfc822addr array, which is the array of addresses (plus
00052 ** syntactical fluff) extracted from those text strings.  Each rfc822addr
00053 ** record has several possible interpretation:
00054 **
00055 ** tokens is NULL - syntactical fluff, look in name/nname for tokens
00056 **                  representing the syntactical fluff ( which is semicolons
00057 **                  and  list name:
00058 **
00059 ** tokens is not NULL - actual address.  The tokens representing the actual
00060 **                  address is in tokens/ntokens.  If there are comments in
00061 **                  the address that are possible "real name" for the address
00062 **                  they are saved in name/nname (name may be null if there
00063 **                  is none).
00064 **                  If nname is 1, and name points to a comment token,
00065 **                  the address was specified in old-style format.  Otherwise
00066 **                  the address was specified in new-style route-addr format.
00067 **
00068 ** The tokens and name pointers are set to point to the original rfc822token
00069 ** array.
00070 */
00071 
00072 struct rfc822addr {
00073        struct rfc822token *tokens;
00074        struct rfc822token *name;
00075 } ;
00076 
00077 /***************************************************************************
00078 **
00079 ** rfc822 tokens
00080 **
00081 ***************************************************************************/
00082 
00083 struct rfc822t {
00084        struct rfc822token *tokens;
00085        int    ntokens;
00086 } ;
00087 
00088 struct rfc822t *rfc822t_alloc_new(const char *p,
00089        void (*err_func)(const char *, int, void *), void *);
00090        /* Parse addresses */
00091 
00092 void rfc822t_free(struct rfc822t *);             /* Free rfc822 structure */
00093 
00094 void rfc822tok_print(const struct rfc822token *, void (*)(char, void *), void *);
00095                                           /* Print the tokens */
00096 
00097 /***************************************************************************
00098 **
00099 ** rfc822 addresses
00100 **
00101 ***************************************************************************/
00102 
00103 struct rfc822a {
00104        struct rfc822addr *addrs;
00105        int    naddrs;
00106 } ;
00107 
00108 struct rfc822a *rfc822a_alloc(struct rfc822t *);
00109 void rfc822a_free(struct rfc822a *);             /* Free rfc822 structure */
00110 
00111 void rfc822_deladdr(struct rfc822a *, int);
00112 
00113 /* rfc822_print "unparses" the rfc822 structure.  Each rfc822addr is "printed"
00114    (via the attached function).  NOTE: instead of separating addresses by
00115    commas, the print_separator function is called.
00116 */
00117 
00118 int rfc822_print(const struct rfc822a *a,
00119        void (*print_func)(char, void *),
00120        void (*print_separator)(const char *, void *), void *);
00121 
00122 /* rfc822_print_common is an internal function */
00123 
00124 int rfc822_print_common(const struct rfc822a *a,
00125                       char *(*decode_func)(const char *, const char *, int),
00126                       const char *chset,
00127                       void (*print_func)(char, void *),
00128                       void (*print_separator)(const char *, void *), void *);
00129 
00130 /* Extra functions */
00131 
00132 char *rfc822_gettok(const struct rfc822token *);
00133 char *rfc822_getaddr(const struct rfc822a *, int);
00134 char *rfc822_getaddrs(const struct rfc822a *);
00135 char *rfc822_getaddrs_wrap(const struct rfc822a *, int);
00136 
00137 void rfc822_mkdate_buf(time_t, char *);
00138 const char *rfc822_mkdate(time_t);
00139 time_t rfc822_parsedt(const char *);
00140 
00141 #define CORESUBJ_RE 1
00142 #define CORESUBJ_FWD 2
00143 
00144 char *rfc822_coresubj(const char *, int *);
00145 char *rfc822_coresubj_nouc(const char *, int *);
00146 char *rfc822_coresubj_keepblobs(const char *s);
00147 
00148 /*
00149 ** Display a header. Takes a raw header value, and formats it for display
00150 ** in the given character set.
00151 **
00152 ** hdrname -- header name. Determines whether the header contains addresses,
00153 **            or unstructured data.
00154 **
00155 ** hdrvalue -- the actual value to format.
00156 **
00157 ** display_func -- output function.
00158 **
00159 ** err_func -- if this function returns a negative value, to indicate an error,
00160 ** this may be called just prior to the error return to indicate where the
00161 ** formatting error is, in the original header.
00162 **
00163 ** ptr -- passthrough last argument to display_func or err_func.
00164 **
00165 ** repeatedly invokes display_func to pass the formatted contents.
00166 **
00167 ** Returns 0 upon success, -1 upon a failure.
00168 */
00169 
00170 int rfc822_display_hdrvalue(const char *hdrname,
00171                          const char *hdrvalue,
00172                          const char *charset,
00173                          void (*display_func)(const char *, size_t,
00174                                            void *),
00175                          void (*err_func)(const char *, int, void *),
00176                          void *ptr);
00177 
00178 /*
00179 ** Like rfc822_display_hdrvalue, except that the converted header is saved in
00180 ** a malloc-ed buffer. The pointer to the malloc-ed buffer is returned, the
00181 ** caller is responsible for free-ing it. An error condition is indicated
00182 ** by a NULL return value.
00183 */
00184 
00185 char *rfc822_display_hdrvalue_tobuf(const char *hdrname,
00186                                 const char *hdrvalue,
00187                                 const char *charset,
00188                                 void (*err_func)(const char *, int,
00189                                                void *),
00190                                 void *ptr);
00191 
00192 /*
00193 ** Display a recipient's name in a specific character set.
00194 **
00195 ** The index-th recipient in the address structure is formatted for the given
00196 ** character set. If the index-th entry in the address structure is not
00197 ** a recipient address (it represents an obsolete list name indicator),
00198 ** this function reproduces it literally.
00199 **
00200 ** If the index-th entry in the address structure is a recipient address without
00201 ** a name, the address itself is formatted for the given character set.
00202 **
00203 ** If 'charset' is NULL, the name is formatted as is, without converting
00204 ** it to any character set.
00205 **
00206 ** A callback function gets repeatedly invoked to produce the name.
00207 **
00208 ** Returns a negative value upon a formatting error.
00209 */
00210 
00211 int rfc822_display_name(const struct rfc822a *rfcp, int index,
00212                      const char *chset,
00213                      void (*print_func)(const char *, size_t, void *),
00214                      void *ptr);
00215 
00216 /*
00217 ** Display a recipient's name in a specific character set.
00218 **
00219 ** Uses rfc822_display_name to place the generated name into a malloc-ed
00220 ** buffer. The caller must free it when it is no longer needed.
00221 **
00222 ** Returns NULL upon an error.
00223 */
00224 
00225 char *rfc822_display_name_tobuf(const struct rfc822a *rfcp, int index,
00226                             const char *chset);
00227 
00228 /*
00229 ** Display names of all addresses. Each name is followed by a newline
00230 ** character.
00231 **
00232 */
00233 int rfc822_display_namelist(const struct rfc822a *rfcp,
00234                          const char *chset,
00235                          void (*print_func)(const char *, size_t, void *),
00236                          void *ptr);
00237 
00238 /*
00239 ** Display a recipient's address in a specific character set.
00240 **
00241 ** The index-th recipient in the address structure is formatted for the given
00242 ** character set. If the index-th entry in the address structure is not
00243 ** a recipient address (it represents an obsolete list name indicator),
00244 ** this function produces an empty string.
00245 **
00246 ** If 'charset' is NULL, the address is formatted as is, without converting
00247 ** it to any character set.
00248 **
00249 ** A callback function gets repeatedly invoked to produce the address.
00250 **
00251 ** Returns a negative value upon a formatting error.
00252 */
00253 
00254 int rfc822_display_addr(const struct rfc822a *rfcp, int index,
00255                      const char *chset,
00256                      void (*print_func)(const char *, size_t, void *),
00257                      void *ptr);
00258 
00259 /*
00260 ** Like rfc822_display_addr, but the resulting displayable string is
00261 ** saved in a buffer. Returns a malloc-ed buffer, the caller is responsible
00262 ** for free()ing it. A NULL return indicates an error.
00263 */
00264 
00265 char *rfc822_display_addr_tobuf(const struct rfc822a *rfcp, int index,
00266                             const char *chset);
00267 
00268 /*
00269 ** Like rfc822_display_addr, but the user@domain gets supplied in a string.
00270 */
00271 int rfc822_display_addr_str(const char *tok,
00272                          const char *chset,
00273                          void (*print_func)(const char *, size_t, void *),
00274                          void *ptr);
00275 
00276 /*
00277 ** Like rfc822_display_addr_str, but the resulting displayable string is
00278 ** saved in a buffer. Returns a malloc-ed buffer, the caller is responsible
00279 ** for free()ing it. A NULL return indicates an error.
00280 */
00281 char *rfc822_display_addr_str_tobuf(const char *tok,
00282                                 const char *chset);
00283 
00284 /*
00285 ** address is a hostname, which is IDN-encoded. 'address' may contain an
00286 ** optional 'user@', which is preserved. Returns a malloc-ed buffer, the
00287 ** caller is responsible for freeing it.
00288 */
00289 char *rfc822_encode_domain(const char *address,
00290                         const char *charset);
00291 
00292 #ifdef  __cplusplus
00293 }
00294 #endif
00295 
00296 #endif