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