xpcom/io/nsStringStream.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 #ifndef nsStringStream_h__
   8 #define nsStringStream_h__
   9
  10 #include "nsIStringStream.h"
  11 #include "nsString.h"
  12 #include "nsTArray.h"
  13
  14 /**
  15  * Implements:
  16  *   nsIStringInputStream
  17  *   nsIInputStream
  18  *   nsISeekableStream
  19  *   nsITellableStream
  20  *   nsISupportsCString
  21  */
  22 #define NS_STRINGINPUTSTREAM_CONTRACTID "@mozilla.org/io/string-input-stream;1"
  23 #define NS_STRINGINPUTSTREAM_CID                     \
  24   { /* 0abb0835-5000-4790-af28-61b3ba17c295 */       \
  25     0x0abb0835, 0x5000, 0x4790, {                    \
  26       0xaf, 0x28, 0x61, 0xb3, 0xba, 0x17, 0xc2, 0x95 \
  27     }                                                \
  28   }
  29
  30 /**
  31  * An enumeration type used to represent a method of assignment.
  32  */
  33 enum nsAssignmentType {
  34   NS_ASSIGNMENT_COPY,    // copy by value
  35   NS_ASSIGNMENT_DEPEND,  // copy by reference
  36   NS_ASSIGNMENT_ADOPT    // copy by reference (take ownership of resource)
  37 };
  38
  39 /**
  40  * Factory method to get an nsInputStream from a byte buffer.  Result will
  41  * implement nsIStringInputStream, nsITellableStream and nsISeekableStream.
  42  *
  43  * If aAssignment is NS_ASSIGNMENT_COPY, then the resulting stream holds a copy
  44  * of the given buffer (aStringToRead), and the caller is free to discard
  45  * aStringToRead after this function returns.
  46  *
  47  * If aAssignment is NS_ASSIGNMENT_DEPEND, then the resulting stream refers
  48  * directly to the given buffer (aStringToRead), so the caller must ensure that
  49  * the buffer remains valid for the lifetime of the stream object.  Use with
  50  * care!!
  51  *
  52  * If aAssignment is NS_ASSIGNMENT_ADOPT, then the resulting stream refers
  53  * directly to the given buffer (aStringToRead) and will free aStringToRead
  54  * once the stream is closed.
  55  */
  56 extern nsresult NS_NewByteInputStream(nsIInputStream** aStreamResult,
  57                                       mozilla::Span<const char> aStringToRead,
  58                                       nsAssignmentType aAssignment);
  59
  60 /**
  61  * Factory method to get an nsIInputStream from an nsTArray representing a byte
  62  * buffer.  This will take ownership of the data and empty out the nsTArray.
  63  *
  64  * Result will implement nsIStringInputStream, nsITellableStream and
  65  * nsISeekableStream.
  66  */
  67 extern nsresult NS_NewByteInputStream(nsIInputStream** aStreamResult,
  68                                       nsTArray<uint8_t>&& aArray);
  69
  70 /**
  71  * Factory method to get an nsIInputStream from an arbitrary StreamBufferSource.
  72  * This will take a strong reference to the source.
  73  *
  74  * Result will implement nsIStringInputStream, nsITellableStream and
  75  * nsISeekableStream.
  76  */
  77 extern nsresult NS_NewByteInputStream(nsIInputStream** aStreamResult,
  78                                       mozilla::StreamBufferSource* aSource);
  79
  80 /**
  81  * Factory method to get an nsInputStream from an nsACString.  Result will
  82  * implement nsIStringInputStream, nsTellableStream and nsISeekableStream.
  83  */
  84 extern nsresult NS_NewCStringInputStream(nsIInputStream** aStreamResult,
  85                                          const nsACString& aStringToRead);
  86 extern nsresult NS_NewCStringInputStream(nsIInputStream** aStreamResult,
  87                                          nsCString&& aStringToRead);
  88
  89 #endif  // nsStringStream_h__