Imported existing code

indra/llmessage/llmime.h

@@ -0,0 +1,298 @@
+/** 
+ * @file llmime.h
+ * @author Phoenix
+ * @date 2006-12-20
+ * @brief Declaration of mime tools.
+ *
+ * $LicenseInfo:firstyear=2006&license=viewergpl$
+ * 
+ * Copyright (c) 2006-2009, Linden Research, Inc.
+ * 
+ * Second Life Viewer Source Code
+ * The source code in this file ("Source Code") is provided by Linden Lab
+ * to you under the terms of the GNU General Public License, version 2.0
+ * ("GPL"), unless you have obtained a separate licensing agreement
+ * ("Other License"), formally executed by you and Linden Lab.  Terms of
+ * the GPL can be found in doc/GPL-license.txt in this distribution, or
+ * online at http://secondlifegrid.net/programs/open_source/licensing/gplv2
+ * 
+ * There are special exceptions to the terms and conditions of the GPL as
+ * it is applied to this Source Code. View the full text of the exception
+ * in the file doc/FLOSS-exception.txt in this software distribution, or
+ * online at
+ * http://secondlifegrid.net/programs/open_source/licensing/flossexception
+ * 
+ * By copying, modifying or distributing this software, you acknowledge
+ * that you have read and understood your obligations described above,
+ * and agree to abide by those obligations.
+ * 
+ * ALL LINDEN LAB SOURCE CODE IS PROVIDED "AS IS." LINDEN LAB MAKES NO
+ * WARRANTIES, EXPRESS, IMPLIED OR OTHERWISE, REGARDING ITS ACCURACY,
+ * COMPLETENESS OR PERFORMANCE.
+ * $/LicenseInfo$
+ */
+
+#ifndef LL_LLMIME_H
+#define LL_LLMIME_H
+
+#include <string>
+#include "llsd.h"
+
+/**
+ * This file declares various tools for parsing and creating MIME
+ * objects as described in RFCs 2045, 2046, 2047, 2048, and 2049.
+ */
+
+/** 
+ * @class LLMimeIndex
+ * @brief Skeletal information useful for handling mime packages.
+ * @see LLMimeParser
+ *
+ * An instance of this class is the parsed output from a LLMimeParser
+ * which then allows for easy access into a data stream to find and
+ * get what you want out of it.
+ *
+ * This class meant as a tool to quickly find what you seek in a
+ * parsed mime entity. As such, it does not have useful support for
+ * modification of a mime entity and specializes the interface toward
+ * querying data from a fixed mime entity. Modifying an instance of
+ * LLMimeIndx does not alter a mime entity and changes to a mime
+ * entity itself are not propogated into an instance of a LLMimeIndex.
+ *
+ * Usage:<br>
+ *  LLMimeIndex mime_index;<br>
+ *  std::ifstream fstr("package.mime", ios::binary);<br>
+ *  LLMimeParser parser;<br>
+ *  if(parser.parseIndex(fstr, mime_index))<br>
+ *  {<br>
+ *    std::vector<U8> content;<br>
+ *    content.resize(mime_index.contentLength());<br>
+ *    fstr.seekg(mime_index.offset(), ios::beg);<br>
+ *    // ...do work on fstr and content<br>
+ *  }<br>
+ */
+class LLMimeIndex
+{
+public:
+	/* @name Client interface.
+	 */
+	//@{
+	/** 
+	 * @brief Get the full parsed headers for this.
+	 *
+	 * If there are any headers, it will be a map of header name to
+	 * the value found on the line. The name is everything before the
+	 * colon, and the value is the string found after the colon to the
+	 * end of the line after trimming leading whitespace. So, for
+	 * example:
+	 * Content-Type:  text/plain
+	 * would become an entry in the headers of:
+	 * headers["Content-Type"] == "text/plain"
+	 *
+	 * If this instance of an index was generated by the
+	 * LLMimeParser::parseIndex() call, all header names in rfc2045
+	 * will be capitalized as in rfc, eg Content-Length and
+	 * MIME-Version, not content-length and mime-version.
+	 * @return Returns an LLSD map of header name to value. Returns
+	 * undef if there are no headers.
+	 */
+	LLSD headers() const;
+
+	/** 
+	 * @brief Get the content offset.
+	 *
+	 * @return Returns the number of bytes to the start of the data
+	 * segment from the start of serialized mime entity. Returns -1 if
+	 * offset is not known.
+	 */
+	S32 offset() const;
+
+	/** 
+	 * @brief Get the length of the data segment for this mime part.
+	 *
+	 * @return Returns the content length in bytes. Returns -1 if
+	 * length is not known.
+	 */
+	S32 contentLength() const;
+
+	/** 
+	 * @brief Get the mime type associated with this node.
+	 *
+	 * @return Returns the mimetype.
+	 */
+	std::string contentType() const;
+
+	/** 
+	 * @brief Helper method which simplifies parsing the return from type()
+	 *
+	 * @return Returns true if this is a multipart mime, and therefore
+	 * getting subparts will succeed.
+	 */
+	bool isMultipart() const;
+
+	/** 
+	 * @brief Get the number of atachments.
+	 *
+	 * @return Returns the number of sub-parts for this.
+	 */
+	S32 subPartCount() const;
+
+	/** 
+	 * @brief Get the indicated attachment.
+	 *
+	 * @param index Value from 0 to (subPartCount() - 1).
+	 * @return Returns the indicated sub-part, or an invalid mime
+	 * index on failure.
+	 */
+	LLMimeIndex subPart(S32 index) const;
+	//@}
+
+	/* @name Interface for building, testing, and helpers for typical use.
+	 */
+	//@{
+	/**
+	 * @brief Default constructor - creates a useless LLMimeIndex.
+	 */
+	LLMimeIndex();
+
+	/**
+	 * @brief Full constructor.
+	 *
+	 * @param headers The complete headers.
+	 * @param content_offset The number of bytes to the start of the
+	 * data segment of this mime entity from the start of the stream
+	 * or buffer.
+	 */
+	LLMimeIndex(LLSD headers, S32 content_offset);
+
+	/**
+	 * @brief Copy constructor.
+	 *
+	 * @param mime The other mime object.
+	 */
+	LLMimeIndex(const LLMimeIndex& mime);
+
+	// @brief Destructor.
+	~LLMimeIndex();
+
+	/*
+	 * @breif Assignment operator.
+	 *
+	 * @param mime The other mime object.
+	 * @return Returns this after assignment.
+	 */
+	LLMimeIndex& operator=(const LLMimeIndex& mime);
+
+	/** 
+	 * @brief Add attachment information as a sub-part to a multipart mime.
+	 *
+	 * @param sub_part the part to attach.
+	 * @return Returns true on success, false on failure.
+	 */
+	bool attachSubPart(LLMimeIndex sub_part);
+	//@}
+
+protected:
+	// Implementation.
+	class Impl;
+	Impl* mImpl;
+};
+
+
+/** 
+ * @class LLMimeParser
+ * @brief This class implements a MIME parser and verifier.
+ *
+ * THOROUGH_DESCRIPTION
+ */
+class LLMimeParser
+{
+public:
+	// @brief Make a new mime parser.
+	LLMimeParser();
+	
+	// @brief Mime parser Destructor.
+	~LLMimeParser();
+
+	// @brief Reset internal state of this parser.
+	void reset();
+
+	
+	/* @name Index generation interface.
+	 */
+	//@{
+	/** 
+	 * @brief Parse a stream to find the mime index information.
+	 *
+	 * This method will scan the istr until a single complete mime
+	 * entity is read or EOF. The istr will be modified by this
+	 * parsing, so pass in a temporary stream or rewind/reset the
+	 * stream after this call.
+	 * @param istr An istream which contains a mime entity.
+	 * @param index[out] The parsed output.
+	 * @return Returns true if an index was parsed and no errors occurred.
+	 */
+	bool parseIndex(std::istream& istr, LLMimeIndex& index);
+
+	/** 
+	 * @brief Parse a vector to find the mime index information.
+	 *
+	 * @param buffer A vector with data to parse.
+	 * @param index[out] The parsed output.
+	 * @return Returns true if an index was parsed and no errors occurred.
+	 */
+	bool parseIndex(const std::vector<U8>& buffer, LLMimeIndex& index);
+
+	/** 
+	 * @brief Parse a stream to find the mime index information.
+	 *
+	 * This method will scan the istr until a single complete mime
+	 * entity is read, an EOF, or limit bytes have been scanned. The
+	 * istr will be modified by this parsing, so pass in a temporary
+	 * stream or rewind/reset the stream after this call.
+	 * @param istr An istream which contains a mime entity.
+	 * @param limit The maximum number of bytes to scan.
+	 * @param index[out] The parsed output.
+	 * @return Returns true if an index was parsed and no errors occurred.
+	 */
+	bool parseIndex(std::istream& istr, S32 limit, LLMimeIndex& index);
+
+	/** 
+	 * @brief Parse a memory bufffer to find the mime index information.
+	 *
+	 * @param buffer The start of the buffer to parse.
+	 * @param buffer_length The length of the buffer.
+	 * @param index[out] The parsed output.
+	 * @return Returns true if an index was parsed and no errors occurred.
+	 */
+	bool parseIndex(const U8* buffer, S32 buffer_length, LLMimeIndex& index);
+	//@}
+
+	/** 
+	 * @brief 
+	 *
+	 * @return
+	 */
+	//bool verify(std::istream& istr, LLMimeIndex& index) const;
+
+	/** 
+	 * @brief 
+	 *
+	 * @return
+	 */
+	//bool verify(U8* buffer, S32 buffer_length, LLMimeIndex& index) const;
+
+protected:
+	// Implementation.
+	class Impl;
+	Impl& mImpl;
+
+private:
+	// @brief Not implemneted to prevent copy consturction.
+	LLMimeParser(const LLMimeParser& parser);
+
+	// @brief Not implemneted to prevent assignment.
+	LLMimeParser& operator=(const LLMimeParser& mime);
+};
+
+#endif // LL_LLMIME_H