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

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