GPBCodedInputStream.h 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253
  1. // Protocol Buffers - Google's data interchange format
  2. // Copyright 2008 Google Inc. All rights reserved.
  3. // https://developers.google.com/protocol-buffers/
  4. //
  5. // Redistribution and use in source and binary forms, with or without
  6. // modification, are permitted provided that the following conditions are
  7. // met:
  8. //
  9. // * Redistributions of source code must retain the above copyright
  10. // notice, this list of conditions and the following disclaimer.
  11. // * Redistributions in binary form must reproduce the above
  12. // copyright notice, this list of conditions and the following disclaimer
  13. // in the documentation and/or other materials provided with the
  14. // distribution.
  15. // * Neither the name of Google Inc. nor the names of its
  16. // contributors may be used to endorse or promote products derived from
  17. // this software without specific prior written permission.
  18. //
  19. // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20. // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21. // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22. // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23. // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24. // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25. // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26. // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27. // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28. // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29. // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30. #import <Foundation/Foundation.h>
  31. @class GPBMessage;
  32. @class GPBExtensionRegistry;
  33. NS_ASSUME_NONNULL_BEGIN
  34. CF_EXTERN_C_BEGIN
  35. /**
  36. * @c GPBCodedInputStream exception name. Exceptions raised from
  37. * @c GPBCodedInputStream contain an underlying error in the userInfo dictionary
  38. * under the GPBCodedInputStreamUnderlyingErrorKey key.
  39. **/
  40. extern NSString *const GPBCodedInputStreamException;
  41. /** The key under which the underlying NSError from the exception is stored. */
  42. extern NSString *const GPBCodedInputStreamUnderlyingErrorKey;
  43. /** NSError domain used for @c GPBCodedInputStream errors. */
  44. extern NSString *const GPBCodedInputStreamErrorDomain;
  45. /**
  46. * Error code for NSError with @c GPBCodedInputStreamErrorDomain.
  47. **/
  48. typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) {
  49. /** The size does not fit in the remaining bytes to be read. */
  50. GPBCodedInputStreamErrorInvalidSize = -100,
  51. /** Attempted to read beyond the subsection limit. */
  52. GPBCodedInputStreamErrorSubsectionLimitReached = -101,
  53. /** The requested subsection limit is invalid. */
  54. GPBCodedInputStreamErrorInvalidSubsectionLimit = -102,
  55. /** Invalid tag read. */
  56. GPBCodedInputStreamErrorInvalidTag = -103,
  57. /** Invalid UTF-8 character in a string. */
  58. GPBCodedInputStreamErrorInvalidUTF8 = -104,
  59. /** Invalid VarInt read. */
  60. GPBCodedInputStreamErrorInvalidVarInt = -105,
  61. /** The maximum recursion depth of messages was exceeded. */
  62. GPBCodedInputStreamErrorRecursionDepthExceeded = -106,
  63. };
  64. CF_EXTERN_C_END
  65. /**
  66. * Reads and decodes protocol message fields.
  67. *
  68. * The common uses of protocol buffers shouldn't need to use this class.
  69. * @c GPBMessage's provide a @c +parseFromData:error: and
  70. * @c +parseFromData:extensionRegistry:error: method that will decode a
  71. * message for you.
  72. *
  73. * @note Subclassing of @c GPBCodedInputStream is NOT supported.
  74. **/
  75. @interface GPBCodedInputStream : NSObject
  76. /**
  77. * Creates a new stream wrapping some data.
  78. *
  79. * @param data The data to wrap inside the stream.
  80. *
  81. * @return A newly instanced GPBCodedInputStream.
  82. **/
  83. + (instancetype)streamWithData:(NSData *)data;
  84. /**
  85. * Initializes a stream wrapping some data.
  86. *
  87. * @param data The data to wrap inside the stream.
  88. *
  89. * @return A newly initialized GPBCodedInputStream.
  90. **/
  91. - (instancetype)initWithData:(NSData *)data;
  92. /**
  93. * Attempts to read a field tag, returning zero if we have reached EOF.
  94. * Protocol message parsers use this to read tags, since a protocol message
  95. * may legally end wherever a tag occurs, and zero is not a valid tag number.
  96. *
  97. * @return The field tag, or zero if EOF was reached.
  98. **/
  99. - (int32_t)readTag;
  100. /**
  101. * @return A double read from the stream.
  102. **/
  103. - (double)readDouble;
  104. /**
  105. * @return A float read from the stream.
  106. **/
  107. - (float)readFloat;
  108. /**
  109. * @return A uint64 read from the stream.
  110. **/
  111. - (uint64_t)readUInt64;
  112. /**
  113. * @return A uint32 read from the stream.
  114. **/
  115. - (uint32_t)readUInt32;
  116. /**
  117. * @return An int64 read from the stream.
  118. **/
  119. - (int64_t)readInt64;
  120. /**
  121. * @return An int32 read from the stream.
  122. **/
  123. - (int32_t)readInt32;
  124. /**
  125. * @return A fixed64 read from the stream.
  126. **/
  127. - (uint64_t)readFixed64;
  128. /**
  129. * @return A fixed32 read from the stream.
  130. **/
  131. - (uint32_t)readFixed32;
  132. /**
  133. * @return An enum read from the stream.
  134. **/
  135. - (int32_t)readEnum;
  136. /**
  137. * @return A sfixed32 read from the stream.
  138. **/
  139. - (int32_t)readSFixed32;
  140. /**
  141. * @return A fixed64 read from the stream.
  142. **/
  143. - (int64_t)readSFixed64;
  144. /**
  145. * @return A sint32 read from the stream.
  146. **/
  147. - (int32_t)readSInt32;
  148. /**
  149. * @return A sint64 read from the stream.
  150. **/
  151. - (int64_t)readSInt64;
  152. /**
  153. * @return A boolean read from the stream.
  154. **/
  155. - (BOOL)readBool;
  156. /**
  157. * @return A string read from the stream.
  158. **/
  159. - (NSString *)readString;
  160. /**
  161. * @return Data read from the stream.
  162. **/
  163. - (NSData *)readBytes;
  164. /**
  165. * Read an embedded message field value from the stream.
  166. *
  167. * @param message The message to set fields on as they are read.
  168. * @param extensionRegistry An optional extension registry to use to lookup
  169. * extensions for message.
  170. **/
  171. - (void)readMessage:(GPBMessage *)message
  172. extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
  173. /**
  174. * Reads and discards a single field, given its tag value.
  175. *
  176. * @param tag The tag number of the field to skip.
  177. *
  178. * @return NO if the tag is an endgroup tag (in which case nothing is skipped),
  179. * YES in all other cases.
  180. **/
  181. - (BOOL)skipField:(int32_t)tag;
  182. /**
  183. * Reads and discards an entire message. This will read either until EOF or
  184. * until an endgroup tag, whichever comes first.
  185. **/
  186. - (void)skipMessage;
  187. /**
  188. * Check to see if the logical end of the stream has been reached.
  189. *
  190. * @note This can return NO when there is no more data, but the current parsing
  191. * expected more data.
  192. *
  193. * @return YES if the logical end of the stream has been reached, NO otherwise.
  194. **/
  195. - (BOOL)isAtEnd;
  196. /**
  197. * @return The offset into the stream.
  198. **/
  199. - (size_t)position;
  200. /**
  201. * Moves the limit to the given byte offset starting at the current location.
  202. *
  203. * @exception GPBCodedInputStreamException If the requested bytes exceeed the
  204. * current limit.
  205. *
  206. * @param byteLimit The number of bytes to move the limit, offset to the current
  207. * location.
  208. *
  209. * @return The limit offset before moving the new limit.
  210. */
  211. - (size_t)pushLimit:(size_t)byteLimit;
  212. /**
  213. * Moves the limit back to the offset as it was before calling pushLimit:.
  214. *
  215. * @param oldLimit The number of bytes to move the current limit. Usually this
  216. * is the value returned by the pushLimit: method.
  217. */
  218. - (void)popLimit:(size_t)oldLimit;
  219. /**
  220. * Verifies that the last call to -readTag returned the given tag value. This
  221. * is used to verify that a nested group ended with the correct end tag.
  222. *
  223. * @exception NSParseErrorException If the value does not match the last tag.
  224. *
  225. * @param expected The tag that was expected.
  226. **/
  227. - (void)checkLastTagWas:(int32_t)expected;
  228. @end
  229. NS_ASSUME_NONNULL_END