iOS/Pods/Protobuf/objectivec/GPBWellKnownTypes.h

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