iOS/Pods/Protobuf/objectivec/GPBDescriptor.h

   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, assign) 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, assign, nullable) GPBOneofDescriptor *containingOneof;
 192
 193 /** Class of the message if the field is of message type. */
 194 @property(nonatomic, readonly, assign, 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  * @param number The raw enum value.
 227  *
 228  * @return The name of the enum value passed, or nil if not valid.
 229  **/
 230 - (nullable NSString *)enumNameForValue:(int32_t)number;
 231
 232 /**
 233  * Gets the enum raw value for the given enum name.
 234  *
 235  * @param outValue A pointer where the value will be set.
 236  * @param name     The enum name for which to get the raw value.
 237  *
 238  * @return YES if a value was copied into the pointer, NO otherwise.
 239  **/
 240 - (BOOL)getValue:(nullable int32_t *)outValue forEnumName:(NSString *)name;
 241
 242 /**
 243  * Returns the text format for the given raw enum value.
 244  *
 245  * @param number The raw enum value.
 246  *
 247  * @return The text format name for the raw enum value, or nil if not valid.
 248  **/
 249 - (nullable NSString *)textFormatNameForValue:(int32_t)number;
 250
 251 /**
 252  * Gets the enum raw value for the given text format name.
 253  *
 254  * @param outValue       A pointer where the value will be set.
 255  * @param textFormatName The text format name for which to get the raw value.
 256  *
 257  * @return YES if a value was copied into the pointer, NO otherwise.
 258  **/
 259 - (BOOL)getValue:(nullable int32_t *)outValue forEnumTextFormatName:(NSString *)textFormatName;
 260
 261 @end
 262
 263 /**
 264  * Describes a proto extension.
 265  **/
 266 @interface GPBExtensionDescriptor : NSObject<NSCopying>
 267 /** Field number under which the extension is stored. */
 268 @property(nonatomic, readonly) uint32_t fieldNumber;
 269 /** The containing message class, i.e. the class extended by this extension. */
 270 @property(nonatomic, readonly) Class containingMessageClass;
 271 /** Data type contained in the extension. */
 272 @property(nonatomic, readonly) GPBDataType dataType;
 273 /** Whether the extension is repeated. */
 274 @property(nonatomic, readonly, getter=isRepeated) BOOL repeated;
 275 /** Whether the extension is packable. */
 276 @property(nonatomic, readonly, getter=isPackable) BOOL packable;
 277 /** The class of the message if the extension is of message type. */
 278 @property(nonatomic, readonly, assign) Class msgClass;
 279 /** The singleton name for the extension. */
 280 @property(nonatomic, readonly) NSString *singletonName;
 281 /** The enum descriptor if the extension is of enum type. */
 282 @property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor;
 283 /** The default value for the extension. */
 284 @property(nonatomic, readonly, nullable) id defaultValue;
 285
 286 @end
 287
 288 NS_ASSUME_NONNULL_END