299 lines
8.4 KiB
C++
299 lines
8.4 KiB
C++
/**
|
|
* @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
|