home *** CD-ROM | disk | FTP | other *** search
/ Tools / WinSN5.0Ver.iso / NETSCAP.50 / WIN1998.ZIP / ns / lib / libmime / mimeobj.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-04-08  |  8.1 KB  |  201 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * The contents of this file are subject to the Netscape Public License
  4.  * Version 1.0 (the "NPL"); you may not use this file except in
  5.  * compliance with the NPL.  You may obtain a copy of the NPL at
  6.  * http://www.mozilla.org/NPL/
  7.  *
  8.  * Software distributed under the NPL is distributed on an "AS IS" basis,
  9.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
  10.  * for the specific language governing rights and limitations under the
  11.  * NPL.
  12.  *
  13.  * The Initial Developer of this code under the NPL is Netscape
  14.  * Communications Corporation.  Portions created by Netscape are
  15.  * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
  16.  * Reserved.
  17.  */
  18.  
  19. /* mimeobj.h --- definition of the MimeObject class (see mimei.h)
  20.    Created: Jamie Zawinski <jwz@netscape.com>, 15-May-96.
  21.  */
  22.  
  23. #ifndef _MIMEOBJ_H_
  24. #define _MIMEOBJ_H_
  25.  
  26. #include "mimei.h"
  27.  
  28. /* MimeObject is the base-class for the objects representing all other 
  29.    MIME types.  It provides several methods:
  30.  
  31.    int initialize (MimeObject *obj)
  32.  
  33.      This is called from mime_new() when a new instance is allocated.
  34.      Subclasses should do whatever setup is necessary from this method,
  35.      and should call the superclass's initialize method, unless there's
  36.      a specific reason not to.
  37.  
  38.    void finalize (MimeObject *obj)
  39.  
  40.      This is called from mime_free() and should free all data associated
  41.      with the object.  If the object points to other MIME objects, they
  42.      should be finalized as well (by calling mime_free(), not by calling
  43.      their finalize() methods directly.)
  44.  
  45.    int parse_buffer (char *buf, int32 size, MimeObject *obj)
  46.  
  47.      This is the method by which you feed arbitrary data into the parser
  48.      for this object.  Most subclasses will probably inherit this method
  49.      from the MimeObject base-class, which line-buffers the data and then
  50.      hands it off to the parse_line() method.
  51.  
  52.      If this object uses a Content-Transfer-Encoding (base64, qp, uue)
  53.      then the data may be decoded by parse_buffer() before parse_line()
  54.      is called.  (The MimeLeaf class provides this functionality.)
  55.  
  56.    int parse_begin (MimeObject *obj)
  57.      Called after `init' but before `parse_line' or `parse_buffer'.
  58.      Can be used to initialize various parsing machinery.
  59.  
  60.    int parse_line (char *line, int32 length, MimeObject *obj)
  61.  
  62.      This method is called (by parse_buffer()) for each complete line of
  63.      data handed to the parser, and is the method which most subclasses
  64.      will override to implement their parsers.
  65.  
  66.      When handing data off to a MIME object for parsing, one should always
  67.      call the parse_buffer() method, and not call the parse_line() method
  68.      directly, since the parse_buffer() method may do other transformations
  69.      on the data (like base64 decoding.)
  70.  
  71.      One should generally not call parse_line() directly, since that could
  72.      bypass decoding.  One should call parse_buffer() instead.
  73.  
  74.    int parse_eof (MimeObject *obj, XP_Bool abort_p)
  75.  
  76.      This is called when there is no more data to be handed to the object:
  77.      when the parent object is done feeding data to an object being parsed.
  78.      Implementors of this method should be sure to also call the parse_eof()
  79.      methods of any sub-objects to which they have pointers.
  80.  
  81.      This is also called by the finalize() method, just before object 
  82.      destruction, if it has not already been called.
  83.  
  84.      The `closed_p' instance variable is used to prevent multiple calls to
  85.      `parse_eof'.
  86.  
  87.    int parse_end (MimeObject *obj)
  88.      Called after `parse_eof' but before `finalize'.
  89.      This can be used to free up any memory no longer needed now that parsing
  90.      is done (to avoid surprises due to unexpected method combination, it's
  91.      best to free things in this method in preference to `parse_eof'.)
  92.      Implementors of this method should be sure to also call the parse_end()
  93.      methods of any sub-objects to which they have pointers.
  94.  
  95.      This is also called by the finalize() method, just before object 
  96.      destruction, if it has not already been called.
  97.  
  98.      The `parsed_p' instance variable is used to prevent multiple calls to
  99.      `parse_end'.
  100.  
  101.  
  102.    XP_Bool displayable_inline_p (MimeObjectClass *class, MimeHeaders *hdrs)
  103.  
  104.      This method should return true if this class of object will be displayed
  105.      directly, as opposed to being displayed as a link.  This information is
  106.      used by the "multipart/alternative" parser to decide which of its children
  107.      is the ``best'' one to display.   Note that this is a class method, not
  108.      an object method -- there is not yet an instance of this class at the time
  109.      that it is called.  The `hdrs' provided are the headers of the object that
  110.      might be instantiated -- from this, the method may extract additional
  111.      infomation that it might need to make its decision.
  112.  */
  113.  
  114.  
  115. /* this one is typdedef'ed in mimei.h, since it is the base-class. */
  116. struct MimeObjectClass {
  117.  
  118.   /* Note: the order of these first five slots is known by MimeDefClass().
  119.      Technically, these are part of the object system, not the MIME code.
  120.    */
  121.   const char *class_name;
  122.   int instance_size;
  123.   struct MimeObjectClass *superclass;
  124.   int (*class_initialize) (MimeObjectClass *class);
  125.   XP_Bool class_initialized;
  126.   XP_Bool showAttachmentIcon;
  127.  
  128.   /* These are the methods shared by all MIME objects.  See comment above.
  129.    */
  130.   int (*initialize) (MimeObject *obj);
  131.   void (*finalize) (MimeObject *obj);
  132.   int (*parse_begin) (MimeObject *obj);
  133.   int (*parse_buffer) (char *buf, int32 size, MimeObject *obj);
  134.   int (*parse_line) (char *line, int32 length, MimeObject *obj);
  135.   int (*parse_eof) (MimeObject *obj, XP_Bool abort_p);
  136.   int (*parse_end) (MimeObject *obj, XP_Bool abort_p);
  137.  
  138.   XP_Bool (*displayable_inline_p) (MimeObjectClass *class, MimeHeaders *hdrs);
  139.  
  140. #if defined(DEBUG) && defined(XP_UNIX)
  141.   int (*debug_print) (MimeObject *obj, FILE *stream, int32 depth);
  142. #endif
  143. };
  144.  
  145. extern MimeObjectClass mimeObjectClass;
  146.  
  147. /* this one is typdedef'ed in mimei.h, since it is the base-class. */
  148. struct MimeObject {
  149.   MimeObjectClass *class;    /* Pointer to class object, for `type-of' */
  150.  
  151.   MimeHeaders *headers;        /* The header data associated with this object;
  152.                                this is where the content-type, disposition,
  153.                                description, and other meta-data live.
  154.  
  155.                                For example, the outermost message/rfc822 object
  156.                                would have NULL here (since it has no parent,
  157.                                thus no headers to describe it.)  However, a
  158.                                multipart/mixed object, which was the sole
  159.                                child of that message/rfc822 object, would have
  160.                                here a copy of the headers which began the
  161.                                parent object (the headers which describe the
  162.                                child.)
  163.                              */
  164.  
  165.   char *content_type;        /* The MIME content-type and encoding.  */
  166.   char *encoding;            /* In most cases, these will be the same as the
  167.                                values to be found in the `headers' object,
  168.                                but in some cases, the values in these slots
  169.                                will be more correct than the headers.
  170.                              */
  171.  
  172.  
  173.   MimeObject *parent;        /* Backpointer to a MimeContainer object. */
  174.  
  175.   MimeDisplayOptions *options;    /* Display preferences set by caller. */
  176.  
  177.   XP_Bool closed_p;            /* Whether it's done being written to. */
  178.   XP_Bool parsed_p;            /* Whether the parser has been shut down. */
  179.   XP_Bool output_p;            /* Whether it should be written. */
  180.  
  181.   /* Read-buffer and write-buffer (on input, `parse_buffer' uses ibuffer to
  182.      compose calls to `parse_line'; on output, `obuffer' is used in various
  183.      ways by various routines.)  These buffers are created and grow as needed.
  184.      `ibuffer' should be generally be considered hands-off, and `obuffer'
  185.      should generally be considered fair game.
  186.    */
  187.   char *ibuffer, *obuffer;
  188.   int32 ibuffer_size, obuffer_size;
  189.   int32 ibuffer_fp, obuffer_fp;
  190. };
  191.  
  192.  
  193. #define MimeObject_grow_obuffer(obj, desired_size) \
  194.   (((desired_size) >= (obj)->obuffer_size) ? \
  195.    msg_GrowBuffer ((desired_size), sizeof(char), 1024, \
  196.                    &(obj)->obuffer, &(obj)->obuffer_size) \
  197.    : 0)
  198.  
  199.  
  200. #endif /* _MIMEOBJ_H_ */
  201.