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