Back to index

lightning-sunbird  0.9+nobinonly
mimeobj.h
Go to the documentation of this file.
00001 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
00002 /* ***** BEGIN LICENSE BLOCK *****
00003  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
00004  *
00005  * The contents of this file are subject to the Mozilla Public License Version
00006  * 1.1 (the "License"); you may not use this file except in compliance with
00007  * the License. You may obtain a copy of the License at
00008  * http://www.mozilla.org/MPL/
00009  *
00010  * Software distributed under the License is distributed on an "AS IS" basis,
00011  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
00012  * for the specific language governing rights and limitations under the
00013  * License.
00014  *
00015  * The Original Code is mozilla.org code.
00016  *
00017  * The Initial Developer of the Original Code is
00018  * Netscape Communications Corporation.
00019  * Portions created by the Initial Developer are Copyright (C) 1998
00020  * the Initial Developer. All Rights Reserved.
00021  *
00022  * Contributor(s):
00023  *
00024  * Alternatively, the contents of this file may be used under the terms of
00025  * either of the GNU General Public License Version 2 or later (the "GPL"),
00026  * or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
00027  * in which case the provisions of the GPL or the LGPL are applicable instead
00028  * of those above. If you wish to allow use of your version of this file only
00029  * under the terms of either the GPL or the LGPL, and not to allow others to
00030  * use your version of this file under the terms of the MPL, indicate your
00031  * decision by deleting the provisions above and replace them with the notice
00032  * and other provisions required by the GPL or the LGPL. If you do not delete
00033  * the provisions above, a recipient may use your version of this file under
00034  * the terms of any one of the MPL, the GPL or the LGPL.
00035  *
00036  * ***** END LICENSE BLOCK ***** */
00037 
00038 #ifndef _MIMEOBJ_H_
00039 #define _MIMEOBJ_H_
00040 
00041 #include "mimei.h"
00042 #include "prio.h"
00043 /* MimeObject is the base-class for the objects representing all other 
00044    MIME types.  It provides several methods:
00045 
00046    int initialize (MimeObject *obj)
00047 
00048      This is called from mime_new() when a new instance is allocated.
00049      Subclasses should do whatever setup is necessary from this method,
00050      and should call the superclass's initialize method, unless there's
00051      a specific reason not to.
00052 
00053    void finalize (MimeObject *obj)
00054 
00055      This is called from mime_free() and should free all data associated
00056      with the object.  If the object points to other MIME objects, they
00057      should be finalized as well (by calling mime_free(), not by calling
00058      their finalize() methods directly.)
00059 
00060    int parse_buffer (const char *buf, PRInt32 size, MimeObject *obj)
00061 
00062      This is the method by which you feed arbitrary data into the parser
00063      for this object.  Most subclasses will probably inherit this method
00064      from the MimeObject base-class, which line-buffers the data and then
00065      hands it off to the parse_line() method.
00066 
00067         If this object uses a Content-Transfer-Encoding (base64, qp, uue)
00068         then the data may be decoded by parse_buffer() before parse_line()
00069         is called.  (The MimeLeaf class provides this functionality.)
00070 
00071    int parse_begin (MimeObject *obj)
00072      Called after `init' but before `parse_line' or `parse_buffer'.
00073         Can be used to initialize various parsing machinery.
00074 
00075    int parse_line (char *line, PRInt32 length, MimeObject *obj)
00076 
00077      This method is called (by parse_buffer()) for each complete line of
00078      data handed to the parser, and is the method which most subclasses
00079      will override to implement their parsers.
00080 
00081      When handing data off to a MIME object for parsing, one should always
00082      call the parse_buffer() method, and not call the parse_line() method
00083      directly, since the parse_buffer() method may do other transformations
00084      on the data (like base64 decoding.)
00085 
00086         One should generally not call parse_line() directly, since that could
00087         bypass decoding.  One should call parse_buffer() instead.
00088 
00089    int parse_eof (MimeObject *obj, PRBool abort_p)
00090 
00091      This is called when there is no more data to be handed to the object:
00092         when the parent object is done feeding data to an object being parsed.
00093         Implementors of this method should be sure to also call the parse_eof()
00094         methods of any sub-objects to which they have pointers.
00095 
00096      This is also called by the finalize() method, just before object 
00097      destruction, if it has not already been called.
00098 
00099      The `closed_p' instance variable is used to prevent multiple calls to
00100      `parse_eof'.
00101 
00102    int parse_end (MimeObject *obj)
00103      Called after `parse_eof' but before `finalize'.
00104         This can be used to free up any memory no longer needed now that parsing
00105         is done (to avoid surprises due to unexpected method combination, it's
00106         best to free things in this method in preference to `parse_eof'.)
00107         Implementors of this method should be sure to also call the parse_end()
00108         methods of any sub-objects to which they have pointers.
00109 
00110      This is also called by the finalize() method, just before object 
00111      destruction, if it has not already been called.
00112 
00113      The `parsed_p' instance variable is used to prevent multiple calls to
00114      `parse_end'.
00115 
00116 
00117    PRBool displayable_inline_p (MimeObjectClass *class, MimeHeaders *hdrs)
00118 
00119      This method should return true if this class of object will be displayed
00120      directly, as opposed to being displayed as a link.  This information is
00121      used by the "multipart/alternative" parser to decide which of its children
00122      is the ``best'' one to display.   Note that this is a class method, not
00123      an object method -- there is not yet an instance of this class at the time
00124      that it is called.  The `hdrs' provided are the headers of the object that
00125         might be instantiated -- from this, the method may extract additional
00126         infomation that it might need to make its decision.
00127  */
00128 
00129 
00130 /* this one is typdedef'ed in mimei.h, since it is the base-class. */
00131 struct MimeObjectClass {
00132 
00133   /* Note: the order of these first five slots is known by MimeDefClass().
00134         Technically, these are part of the object system, not the MIME code.
00135    */
00136   const char *class_name;
00137   int instance_size;
00138   struct MimeObjectClass *superclass;
00139   int (*class_initialize) (MimeObjectClass *clazz);
00140   PRBool class_initialized;
00141 
00142   /* These are the methods shared by all MIME objects.  See comment above.
00143    */
00144   int (*initialize) (MimeObject *obj);
00145   void (*finalize) (MimeObject *obj);
00146   int (*parse_begin) (MimeObject *obj);
00147   int (*parse_buffer) (const char *buf, PRInt32 size, MimeObject *obj);
00148   int (*parse_line) (char *line, PRInt32 length, MimeObject *obj);
00149   int (*parse_eof) (MimeObject *obj, PRBool abort_p);
00150   int (*parse_end) (MimeObject *obj, PRBool abort_p);
00151 
00152   PRBool (*displayable_inline_p) (MimeObjectClass *clazz, MimeHeaders *hdrs);
00153 
00154 #if defined(DEBUG) && defined(XP_UNIX)
00155   int (*debug_print) (MimeObject *obj, PRFileDesc *stream, PRInt32 depth);
00156 #endif
00157 };
00158 
00159 extern "C" MimeObjectClass mimeObjectClass;
00160 
00161 /* this one is typdedef'ed in mimei.h, since it is the base-class. */
00162 struct MimeObject {
00163   MimeObjectClass *clazz;   /* Pointer to class object, for `type-of' */
00164 
00165   MimeHeaders *headers;            /* The header data associated with this object;
00166                                                     this is where the content-type, disposition,
00167                                                     description, and other meta-data live.
00168 
00169                                                     For example, the outermost message/rfc822 object
00170                                                     would have NULL here (since it has no parent,
00171                                                     thus no headers to describe it.)  However, a
00172                                                     multipart/mixed object, which was the sole
00173                                                     child of that message/rfc822 object, would have
00174                                                     here a copy of the headers which began the
00175                                                     parent object (the headers which describe the
00176                                                     child.)
00177                                                   */
00178 
00179   char *content_type;              /* The MIME content-type and encoding.  */
00180   char *encoding;                  /* In most cases, these will be the same as the
00181                                                     values to be found in the `headers' object,
00182                                                     but in some cases, the values in these slots
00183                                                     will be more correct than the headers.
00184                                                   */
00185 
00186 
00187   MimeObject *parent;              /* Backpointer to a MimeContainer object. */
00188 
00189   MimeDisplayOptions *options;     /* Display preferences set by caller. */
00190 
00191   PRBool closed_p;                 /* Whether it's done being written to. */
00192   PRBool parsed_p;                 /* Whether the parser has been shut down. */
00193   PRBool output_p;                 /* Whether it should be written. */
00194   PRBool dontShowAsAttachment; /* Force an object to not be shown as attachment,
00195                                   but when is false, it doesn't mean it will be
00196                                   shown as attachment */
00197 
00198   /* Read-buffer and write-buffer (on input, `parse_buffer' uses ibuffer to
00199         compose calls to `parse_line'; on output, `obuffer' is used in various
00200         ways by various routines.)  These buffers are created and grow as needed.
00201         `ibuffer' should be generally be considered hands-off, and `obuffer'
00202         should generally be considered fair game.
00203    */
00204   char *ibuffer, *obuffer;
00205   PRInt32 ibuffer_size, obuffer_size;
00206   PRInt32 ibuffer_fp, obuffer_fp;
00207 };
00208 
00209 
00210 #define MimeObject_grow_obuffer(obj, desired_size) \
00211   (((desired_size) >= (obj)->obuffer_size) ? \
00212    mime_GrowBuffer ((PRUint32)(desired_size), (PRUint32)sizeof(char), 1024, \
00213                                &(obj)->obuffer, (PRInt32*)&(obj)->obuffer_size) \
00214    : 0)
00215 
00216 
00217 #endif /* _MIMEOBJ_H_ */