PageRenderTime 27ms CodeModel.GetById 14ms RepoModel.GetById 1ms 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
Possible License(s): LGPL-2.1
  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. #ifndef LL_LLMIME_H
  29. #define LL_LLMIME_H
  30. #include <string>
  31. #include "llsd.h"
  32. /**
  33. * This file declares various tools for parsing and creating MIME
  34. * objects as described in RFCs 2045, 2046, 2047, 2048, and 2049.
  35. */
  36. /**
  37. * @class LLMimeIndex
  38. * @brief Skeletal information useful for handling mime packages.
  39. * @see LLMimeParser
  40. *
  41. * An instance of this class is the parsed output from a LLMimeParser
  42. * which then allows for easy access into a data stream to find and
  43. * get what you want out of it.
  44. *
  45. * This class meant as a tool to quickly find what you seek in a
  46. * parsed mime entity. As such, it does not have useful support for
  47. * modification of a mime entity and specializes the interface toward
  48. * querying data from a fixed mime entity. Modifying an instance of
  49. * LLMimeIndx does not alter a mime entity and changes to a mime
  50. * entity itself are not propogated into an instance of a LLMimeIndex.
  51. *
  52. * Usage:<br>
  53. * LLMimeIndex mime_index;<br>
  54. * std::ifstream fstr("package.mime", ios::binary);<br>
  55. * LLMimeParser parser;<br>
  56. * if(parser.parseIndex(fstr, mime_index))<br>
  57. * {<br>
  58. * std::vector<U8> content;<br>
  59. * content.resize(mime_index.contentLength());<br>
  60. * fstr.seekg(mime_index.offset(), ios::beg);<br>
  61. * // ...do work on fstr and content<br>
  62. * }<br>
  63. */
  64. class LLMimeIndex
  65. {
  66. public:
  67. /* @name Client interface.
  68. */
  69. //@{
  70. /**
  71. * @brief Get the full parsed headers for this.
  72. *
  73. * If there are any headers, it will be a map of header name to
  74. * the value found on the line. The name is everything before the
  75. * colon, and the value is the string found after the colon to the
  76. * end of the line after trimming leading whitespace. So, for
  77. * example:
  78. * Content-Type: text/plain
  79. * would become an entry in the headers of:
  80. * headers["Content-Type"] == "text/plain"
  81. *
  82. * If this instance of an index was generated by the
  83. * LLMimeParser::parseIndex() call, all header names in rfc2045
  84. * will be capitalized as in rfc, eg Content-Length and
  85. * MIME-Version, not content-length and mime-version.
  86. * @return Returns an LLSD map of header name to value. Returns
  87. * undef if there are no headers.
  88. */
  89. LLSD headers() const;
  90. /**
  91. * @brief Get the content offset.
  92. *
  93. * @return Returns the number of bytes to the start of the data
  94. * segment from the start of serialized mime entity. Returns -1 if
  95. * offset is not known.
  96. */
  97. S32 offset() const;
  98. /**
  99. * @brief Get the length of the data segment for this mime part.
  100. *
  101. * @return Returns the content length in bytes. Returns -1 if
  102. * length is not known.
  103. */
  104. S32 contentLength() const;
  105. /**
  106. * @brief Get the mime type associated with this node.
  107. *
  108. * @return Returns the mimetype.
  109. */
  110. std::string contentType() const;
  111. /**
  112. * @brief Helper method which simplifies parsing the return from type()
  113. *
  114. * @return Returns true if this is a multipart mime, and therefore
  115. * getting subparts will succeed.
  116. */
  117. bool isMultipart() const;
  118. /**
  119. * @brief Get the number of atachments.
  120. *
  121. * @return Returns the number of sub-parts for this.
  122. */
  123. S32 subPartCount() const;
  124. /**
  125. * @brief Get the indicated attachment.
  126. *
  127. * @param index Value from 0 to (subPartCount() - 1).
  128. * @return Returns the indicated sub-part, or an invalid mime
  129. * index on failure.
  130. */
  131. LLMimeIndex subPart(S32 index) const;
  132. //@}
  133. /* @name Interface for building, testing, and helpers for typical use.
  134. */
  135. //@{
  136. /**
  137. * @brief Default constructor - creates a useless LLMimeIndex.
  138. */
  139. LLMimeIndex();
  140. /**
  141. * @brief Full constructor.
  142. *
  143. * @param headers The complete headers.
  144. * @param content_offset The number of bytes to the start of the
  145. * data segment of this mime entity from the start of the stream
  146. * or buffer.
  147. */
  148. LLMimeIndex(LLSD headers, S32 content_offset);
  149. /**
  150. * @brief Copy constructor.
  151. *
  152. * @param mime The other mime object.
  153. */
  154. LLMimeIndex(const LLMimeIndex& mime);
  155. // @brief Destructor.
  156. ~LLMimeIndex();
  157. /*
  158. * @breif Assignment operator.
  159. *
  160. * @param mime The other mime object.
  161. * @return Returns this after assignment.
  162. */
  163. LLMimeIndex& operator=(const LLMimeIndex& mime);
  164. /**
  165. * @brief Add attachment information as a sub-part to a multipart mime.
  166. *
  167. * @param sub_part the part to attach.
  168. * @return Returns true on success, false on failure.
  169. */
  170. bool attachSubPart(LLMimeIndex sub_part);
  171. //@}
  172. protected:
  173. // Implementation.
  174. class Impl;
  175. Impl* mImpl;
  176. };
  177. /**
  178. * @class LLMimeParser
  179. * @brief This class implements a MIME parser and verifier.
  180. *
  181. * THOROUGH_DESCRIPTION
  182. */
  183. class LLMimeParser
  184. {
  185. public:
  186. // @brief Make a new mime parser.
  187. LLMimeParser();
  188. // @brief Mime parser Destructor.
  189. ~LLMimeParser();
  190. // @brief Reset internal state of this parser.
  191. void reset();
  192. /* @name Index generation interface.
  193. */
  194. //@{
  195. /**
  196. * @brief Parse a stream to find the mime index information.
  197. *
  198. * This method will scan the istr until a single complete mime
  199. * entity is read or EOF. The istr will be modified by this
  200. * parsing, so pass in a temporary stream or rewind/reset the
  201. * stream after this call.
  202. * @param istr An istream which contains a mime entity.
  203. * @param index[out] The parsed output.
  204. * @return Returns true if an index was parsed and no errors occurred.
  205. */
  206. bool parseIndex(std::istream& istr, LLMimeIndex& index);
  207. /**
  208. * @brief Parse a vector to find the mime index information.
  209. *
  210. * @param buffer A vector with data to parse.
  211. * @param index[out] The parsed output.
  212. * @return Returns true if an index was parsed and no errors occurred.
  213. */
  214. bool parseIndex(const std::vector<U8>& buffer, LLMimeIndex& index);
  215. /**
  216. * @brief Parse a stream to find the mime index information.
  217. *
  218. * This method will scan the istr until a single complete mime
  219. * entity is read, an EOF, or limit bytes have been scanned. The
  220. * istr will be modified by this parsing, so pass in a temporary
  221. * stream or rewind/reset the stream after this call.
  222. * @param istr An istream which contains a mime entity.
  223. * @param limit The maximum number of bytes to scan.
  224. * @param index[out] The parsed output.
  225. * @return Returns true if an index was parsed and no errors occurred.
  226. */
  227. bool parseIndex(std::istream& istr, S32 limit, LLMimeIndex& index);
  228. /**
  229. * @brief Parse a memory bufffer to find the mime index information.
  230. *
  231. * @param buffer The start of the buffer to parse.
  232. * @param buffer_length The length of the buffer.
  233. * @param index[out] The parsed output.
  234. * @return Returns true if an index was parsed and no errors occurred.
  235. */
  236. bool parseIndex(const U8* buffer, S32 buffer_length, LLMimeIndex& index);
  237. //@}
  238. /**
  239. * @brief
  240. *
  241. * @return
  242. */
  243. //bool verify(std::istream& istr, LLMimeIndex& index) const;
  244. /**
  245. * @brief
  246. *
  247. * @return
  248. */
  249. //bool verify(U8* buffer, S32 buffer_length, LLMimeIndex& index) const;
  250. protected:
  251. // Implementation.
  252. class Impl;
  253. Impl& mImpl;
  254. private:
  255. // @brief Not implemneted to prevent copy consturction.
  256. LLMimeParser(const LLMimeParser& parser);
  257. // @brief Not implemneted to prevent assignment.
  258. LLMimeParser& operator=(const LLMimeParser& mime);
  259. };
  260. #endif // LL_LLMIME_H