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/GPBAny.pbobjc.h> 41 #import <Protobuf/GPBDuration.pbobjc.h> 42 #import <Protobuf/GPBTimestamp.pbobjc.h> 43 #else 44 #import "GPBAny.pbobjc.h" 45 #import "GPBDuration.pbobjc.h" 46 #import "GPBTimestamp.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 246