1 // Protocol Buffers - Google's data interchange format 2 // Copyright 2008 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 "GPBRuntimeTypes.h" 34 35 @class GPBEnumDescriptor; 36 @class GPBFieldDescriptor; 37 @class GPBFileDescriptor; 38 @class GPBOneofDescriptor; 39 40 NS_ASSUME_NONNULL_BEGIN 41 42 /** Syntax used in the proto file. */ 43 typedef NS_ENUM(uint8_t, GPBFileSyntax) { 44 /** Unknown syntax. */ 45 GPBFileSyntaxUnknown = 0, 46 /** Proto2 syntax. */ 47 GPBFileSyntaxProto2 = 2, 48 /** Proto3 syntax. */ 49 GPBFileSyntaxProto3 = 3, 50 }; 51 52 /** Type of proto field. */ 53 typedef NS_ENUM(uint8_t, GPBFieldType) { 54 /** Optional/required field. Only valid for proto2 fields. */ 55 GPBFieldTypeSingle, 56 /** Repeated field. */ 57 GPBFieldTypeRepeated, 58 /** Map field. */ 59 GPBFieldTypeMap, 60 }; 61 62 /** 63 * Describes a proto message. 64 **/ 65 @interface GPBDescriptor : NSObject<NSCopying> 66 67 /** Name of the message. */ 68 @property(nonatomic, readonly, copy) NSString *name; 69 /** Fields declared in the message. */ 70 @property(nonatomic, readonly, strong, nullable) NSArray<GPBFieldDescriptor*> *fields; 71 /** Oneofs declared in the message. */ 72 @property(nonatomic, readonly, strong, nullable) NSArray<GPBOneofDescriptor*> *oneofs; 73 /** Extension range declared for the message. */ 74 @property(nonatomic, readonly, nullable) const GPBExtensionRange *extensionRanges; 75 /** Number of extension ranges declared for the message. */ 76 @property(nonatomic, readonly) uint32_t extensionRangesCount; 77 /** Descriptor for the file where the message was defined. */ 78 @property(nonatomic, readonly) GPBFileDescriptor *file; 79 80 /** Whether the message is in wire format or not. */ 81 @property(nonatomic, readonly, getter=isWireFormat) BOOL wireFormat; 82 /** The class of this message. */ 83 @property(nonatomic, readonly) Class messageClass; 84 /** Containing message descriptor if this message is nested, or nil otherwise. */ 85 @property(readonly, nullable) GPBDescriptor *containingType; 86 /** 87 * Fully qualified name for this message (package.message). Can be nil if the 88 * value is unable to be computed. 89 */ 90 @property(readonly, nullable) NSString *fullName; 91 92 /** 93 * Gets the field for the given number. 94 * 95 * @param fieldNumber The number for the field to get. 96 * 97 * @return The field descriptor for the given number, or nil if not found. 98 **/ 99 - (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber; 100 101 /** 102 * Gets the field for the given name. 103 * 104 * @param name The name for the field to get. 105 * 106 * @return The field descriptor for the given name, or nil if not found. 107 **/ 108 - (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name; 109 110 /** 111 * Gets the oneof for the given name. 112 * 113 * @param name The name for the oneof to get. 114 * 115 * @return The oneof descriptor for the given name, or nil if not found. 116 **/ 117 - (nullable GPBOneofDescriptor *)oneofWithName:(NSString *)name; 118 119 @end 120 121 /** 122 * Describes a proto file. 123 **/ 124 @interface GPBFileDescriptor : NSObject 125 126 /** The package declared in the proto file. */ 127 @property(nonatomic, readonly, copy) NSString *package; 128 /** The objc prefix declared in the proto file. */ 129 @property(nonatomic, readonly, copy, nullable) NSString *objcPrefix; 130 /** The syntax of the proto file. */ 131 @property(nonatomic, readonly) GPBFileSyntax syntax; 132 133 @end 134 135 /** 136 * Describes a oneof field. 137 **/ 138 @interface GPBOneofDescriptor : NSObject 139 /** Name of the oneof field. */ 140 @property(nonatomic, readonly) NSString *name; 141 /** Fields declared in the oneof. */ 142 @property(nonatomic, readonly) NSArray<GPBFieldDescriptor*> *fields; 143 144 /** 145 * Gets the field for the given number. 146 * 147 * @param fieldNumber The number for the field to get. 148 * 149 * @return The field descriptor for the given number, or nil if not found. 150 **/ 151 - (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber; 152 153 /** 154 * Gets the field for the given name. 155 * 156 * @param name The name for the field to get. 157 * 158 * @return The field descriptor for the given name, or nil if not found. 159 **/ 160 - (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name; 161 162 @end 163 164 /** 165 * Describes a proto field. 166 **/ 167 @interface GPBFieldDescriptor : NSObject 168 169 /** Name of the field. */ 170 @property(nonatomic, readonly, copy) NSString *name; 171 /** Number associated with the field. */ 172 @property(nonatomic, readonly) uint32_t number; 173 /** Data type contained in the field. */ 174 @property(nonatomic, readonly) GPBDataType dataType; 175 /** Whether it has a default value or not. */ 176 @property(nonatomic, readonly) BOOL hasDefaultValue; 177 /** Default value for the field. */ 178 @property(nonatomic, readonly) GPBGenericValue defaultValue; 179 /** Whether this field is required. Only valid for proto2 fields. */ 180 @property(nonatomic, readonly, getter=isRequired) BOOL required; 181 /** Whether this field is optional. */ 182 @property(nonatomic, readonly, getter=isOptional) BOOL optional; 183 /** Type of field (single, repeated, map). */ 184 @property(nonatomic, readonly) GPBFieldType fieldType; 185 /** Type of the key if the field is a map. The value's type is -fieldType. */ 186 @property(nonatomic, readonly) GPBDataType mapKeyDataType; 187 /** Whether the field is packable. */ 188 @property(nonatomic, readonly, getter=isPackable) BOOL packable; 189 190 /** The containing oneof if this field is part of one, nil otherwise. */ 191 @property(nonatomic, readonly, nullable) GPBOneofDescriptor *containingOneof; 192 193 /** Class of the message if the field is of message type. */ 194 @property(nonatomic, readonly, nullable) Class msgClass; 195 196 /** Descriptor for the enum if this field is an enum. */ 197 @property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor; 198 199 /** 200 * Checks whether the given enum raw value is a valid enum value. 201 * 202 * @param value The raw enum value to check. 203 * 204 * @return YES if value is a valid enum raw value. 205 **/ 206 - (BOOL)isValidEnumValue:(int32_t)value; 207 208 /** @return Name for the text format, or nil if not known. */ 209 - (nullable NSString *)textFormatName; 210 211 @end 212 213 /** 214 * Describes a proto enum. 215 **/ 216 @interface GPBEnumDescriptor : NSObject 217 218 /** Name of the enum. */ 219 @property(nonatomic, readonly, copy) NSString *name; 220 /** Function that validates that raw values are valid enum values. */ 221 @property(nonatomic, readonly) GPBEnumValidationFunc enumVerifier; 222 223 /** 224 * Returns the enum value name for the given raw enum. 225 * 226 * Note that there can be more than one name corresponding to a given value 227 * if the allow_alias option is used. 228 * 229 * @param number The raw enum value. 230 * 231 * @return The first name that matches the enum value passed, or nil if not valid. 232 **/ 233 - (nullable NSString *)enumNameForValue:(int32_t)number; 234 235 /** 236 * Gets the enum raw value for the given enum name. 237 * 238 * @param outValue A pointer where the value will be set. 239 * @param name The enum name for which to get the raw value. 240 * 241 * @return YES if a value was copied into the pointer, NO otherwise. 242 **/ 243 - (BOOL)getValue:(nullable int32_t *)outValue forEnumName:(NSString *)name; 244 245 /** 246 * Returns the text format for the given raw enum value. 247 * 248 * @param number The raw enum value. 249 * 250 * @return The first text format name which matches the enum value, or nil if not valid. 251 **/ 252 - (nullable NSString *)textFormatNameForValue:(int32_t)number; 253 254 /** 255 * Gets the enum raw value for the given text format name. 256 * 257 * @param outValue A pointer where the value will be set. 258 * @param textFormatName The text format name for which to get the raw value. 259 * 260 * @return YES if a value was copied into the pointer, NO otherwise. 261 **/ 262 - (BOOL)getValue:(nullable int32_t *)outValue forEnumTextFormatName:(NSString *)textFormatName; 263 264 /** 265 * Gets the number of defined enum names. 266 * 267 * @return Count of the number of enum names, including any aliases. 268 */ 269 @property(nonatomic, readonly) uint32_t enumNameCount; 270 271 /** 272 * Gets the enum name corresponding to the given index. 273 * 274 * @param index Index into the available names. The defined range is from 0 275 * to self.enumNameCount - 1. 276 * 277 * @returns The enum name at the given index, or nil if the index is out of range. 278 */ 279 - (nullable NSString *)getEnumNameForIndex:(uint32_t)index; 280 281 /** 282 * Gets the enum text format name corresponding to the given index. 283 * 284 * @param index Index into the available names. The defined range is from 0 285 * to self.enumNameCount - 1. 286 * 287 * @returns The text format name at the given index, or nil if the index is out of range. 288 */ 289 - (nullable NSString *)getEnumTextFormatNameForIndex:(uint32_t)index; 290 291 @end 292 293 /** 294 * Describes a proto extension. 295 **/ 296 @interface GPBExtensionDescriptor : NSObject<NSCopying> 297 /** Field number under which the extension is stored. */ 298 @property(nonatomic, readonly) uint32_t fieldNumber; 299 /** The containing message class, i.e. the class extended by this extension. */ 300 @property(nonatomic, readonly) Class containingMessageClass; 301 /** Data type contained in the extension. */ 302 @property(nonatomic, readonly) GPBDataType dataType; 303 /** Whether the extension is repeated. */ 304 @property(nonatomic, readonly, getter=isRepeated) BOOL repeated; 305 /** Whether the extension is packable. */ 306 @property(nonatomic, readonly, getter=isPackable) BOOL packable; 307 /** The class of the message if the extension is of message type. */ 308 @property(nonatomic, readonly) Class msgClass; 309 /** The singleton name for the extension. */ 310 @property(nonatomic, readonly) NSString *singletonName; 311 /** The enum descriptor if the extension is of enum type. */ 312 @property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor; 313 /** The default value for the extension. */ 314 @property(nonatomic, readonly, nullable) id defaultValue; 315 316 @end 317 318 NS_ASSUME_NONNULL_END 319