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