PageRenderTime 24ms CodeModel.GetById 14ms app.highlight 6ms RepoModel.GetById 2ms app.codeStats 0ms

/indra/llmessage/llmime.h

https://bitbucket.org/lindenlab/viewer-beta/
C++ Header | 292 lines | 42 code | 32 blank | 218 comment | 0 complexity | 2af9029a0cafac511180e435eee95b4e MD5 | raw file
  1/** 
  2 * @file llmime.h
  3 * @author Phoenix
  4 * @date 2006-12-20
  5 * @brief Declaration of mime tools.
  6 *
  7 * $LicenseInfo:firstyear=2006&license=viewerlgpl$
  8 * Second Life Viewer Source Code
  9 * Copyright (C) 2010, Linden Research, Inc.
 10 * 
 11 * This library is free software; you can redistribute it and/or
 12 * modify it under the terms of the GNU Lesser General Public
 13 * License as published by the Free Software Foundation;
 14 * version 2.1 of the License only.
 15 * 
 16 * This library is distributed in the hope that it will be useful,
 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 19 * Lesser General Public License for more details.
 20 * 
 21 * You should have received a copy of the GNU Lesser General Public
 22 * License along with this library; if not, write to the Free Software
 23 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 24 * 
 25 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 26 * $/LicenseInfo$
 27 */
 28
 29#ifndef LL_LLMIME_H
 30#define LL_LLMIME_H
 31
 32#include <string>
 33#include "llsd.h"
 34
 35/**
 36 * This file declares various tools for parsing and creating MIME
 37 * objects as described in RFCs 2045, 2046, 2047, 2048, and 2049.
 38 */
 39
 40/** 
 41 * @class LLMimeIndex
 42 * @brief Skeletal information useful for handling mime packages.
 43 * @see LLMimeParser
 44 *
 45 * An instance of this class is the parsed output from a LLMimeParser
 46 * which then allows for easy access into a data stream to find and
 47 * get what you want out of it.
 48 *
 49 * This class meant as a tool to quickly find what you seek in a
 50 * parsed mime entity. As such, it does not have useful support for
 51 * modification of a mime entity and specializes the interface toward
 52 * querying data from a fixed mime entity. Modifying an instance of
 53 * LLMimeIndx does not alter a mime entity and changes to a mime
 54 * entity itself are not propogated into an instance of a LLMimeIndex.
 55 *
 56 * Usage:<br>
 57 *  LLMimeIndex mime_index;<br>
 58 *  std::ifstream fstr("package.mime", ios::binary);<br>
 59 *  LLMimeParser parser;<br>
 60 *  if(parser.parseIndex(fstr, mime_index))<br>
 61 *  {<br>
 62 *    std::vector<U8> content;<br>
 63 *    content.resize(mime_index.contentLength());<br>
 64 *    fstr.seekg(mime_index.offset(), ios::beg);<br>
 65 *    // ...do work on fstr and content<br>
 66 *  }<br>
 67 */
 68class LLMimeIndex
 69{
 70public:
 71	/* @name Client interface.
 72	 */
 73	//@{
 74	/** 
 75	 * @brief Get the full parsed headers for this.
 76	 *
 77	 * If there are any headers, it will be a map of header name to
 78	 * the value found on the line. The name is everything before the
 79	 * colon, and the value is the string found after the colon to the
 80	 * end of the line after trimming leading whitespace. So, for
 81	 * example:
 82	 * Content-Type:  text/plain
 83	 * would become an entry in the headers of:
 84	 * headers["Content-Type"] == "text/plain"
 85	 *
 86	 * If this instance of an index was generated by the
 87	 * LLMimeParser::parseIndex() call, all header names in rfc2045
 88	 * will be capitalized as in rfc, eg Content-Length and
 89	 * MIME-Version, not content-length and mime-version.
 90	 * @return Returns an LLSD map of header name to value. Returns
 91	 * undef if there are no headers.
 92	 */
 93	LLSD headers() const;
 94
 95	/** 
 96	 * @brief Get the content offset.
 97	 *
 98	 * @return Returns the number of bytes to the start of the data
 99	 * segment from the start of serialized mime entity. Returns -1 if
100	 * offset is not known.
101	 */
102	S32 offset() const;
103
104	/** 
105	 * @brief Get the length of the data segment for this mime part.
106	 *
107	 * @return Returns the content length in bytes. Returns -1 if
108	 * length is not known.
109	 */
110	S32 contentLength() const;
111
112	/** 
113	 * @brief Get the mime type associated with this node.
114	 *
115	 * @return Returns the mimetype.
116	 */
117	std::string contentType() const;
118
119	/** 
120	 * @brief Helper method which simplifies parsing the return from type()
121	 *
122	 * @return Returns true if this is a multipart mime, and therefore
123	 * getting subparts will succeed.
124	 */
125	bool isMultipart() const;
126
127	/** 
128	 * @brief Get the number of atachments.
129	 *
130	 * @return Returns the number of sub-parts for this.
131	 */
132	S32 subPartCount() const;
133
134	/** 
135	 * @brief Get the indicated attachment.
136	 *
137	 * @param index Value from 0 to (subPartCount() - 1).
138	 * @return Returns the indicated sub-part, or an invalid mime
139	 * index on failure.
140	 */
141	LLMimeIndex subPart(S32 index) const;
142	//@}
143
144	/* @name Interface for building, testing, and helpers for typical use.
145	 */
146	//@{
147	/**
148	 * @brief Default constructor - creates a useless LLMimeIndex.
149	 */
150	LLMimeIndex();
151
152	/**
153	 * @brief Full constructor.
154	 *
155	 * @param headers The complete headers.
156	 * @param content_offset The number of bytes to the start of the
157	 * data segment of this mime entity from the start of the stream
158	 * or buffer.
159	 */
160	LLMimeIndex(LLSD headers, S32 content_offset);
161
162	/**
163	 * @brief Copy constructor.
164	 *
165	 * @param mime The other mime object.
166	 */
167	LLMimeIndex(const LLMimeIndex& mime);
168
169	// @brief Destructor.
170	~LLMimeIndex();
171
172	/*
173	 * @breif Assignment operator.
174	 *
175	 * @param mime The other mime object.
176	 * @return Returns this after assignment.
177	 */
178	LLMimeIndex& operator=(const LLMimeIndex& mime);
179
180	/** 
181	 * @brief Add attachment information as a sub-part to a multipart mime.
182	 *
183	 * @param sub_part the part to attach.
184	 * @return Returns true on success, false on failure.
185	 */
186	bool attachSubPart(LLMimeIndex sub_part);
187	//@}
188
189protected:
190	// Implementation.
191	class Impl;
192	Impl* mImpl;
193};
194
195
196/** 
197 * @class LLMimeParser
198 * @brief This class implements a MIME parser and verifier.
199 *
200 * THOROUGH_DESCRIPTION
201 */
202class LLMimeParser
203{
204public:
205	// @brief Make a new mime parser.
206	LLMimeParser();
207	
208	// @brief Mime parser Destructor.
209	~LLMimeParser();
210
211	// @brief Reset internal state of this parser.
212	void reset();
213
214	
215	/* @name Index generation interface.
216	 */
217	//@{
218	/** 
219	 * @brief Parse a stream to find the mime index information.
220	 *
221	 * This method will scan the istr until a single complete mime
222	 * entity is read or EOF. The istr will be modified by this
223	 * parsing, so pass in a temporary stream or rewind/reset the
224	 * stream after this call.
225	 * @param istr An istream which contains a mime entity.
226	 * @param index[out] The parsed output.
227	 * @return Returns true if an index was parsed and no errors occurred.
228	 */
229	bool parseIndex(std::istream& istr, LLMimeIndex& index);
230
231	/** 
232	 * @brief Parse a vector to find the mime index information.
233	 *
234	 * @param buffer A vector with data to parse.
235	 * @param index[out] The parsed output.
236	 * @return Returns true if an index was parsed and no errors occurred.
237	 */
238	bool parseIndex(const std::vector<U8>& buffer, LLMimeIndex& index);
239
240	/** 
241	 * @brief Parse a stream to find the mime index information.
242	 *
243	 * This method will scan the istr until a single complete mime
244	 * entity is read, an EOF, or limit bytes have been scanned. The
245	 * istr will be modified by this parsing, so pass in a temporary
246	 * stream or rewind/reset the stream after this call.
247	 * @param istr An istream which contains a mime entity.
248	 * @param limit The maximum number of bytes to scan.
249	 * @param index[out] The parsed output.
250	 * @return Returns true if an index was parsed and no errors occurred.
251	 */
252	bool parseIndex(std::istream& istr, S32 limit, LLMimeIndex& index);
253
254	/** 
255	 * @brief Parse a memory bufffer to find the mime index information.
256	 *
257	 * @param buffer The start of the buffer to parse.
258	 * @param buffer_length The length of the buffer.
259	 * @param index[out] The parsed output.
260	 * @return Returns true if an index was parsed and no errors occurred.
261	 */
262	bool parseIndex(const U8* buffer, S32 buffer_length, LLMimeIndex& index);
263	//@}
264
265	/** 
266	 * @brief 
267	 *
268	 * @return
269	 */
270	//bool verify(std::istream& istr, LLMimeIndex& index) const;
271
272	/** 
273	 * @brief 
274	 *
275	 * @return
276	 */
277	//bool verify(U8* buffer, S32 buffer_length, LLMimeIndex& index) const;
278
279protected:
280	// Implementation.
281	class Impl;
282	Impl& mImpl;
283
284private:
285	// @brief Not implemneted to prevent copy consturction.
286	LLMimeParser(const LLMimeParser& parser);
287
288	// @brief Not implemneted to prevent assignment.
289	LLMimeParser& operator=(const LLMimeParser& mime);
290};
291
292#endif // LL_LLMIME_H