diplodocus.org Git - nmh/blob - h/mhparse.h

   1 /* mhparse.h -- definitions for parsing/building of MIME content
   2  *           -- (mhparse.c/mhbuildsbr.c)
   3  */
   4
   5 /*
   6  * Abstract type for header fields
   7  */
   8 typedef struct hfield *HF;
   9
  10 /*
  11  * Abstract types for MIME parsing/building
  12  */
  13 typedef struct cefile           *CE;
  14 typedef struct CTinfo           *CI;
  15 typedef struct Content          *CT;
  16 typedef struct Parameter        *PM;
  17
  18 /*
  19  * type for Init function (both type and transfer encoding)
  20  */
  21 typedef int (*InitFunc) (CT);
  22
  23 /*
  24  * types for various transfer encoding access functions
  25  */
  26 typedef int (*OpenCEFunc) (CT, char **);
  27 typedef void (*CloseCEFunc) (CT);
  28 typedef unsigned long (*SizeCEFunc) (CT);
  29
  30 /*
  31  * Structure for storing/encoding/decoding
  32  * a header field and its value.
  33  */
  34 struct hfield {
  35     char *name;         /* field name */
  36     char *value;        /* field body */
  37     HF next;            /* link to next header field */
  38 };
  39
  40 /*
  41  * Structure for holding MIME parameter elements.
  42  */
  43 struct Parameter {
  44     char *pm_name;      /* Parameter name */
  45     char *pm_value;     /* Parameter value */
  46     char *pm_charset;   /* Parameter character set (optional) */
  47     char *pm_lang;      /* Parameter language tag (optional) */
  48     PM   pm_next;       /* Pointer to next element */
  49 };
  50
  51 /*
  52  * Structure for storing parsed elements
  53  * of the Content-Type component.
  54  */
  55 struct CTinfo {
  56     char *ci_type;              /* content type     */
  57     char *ci_subtype;           /* content subtype  */
  58     PM   ci_first_pm;           /* Pointer to first MIME parameter */
  59     PM   ci_last_pm;            /* Pointer to last MIME parameter */
  60     char *ci_comment;           /* RFC-822 comments */
  61     char *ci_magic;
  62 };
  63
  64 /*
  65  * Structure for storing decoded contents after
  66  * removing Content-Transfer-Encoding.
  67  */
  68 struct cefile {
  69     char *ce_file;      /* decoded content (file)   */
  70     FILE *ce_fp;        /* decoded content (stream) */
  71     int   ce_unlink;    /* remove file when done?   */
  72 };
  73
  74 /*
  75  * Primary structure for handling Content (Entity)
  76  *
  77  * Some more explanation of this:
  78  *
  79  * This structure recursively describes a complete MIME message.
  80  * At the top level, the c_first_hf list has a list of all message
  81  * headers.  If the content-type is multipart (c_type == CT_MULTIPART)
  82  * then c_ctparams will contain a pointer to a struct multipart.
  83  * A struct multipart contains (among other things) a linked list
  84  * of struct part elements, and THOSE contain a pointer to the sub-part's
  85  * Content structure.
  86  *
  87  * An extra note for message/external-body parts.  The enclosing
  88  * content structure is marked as a message/external-body; the c_ctparams
  89  * contains a pointer to a struct exbody, which contains a pointer to
  90  * (among other things) the "real" content (e.g., application/octet-stream).
  91  * The "real" content structure has the c_ctexbody pointer back to the
  92  * same struct exbody sees in the enclosing content structure (the struct
  93  * exbody contains parent pointers if you need to traverse up the content
  94  * structure).  Hopefully this makes it clearer:
  95  *
  96  * Enclosing content:
  97  *   Type: message/external-body
  98  *   c_ctparams: pointer to "struct exbody"
  99  *   c_ctexbody: NULL
 100  *
 101  * "Real" content:
 102  *   Type: application/octet-stream (or whatever)
 103  *   c_ctparams: NULL
 104  *   c_ctexbody: pointer to "struct exbody"
 105  *
 106  */
 107 struct Content {
 108     /* source (read) file */
 109     char *c_file;               /* read contents (file)              */
 110     FILE *c_fp;                 /* read contents (stream)            */
 111     int c_unlink;               /* remove file when done?            */
 112
 113     long c_begin;               /* where content body starts in file */
 114     long c_end;                 /* where content body ends in file   */
 115
 116     /* linked list of header fields */
 117     HF c_first_hf;              /* pointer to first header field     */
 118     HF c_last_hf;               /* pointer to last header field      */
 119
 120     /* copies of MIME related header fields */
 121     char *c_vrsn;               /* MIME-Version:                     */
 122     char *c_ctline;             /* Content-Type:                     */
 123     char *c_celine;             /* Content-Transfer-Encoding:        */
 124     char *c_id;                 /* Content-ID:                       */
 125     char *c_descr;              /* Content-Description:              */
 126     char *c_dispo;              /* Content-Disposition:              */
 127     char *c_dispo_type;         /* Type of Content-Disposition       */
 128     PM c_dispo_first;           /* Pointer to first disposition parm */
 129     PM c_dispo_last;            /* Pointer to last disposition parm  */
 130     char *c_partno;             /* within multipart content          */
 131
 132     /* Content-Type info */
 133     struct CTinfo c_ctinfo;     /* parsed elements of Content-Type   */
 134     int c_type;                 /* internal flag for content type    */
 135     int c_subtype;              /* internal flag for content subtype */
 136
 137     /* Content-Transfer-Encoding info (decoded contents) */
 138     struct cefile c_cefile;     /* structure holding decoded content */
 139     int c_encoding;             /* internal flag for encoding type   */
 140     int c_reqencoding;          /* Requested encoding (by mhbuild)   */
 141
 142     /* Content-MD5 info */
 143     int c_digested;             /* have we seen this header before?  */
 144     unsigned char c_digest[16]; /* decoded MD5 checksum              */
 145
 146     /* pointers to content-specific structures */
 147     void *c_ctparams;           /* content type specific data        */
 148     struct exbody *c_ctexbody;  /* data for type message/external    */
 149
 150     /* function pointers */
 151     InitFunc    c_ctinitfnx;    /* parse content body                */
 152     OpenCEFunc  c_ceopenfnx;    /* get a stream to decoded contents  */
 153     CloseCEFunc c_ceclosefnx;   /* release stream                    */
 154     SizeCEFunc  c_cesizefnx;    /* size of decoded contents          */
 155
 156     int c_umask;                /* associated umask                  */
 157     int c_rfc934;               /* RFC 934 compatibility flag        */
 158
 159     char *c_showproc;           /* default, if not in profile        */
 160     char *c_termproc;           /* for charset madness...            */
 161     char *c_storeproc;          /* overrides profile entry, if any   */
 162
 163     char *c_storage;            /* write contents (file)             */
 164     char *c_folder;             /* write contents (folder)           */
 165 };
 166
 167 /*
 168  * Flags for Content-Type (Content->c_type)
 169  */
 170 #define CT_UNKNOWN      0x00
 171 #define CT_APPLICATION  0x01
 172 #define CT_AUDIO        0x02
 173 #define CT_IMAGE        0x03
 174 #define CT_MESSAGE      0x04
 175 #define CT_MULTIPART    0x05
 176 #define CT_TEXT         0x06
 177 #define CT_VIDEO        0x07
 178 #define CT_EXTENSION    0x08
 179
 180 /*
 181  * Flags for Content-Transfer-Encoding (Content->c_encoding)
 182  */
 183 #define CE_UNKNOWN      0x00
 184 #define CE_BASE64       0x01
 185 #define CE_QUOTED       0x02
 186 #define CE_8BIT         0x03
 187 #define CE_7BIT         0x04
 188 #define CE_BINARY       0x05
 189 #define CE_EXTENSION    0x06
 190 #define CE_EXTERNAL     0x07    /* for external-body */
 191
 192 /*
 193  * TEXT content
 194  */
 195
 196 /* Flags for subtypes of TEXT */
 197 #define TEXT_UNKNOWN    0x00
 198 #define TEXT_PLAIN      0x01
 199 #define TEXT_RICHTEXT   0x02
 200 #define TEXT_ENRICHED   0x03
 201
 202 /* Flags for character sets */
 203 #define CHARSET_SPECIFIED    0x00
 204 #define CHARSET_UNSPECIFIED 0x01  /* only needed when building drafts */
 205
 206 /* Structure for text content */
 207 struct text {
 208     int tx_charset;             /* flag for character set */
 209     int lf_line_endings;        /* Whether to use CR LF (0) or LF (1) line
 210                                    endings.  The meaning of 0 was selected so
 211                                    that CR LF is the default, in accordance
 212                                    with RFC 2046, Sec. 4.1.1, Par. 1. */
 213 };
 214
 215 /*
 216  * MULTIPART content
 217  */
 218
 219 /* Flags for subtypes of MULTIPART */
 220 #define MULTI_UNKNOWN   0x00
 221 #define MULTI_MIXED     0x01
 222 #define MULTI_ALTERNATE 0x02
 223 #define MULTI_DIGEST    0x03
 224 #define MULTI_PARALLEL  0x04
 225 #define MULTI_RELATED   0x05
 226
 227 /* Structure for subparts of a multipart content */
 228 struct part {
 229     CT mp_part;                 /* Content structure for subpart     */
 230     struct part *mp_next;       /* pointer to next subpart structure */
 231 };
 232
 233 /* Main structure for multipart content */
 234 struct multipart {
 235     char *mp_start;             /* boundary string separating parts   */
 236     char *mp_stop;              /* terminating boundary string        */
 237     char *mp_content_before;    /* any content before the first subpart */
 238     char *mp_content_after;     /* any content after the last subpart */
 239     struct part *mp_parts;      /* pointer to first subpart structure */
 240 };
 241
 242 /*
 243  * MESSAGE content
 244  */
 245
 246 /* Flags for subtypes of MESSAGE */
 247 #define MESSAGE_UNKNOWN  0x00
 248 #define MESSAGE_RFC822   0x01
 249 #define MESSAGE_PARTIAL  0x02
 250 #define MESSAGE_EXTERNAL 0x03
 251
 252 /* Structure for message/partial */
 253 struct partial {
 254     char *pm_partid;
 255     int pm_partno;
 256     int pm_maxno;
 257     int pm_marked;
 258     int pm_stored;
 259 };
 260
 261 /* Structure for message/external */
 262 struct exbody {
 263     CT eb_parent;       /* pointer to controlling content structure */
 264     CT eb_content;      /* pointer to internal content structure    */
 265     char *eb_partno;
 266     char *eb_access;
 267     int eb_flags;
 268     char *eb_name;
 269     char *eb_permission;
 270     char *eb_site;
 271     char *eb_dir;
 272     char *eb_mode;
 273     unsigned long eb_size;
 274     char *eb_server;
 275     char *eb_subject;
 276     char *eb_body;
 277     char *eb_url;
 278 };
 279
 280 /*
 281  * APPLICATION content
 282  */
 283
 284 /* Flags for subtype of APPLICATION */
 285 #define APPLICATION_UNKNOWN     0x00
 286 #define APPLICATION_OCTETS      0x01
 287 #define APPLICATION_POSTSCRIPT  0x02
 288
 289
 290 /*
 291  * Structures for mapping types to their internal flags
 292  */
 293 struct k2v {
 294     char *kv_key;
 295     int   kv_value;
 296 };
 297 extern struct k2v SubText[];
 298 extern struct k2v Charset[];
 299 extern struct k2v SubMultiPart[];
 300 extern struct k2v SubMessage[];
 301 extern struct k2v SubApplication[];
 302
 303 /*
 304  * Structures for mapping (content) types to
 305  * the functions to handle them.
 306  */
 307 struct str2init {
 308     char *si_key;
 309     int   si_val;
 310     InitFunc si_init;
 311 };
 312 extern struct str2init str2cts[];
 313 extern struct str2init str2ces[];
 314 extern struct str2init str2methods[];
 315
 316 /*
 317  * prototypes
 318  */
 319 CT parse_mime (char *);
 320
 321 /*
 322  * Translate a composition file into a MIME data structure.  Arguments are:
 323  *
 324  * infile       - Name of input filename
 325  * autobuild    - A flag to indicate if the composition file parser is
 326  *                being run in automatic mode or not.  In auto mode,
 327  *                if a MIME-Version header is encountered it is assumed
 328  *                that the composition file is already in MIME format
 329  *                and will not be processed further.  Otherwise, an
 330  *                error is generated.
 331  * dist         - A flag to indicate if we are being run by "dist".  In
 332  *                that case, add no MIME headers to the message.  Existing
 333  *                headers will still be encoded by RFC 2047.
 334  * directives   - A flag to control whether or not build directives are
 335  *                processed by default.
 336  * encoding     - The default encoding to use when doing RFC 2047 header
 337  *                encoding.  Must be one of CE_UNKNOWN, CE_BASE64, or
 338  *                CE_QUOTED.
 339  * maxunencoded - The maximum line length before the default encoding for
 340  *                text parts is quoted-printable.
 341  * verbose      - If 1, output verbose information during message composition
 342  *
 343  * Returns a CT structure describing the resulting MIME message.  If the
 344  * -auto flag is set and a MIME-Version header is encountered, the return
 345  * value is NULL.
 346  */
 347 CT build_mime (char *infile, int autobuild, int dist, int directives,
 348                int encoding, size_t maxunencoded, int verbose);
 349
 350 int add_header (CT, char *, char *);
 351 int get_ctinfo (char *, CT, int);
 352 int params_external (CT, int);
 353 int open7Bit (CT, char **);
 354 void close_encoding (CT);
 355 char *ct_type_str (int) CONST;
 356 char *ct_subtype_str (int, int) CONST;
 357 int ct_str_type (const char *) PURE;
 358 int ct_str_subtype (int, const char *) PURE;
 359 const struct str2init *get_ct_init (int) PURE;
 360 const char *ce_str (int) CONST;
 361 const struct str2init *get_ce_method (const char *) PURE;
 362 char *content_charset (CT);
 363 void reverse_alternative_parts (CT);
 364
 365 /*
 366  * Given a list of messages, display information about them on standard
 367  * output.
 368  *
 369  * Arguments are:
 370  *
 371  * cts          - An array of CT elements of messages that need to be
 372  *                displayed.  Array is terminated by a NULL.
 373  * headsw       - If 1, display a column header.
 374  * sizesw       - If 1, display the size of the part.
 375  * verbosw      - If 1, display verbose information
 376  * debugsw      - If 1, turn on debugging for the output.
 377  * disposw      - If 1, display MIME part disposition information.
 378  *
 379  */
 380 void list_all_messages(CT *cts, int headsw, int sizesw, int verbosw,
 381                        int debugsw, int disposw);
 382
 383 /*
 384  * List the content information of a single MIME part on stdout.
 385  *
 386  * Arguments are:
 387  *
 388  * ct           - MIME Content structure to display.
 389  * toplevel     - If set, we're at the top level of a message
 390  * realsize     - If set, determine the real size of the content
 391  * verbose      - If set, output verbose information
 392  * debug        - If set, turn on debugging for the output
 393  * dispo        - If set, display MIME part disposition information.
 394  *
 395  * Returns OK on success, NOTOK otherwise.
 396  */
 397 int list_content(CT ct, int toplevel, int realsize, int verbose, int debug,
 398                  int dispo);
 399
 400 /*
 401  * Display content-appropriate information on MIME parts, descending recursively
 402  * into multipart content if appropriate.  Uses list_content() for displaying
 403  * generic information.
 404  *
 405  * Arguments and return value are the same as list_content().
 406  */
 407 int list_switch(CT ct, int toplevel, int realsize, int verbose, int debug,
 408                 int dispo);
 409
 410 /*
 411  * Given a linked list of parameters, build an output string for them.  This
 412  * string is designed to be concatenated on an already-built header.
 413  *
 414  * Arguments are:
 415  *
 416  * initialwidth - Current width of the header.  Used to compute when to wrap
 417  *                parameters on the first line.  The following lines will
 418  *                be prefixed by a tab (\t) character.
 419  * params       - Pointer to head of linked list of parameters.
 420  * offsetout    - The final line offset after all the parameters have been
 421  *                output.  May be NULL.
 422  * external     - If set, outputting an external-body type and will not
 423  *                output a "body" parameter.
 424
 425  * Returns a pointer to the resulting parameter string.  This string must
 426  * be free()'d by the caller.  Returns NULL on error.
 427  */
 428 char *output_params(size_t initialwidth, PM params, int *offsetout,
 429                     int external);
 430
 431 /*
 432  * Encode a parameter value using RFC 2231 encode.
 433  *
 434  * Arguments are:
 435  *
 436  * pm           - PM containing the parameter value and related info.
 437  * output       - Output buffer.
 438  * len          - Size, in octets, of output buffer.
 439  * valuelen     - Number of characters in the value
 440  * valueoff     - Offset into value field (pm->pm_value).
 441  * index        - If 0, output character set and language tag.
 442  */
 443 size_t encode_param(PM pm, char *output, size_t len, size_t valuelen,
 444                     size_t valueoff, int index);
 445
 446 /*
 447  * Add a parameter to the parameter linked list.
 448  *
 449  * Arguments are:
 450  *
 451  * first        - Pointer to head of linked list
 452  * last         - Pointer to tail of linked list
 453  * name         - Name of parameter
 454  * value        - Value of parameter
 455  * nocopy       - If set, will use the pointer values directly for "name"
 456  *                and "value" instead of making their own copy.  These
 457  *                pointers will be free()'d later by the MIME routines, so
 458  *                they should not be used after calling this function!
 459  *
 460  * Returns allocated parameter element
 461  */
 462 PM add_param(PM *first, PM *last, char *name, char *value, int nocopy);
 463
 464 /*
 465  * Replace (or add) a parameter to the parameter linked list.
 466  *
 467  * If the named parameter already exists on the parameter linked list,
 468  * replace the value with the new one.  Otherwise add it to the linked
 469  * list.  All parameters are identical to add_param().
 470  */
 471 PM replace_param(PM *first, PM *last, char *name, char *value, int nocopy);
 472
 473 /*
 474  * Retrieve a parameter value from a parameter linked list.  Convert to the
 475  * local character set if required.
 476  *
 477  * Arguments are:
 478  *
 479  * first        - Pointer to head of parameter linked list.
 480  * name         - Name of parameter.
 481  * replace      - If characters in the parameter list cannot be converted to
 482  *                the local character set, replace with this character.
 483  * fetchonly    - If true, return pointer to original value, no conversion
 484  *                performed.
 485  *
 486  * Returns parameter value if found, NULL otherwise.  Memory must be free()'d
 487  * unless fetchonly is set.
 488  */
 489
 490 char *get_param(PM first, const char *name, char replace, int fetchonly);
 491
 492 /*
 493  * Fetch a parameter value from a parameter structure, converting it to
 494  * the local character set.
 495  *
 496  * Arguments are:
 497  *
 498  * pm           - Pointer to parameter structure
 499  * replace      - If characters in the parameter list cannot be converted to
 500  *                the local character set, replace with this character.
 501  *
 502  * Returns a pointer to the parameter value.  Memory is stored in an
 503  * internal buffer, so the returned value is only valid until the next
 504  * call to get_param_value() or get_param() (get_param() uses get_param_value()
 505  * internally).
 506  */
 507 char *get_param_value(PM pm, char replace);
 508
 509 extern int checksw;     /* Add Content-MD5 field */
 510
 511 /*
 512  * mhstore
 513  * Put it here because it uses the CT typedef.
 514  */
 515 typedef struct mhstoreinfo *mhstoreinfo_t;
 516 mhstoreinfo_t mhstoreinfo_create(CT *, char *, const char *, int, int);
 517 int mhstoreinfo_files_not_clobbered(const mhstoreinfo_t) PURE;
 518 void mhstoreinfo_free(mhstoreinfo_t);
 519 void store_all_messages (mhstoreinfo_t);
 520
 521 extern bool skip_mp_cte_check;
 522 extern bool suppress_bogus_mp_content_warning;
 523 extern bool bogus_mp_content;
 524 extern bool suppress_extraneous_trailing_semicolon_warning;
 525
 526 extern bool suppress_multiple_mime_version_warning;
 527
 528 #define NPREFS  20
 529 typedef struct {
 530     char *type;
 531     char *subtype;
 532 } mime_type_subtype;
 533 extern mime_type_subtype mime_preference[NPREFS];
 534 extern int npreferred;