1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2015 Google Inc. All rights reserved. 3 // 4 // Use of this source code is governed by a BSD-style 5 // license that can be found in the LICENSE file or at 6 // https://developers.google.com/open-source/licenses/bsd 7 8 #import <Foundation/Foundation.h> 9 10 #import "GPBAny.pbobjc.h" 11 #import "GPBDuration.pbobjc.h" 12 #import "GPBTimestamp.pbobjc.h" 13 14 NS_ASSUME_NONNULL_BEGIN 15 16 #pragma mark - Errors 17 18 /** NSError domain used for errors. */ 19 extern NSString *const GPBWellKnownTypesErrorDomain; 20 21 /** Error code for NSError with GPBWellKnownTypesErrorDomain. */ 22 typedef NS_ENUM(NSInteger, GPBWellKnownTypesErrorCode) { 23 /** The type_url could not be computed for the requested GPBMessage class. */ 24 GPBWellKnownTypesErrorCodeFailedToComputeTypeURL = -100, 25 /** type_url in a Any doesn’t match that of the requested GPBMessage class. */ 26 GPBWellKnownTypesErrorCodeTypeURLMismatch = -101, 27 }; 28 29 #pragma mark - GPBTimestamp 30 31 /** 32 * Category for GPBTimestamp to work with standard Foundation time/date types. 33 **/ 34 @interface GPBTimestamp (GBPWellKnownTypes) 35 36 /** The NSDate representation of this GPBTimestamp. */ 37 @property(nonatomic, readwrite, strong) NSDate *date; 38 39 /** 40 * The NSTimeInterval representation of this GPBTimestamp. 41 * 42 * @note: Not all second/nanos combinations can be represented in a 43 * NSTimeInterval, so getting this could be a lossy transform. 44 **/ 45 @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970; 46 47 /** 48 * Initializes a GPBTimestamp with the given NSDate. 49 * 50 * @param date The date to configure the GPBTimestamp with. 51 * 52 * @return A newly initialized GPBTimestamp. 53 **/ 54 - (instancetype)initWithDate:(NSDate *)date; 55 56 /** 57 * Initializes a GPBTimestamp with the given NSTimeInterval. 58 * 59 * @param timeIntervalSince1970 Time interval to configure the GPBTimestamp with. 60 * 61 * @return A newly initialized GPBTimestamp. 62 **/ 63 - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970; 64 65 @end 66 67 #pragma mark - GPBDuration 68 69 /** 70 * Category for GPBDuration to work with standard Foundation time type. 71 **/ 72 @interface GPBDuration (GBPWellKnownTypes) 73 74 /** 75 * The NSTimeInterval representation of this GPBDuration. 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 timeInterval; 81 82 /** 83 * Initializes a GPBDuration with the given NSTimeInterval. 84 * 85 * @param timeInterval Time interval to configure the GPBDuration with. 86 * 87 * @return A newly initialized GPBDuration. 88 **/ 89 - (instancetype)initWithTimeInterval:(NSTimeInterval)timeInterval; 90 91 // These next two methods are deprecated because GBPDuration has no need of a 92 // "base" time. The older methods were about symmetry with GBPTimestamp, but 93 // the unix epoch usage is too confusing. 94 95 /** Deprecated, use timeInterval instead. */ 96 @property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970 97 __attribute__((deprecated("Use timeInterval"))); 98 /** Deprecated, use initWithTimeInterval: instead. */ 99 - (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970 100 __attribute__((deprecated("Use initWithTimeInterval:"))); 101 102 @end 103 104 #pragma mark - GPBAny 105 106 /** 107 * Category for GPBAny to help work with the message within the object. 108 **/ 109 @interface GPBAny (GBPWellKnownTypes) 110 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 error:(NSError **)errorPtr; 122 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 /** 138 * Initializes a GPBAny to contain the serialized message. This uses 139 * type.googleapis.com/ as the type_url's prefix. 140 * 141 * @param message The message to be packed into the GPBAny. 142 * @param errorPtr Pointer to an error that will be populated if something goes 143 * wrong. 144 * 145 * @return A newly configured GPBAny with the given message, or nil on failure. 146 */ 147 - (nullable instancetype)initWithMessage:(nonnull GPBMessage *)message error:(NSError **)errorPtr; 148 149 /** 150 * Initializes a GPBAny to contain the serialized message. 151 * 152 * @param message The message to be packed into the GPBAny. 153 * @param typeURLPrefix The URL prefix to apply for type_url. 154 * @param errorPtr Pointer to an error that will be populated if something 155 * goes wrong. 156 * 157 * @return A newly configured GPBAny with the given message, or nil on failure. 158 */ 159 - (nullable instancetype)initWithMessage:(nonnull GPBMessage *)message 160 typeURLPrefix:(nonnull NSString *)typeURLPrefix 161 error:(NSError **)errorPtr; 162 163 /** 164 * Packs the serialized message into this GPBAny. This uses 165 * type.googleapis.com/ as the type_url's prefix. 166 * 167 * @param message The message to be packed into the GPBAny. 168 * @param errorPtr Pointer to an error that will be populated if something goes 169 * wrong. 170 * 171 * @return Whether the packing was successful or not. 172 */ 173 - (BOOL)packWithMessage:(nonnull GPBMessage *)message error:(NSError **)errorPtr; 174 175 /** 176 * Packs the serialized message into this GPBAny. 177 * 178 * @param message The message to be packed into the GPBAny. 179 * @param typeURLPrefix The URL prefix to apply for type_url. 180 * @param errorPtr Pointer to an error that will be populated if something 181 * goes wrong. 182 * 183 * @return Whether the packing was successful or not. 184 */ 185 - (BOOL)packWithMessage:(nonnull GPBMessage *)message 186 typeURLPrefix:(nonnull NSString *)typeURLPrefix 187 error:(NSError **)errorPtr; 188 189 /** 190 * Unpacks the serialized message as if it was an instance of the given class. 191 * 192 * @note When checking type_url, the base URL is not checked, only the fully 193 * qualified name. 194 * 195 * @param messageClass The class to use to deserialize the contained message. 196 * @param errorPtr Pointer to an error that will be populated if something 197 * goes wrong. 198 * 199 * @return An instance of the given class populated with the contained data, or 200 * nil on failure. 201 */ 202 - (nullable GPBMessage *)unpackMessageClass:(Class)messageClass error:(NSError **)errorPtr; 203 204 /** 205 * Unpacks the serialized message as if it was an instance of the given class. 206 * 207 * @note When checking type_url, the base URL is not checked, only the fully 208 * qualified name. 209 * 210 * @param messageClass The class to use to deserialize the contained message. 211 * @param extensionRegistry The extension registry to use to look up extensions. 212 * @param errorPtr Pointer to an error that will be populated if something 213 * goes wrong. 214 * 215 * @return An instance of the given class populated with the contained data, or 216 * nil on failure. 217 */ 218 - (nullable GPBMessage *)unpackMessageClass:(Class)messageClass 219 extensionRegistry:(nullable id<GPBExtensionRegistry>)extensionRegistry 220 error:(NSError **)errorPtr; 221 222 @end 223 224 NS_ASSUME_NONNULL_END 225