GPBWellKnownTypes.h 8.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233
  1. // Protocol Buffers - Google's data interchange format
  2. // Copyright 2015 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. #import "GPBAny.pbobjc.h"
  32. #import "GPBDuration.pbobjc.h"
  33. #import "GPBTimestamp.pbobjc.h"
  34. NS_ASSUME_NONNULL_BEGIN
  35. #pragma mark - Errors
  36. /** NSError domain used for errors. */
  37. extern NSString *const GPBWellKnownTypesErrorDomain;
  38. /** Error code for NSError with GPBWellKnownTypesErrorDomain. */
  39. typedef NS_ENUM(NSInteger, GPBWellKnownTypesErrorCode) {
  40. /** The type_url could not be computed for the requested GPBMessage class. */
  41. GPBWellKnownTypesErrorCodeFailedToComputeTypeURL = -100,
  42. /** type_url in a Any doesn’t match that of the requested GPBMessage class. */
  43. GPBWellKnownTypesErrorCodeTypeURLMismatch = -101,
  44. };
  45. #pragma mark - GPBTimestamp
  46. /**
  47. * Category for GPBTimestamp to work with standard Foundation time/date types.
  48. **/
  49. @interface GPBTimestamp (GBPWellKnownTypes)
  50. /** The NSDate representation of this GPBTimestamp. */
  51. @property(nonatomic, readwrite, strong) NSDate *date;
  52. /**
  53. * The NSTimeInterval representation of this GPBTimestamp.
  54. *
  55. * @note: Not all second/nanos combinations can be represented in a
  56. * NSTimeInterval, so getting this could be a lossy transform.
  57. **/
  58. @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970;
  59. /**
  60. * Initializes a GPBTimestamp with the given NSDate.
  61. *
  62. * @param date The date to configure the GPBTimestamp with.
  63. *
  64. * @return A newly initialized GPBTimestamp.
  65. **/
  66. - (instancetype)initWithDate:(NSDate *)date;
  67. /**
  68. * Initializes a GPBTimestamp with the given NSTimeInterval.
  69. *
  70. * @param timeIntervalSince1970 Time interval to configure the GPBTimestamp with.
  71. *
  72. * @return A newly initialized GPBTimestamp.
  73. **/
  74. - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970;
  75. @end
  76. #pragma mark - GPBDuration
  77. /**
  78. * Category for GPBDuration to work with standard Foundation time type.
  79. **/
  80. @interface GPBDuration (GBPWellKnownTypes)
  81. /**
  82. * The NSTimeInterval representation of this GPBDuration.
  83. *
  84. * @note: Not all second/nanos combinations can be represented in a
  85. * NSTimeInterval, so getting this could be a lossy transform.
  86. **/
  87. @property(nonatomic, readwrite) NSTimeInterval timeInterval;
  88. /**
  89. * Initializes a GPBDuration with the given NSTimeInterval.
  90. *
  91. * @param timeInterval Time interval to configure the GPBDuration with.
  92. *
  93. * @return A newly initialized GPBDuration.
  94. **/
  95. - (instancetype)initWithTimeInterval:(NSTimeInterval)timeInterval;
  96. // These next two methods are deprecated because GBPDuration has no need of a
  97. // "base" time. The older methods were about symmetry with GBPTimestamp, but
  98. // the unix epoch usage is too confusing.
  99. /** Deprecated, use timeInterval instead. */
  100. @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970
  101. __attribute__((deprecated("Use timeInterval")));
  102. /** Deprecated, use initWithTimeInterval: instead. */
  103. - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970
  104. __attribute__((deprecated("Use initWithTimeInterval:")));
  105. @end
  106. #pragma mark - GPBAny
  107. /**
  108. * Category for GPBAny to help work with the message within the object.
  109. **/
  110. @interface GPBAny (GBPWellKnownTypes)
  111. /**
  112. * Convenience method to create a GPBAny containing the serialized message.
  113. * This uses type.googleapis.com/ as the type_url's prefix.
  114. *
  115. * @param message The message to be packed into the GPBAny.
  116. * @param errorPtr Pointer to an error that will be populated if something goes
  117. * wrong.
  118. *
  119. * @return A newly configured GPBAny with the given message, or nil on failure.
  120. */
  121. + (nullable instancetype)anyWithMessage:(nonnull GPBMessage *)message
  122. error:(NSError **)errorPtr;
  123. /**
  124. * Convenience method to create a GPBAny containing the serialized message.
  125. *
  126. * @param message The message to be packed into the GPBAny.
  127. * @param typeURLPrefix The URL prefix to apply for type_url.
  128. * @param errorPtr Pointer to an error that will be populated if something
  129. * goes wrong.
  130. *
  131. * @return A newly configured GPBAny with the given message, or nil on failure.
  132. */
  133. + (nullable instancetype)anyWithMessage:(nonnull GPBMessage *)message
  134. typeURLPrefix:(nonnull NSString *)typeURLPrefix
  135. error:(NSError **)errorPtr;
  136. /**
  137. * Initializes a GPBAny to contain the serialized message. This uses
  138. * type.googleapis.com/ as the type_url's prefix.
  139. *
  140. * @param message The message to be packed into the GPBAny.
  141. * @param errorPtr Pointer to an error that will be populated if something goes
  142. * wrong.
  143. *
  144. * @return A newly configured GPBAny with the given message, or nil on failure.
  145. */
  146. - (nullable instancetype)initWithMessage:(nonnull GPBMessage *)message
  147. error:(NSError **)errorPtr;
  148. /**
  149. * Initializes a GPBAny to contain the serialized message.
  150. *
  151. * @param message The message to be packed into the GPBAny.
  152. * @param typeURLPrefix The URL prefix to apply for type_url.
  153. * @param errorPtr Pointer to an error that will be populated if something
  154. * goes wrong.
  155. *
  156. * @return A newly configured GPBAny with the given message, or nil on failure.
  157. */
  158. - (nullable instancetype)initWithMessage:(nonnull GPBMessage *)message
  159. typeURLPrefix:(nonnull NSString *)typeURLPrefix
  160. error:(NSError **)errorPtr;
  161. /**
  162. * Packs the serialized message into this GPBAny. This uses
  163. * type.googleapis.com/ as the type_url's prefix.
  164. *
  165. * @param message The message to be packed into the GPBAny.
  166. * @param errorPtr Pointer to an error that will be populated if something goes
  167. * wrong.
  168. *
  169. * @return Whether the packing was successful or not.
  170. */
  171. - (BOOL)packWithMessage:(nonnull GPBMessage *)message
  172. error:(NSError **)errorPtr;
  173. /**
  174. * Packs the serialized message into this GPBAny.
  175. *
  176. * @param message The message to be packed into the GPBAny.
  177. * @param typeURLPrefix The URL prefix to apply for type_url.
  178. * @param errorPtr Pointer to an error that will be populated if something
  179. * goes wrong.
  180. *
  181. * @return Whether the packing was successful or not.
  182. */
  183. - (BOOL)packWithMessage:(nonnull GPBMessage *)message
  184. typeURLPrefix:(nonnull NSString *)typeURLPrefix
  185. error:(NSError **)errorPtr;
  186. /**
  187. * Unpacks the serialized message as if it was an instance of the given class.
  188. *
  189. * @note When checking type_url, the base URL is not checked, only the fully
  190. * qualified name.
  191. *
  192. * @param messageClass The class to use to deserialize the contained message.
  193. * @param errorPtr Pointer to an error that will be populated if something
  194. * goes wrong.
  195. *
  196. * @return An instance of the given class populated with the contained data, or
  197. * nil on failure.
  198. */
  199. - (nullable GPBMessage *)unpackMessageClass:(Class)messageClass
  200. error:(NSError **)errorPtr;
  201. @end
  202. NS_ASSUME_NONNULL_END