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// This header is private to the ProtobolBuffers library and must NOT be
32// included by any sources outside this library. The contents of this file are
33// subject to change at any time without notice.
34
35#import "GPBDescriptor.h"
36#import "GPBWireFormat.h"
37
38// Describes attributes of the field.
39typedef NS_OPTIONS(uint16_t, GPBFieldFlags) {
40  GPBFieldNone            = 0,
41  // These map to standard protobuf concepts.
42  GPBFieldRequired        = 1 << 0,
43  GPBFieldRepeated        = 1 << 1,
44  GPBFieldPacked          = 1 << 2,
45  GPBFieldOptional        = 1 << 3,
46  GPBFieldHasDefaultValue = 1 << 4,
47
48  // Indicate that the field should "clear" when set to zero value. This is the
49  // proto3 non optional behavior for singular data (ints, data, string, enum)
50  // fields.
51  GPBFieldClearHasIvarOnZero = 1 << 5,
52  // Indicates the field needs custom handling for the TextFormat name, if not
53  // set, the name can be derived from the ObjC name.
54  GPBFieldTextFormatNameCustom = 1 << 6,
55  // Indicates the field has an enum descriptor.
56  GPBFieldHasEnumDescriptor = 1 << 7,
57
58  // These are not standard protobuf concepts, they are specific to the
59  // Objective C runtime.
60
61  // These bits are used to mark the field as a map and what the key
62  // type is.
63  GPBFieldMapKeyMask     = 0xF << 8,
64  GPBFieldMapKeyInt32    =  1 << 8,
65  GPBFieldMapKeyInt64    =  2 << 8,
66  GPBFieldMapKeyUInt32   =  3 << 8,
67  GPBFieldMapKeyUInt64   =  4 << 8,
68  GPBFieldMapKeySInt32   =  5 << 8,
69  GPBFieldMapKeySInt64   =  6 << 8,
70  GPBFieldMapKeyFixed32  =  7 << 8,
71  GPBFieldMapKeyFixed64  =  8 << 8,
72  GPBFieldMapKeySFixed32 =  9 << 8,
73  GPBFieldMapKeySFixed64 = 10 << 8,
74  GPBFieldMapKeyBool     = 11 << 8,
75  GPBFieldMapKeyString   = 12 << 8,
76};
77
78// NOTE: The structures defined here have their members ordered to minimize
79// their size. This directly impacts the size of apps since these exist per
80// field/extension.
81
82// Describes a single field in a protobuf as it is represented as an ivar.
83typedef struct GPBMessageFieldDescription {
84  // Name of ivar.
85  const char *name;
86  union {
87    // className is deprecated and will be removed in favor of clazz.
88    // kept around right now for backwards compatibility.
89    // clazz is used iff GPBDescriptorInitializationFlag_UsesClassRefs is set.
90    char *className;  // Name of the class of the message.
91    Class clazz;  // Class of the message.
92    // For enums only: If EnumDescriptors are compiled in, it will be that,
93    // otherwise it will be the verifier.
94    GPBEnumDescriptorFunc enumDescFunc;
95    GPBEnumValidationFunc enumVerifier;
96  } dataTypeSpecific;
97  // The field number for the ivar.
98  uint32_t number;
99  // The index (in bits) into _has_storage_.
100  //   >= 0: the bit to use for a value being set.
101  //   = GPBNoHasBit(INT32_MAX): no storage used.
102  //   < 0: in a oneOf, use a full int32 to record the field active.
103  int32_t hasIndex;
104  // Offset of the variable into it's structure struct.
105  uint32_t offset;
106  // Field flags. Use accessor functions below.
107  GPBFieldFlags flags;
108  // Data type of the ivar.
109  GPBDataType dataType;
110} GPBMessageFieldDescription;
111
112// Fields in messages defined in a 'proto2' syntax file can provide a default
113// value. This struct provides the default along with the field info.
114typedef struct GPBMessageFieldDescriptionWithDefault {
115  // Default value for the ivar.
116  GPBGenericValue defaultValue;
117
118  GPBMessageFieldDescription core;
119} GPBMessageFieldDescriptionWithDefault;
120
121// Describes attributes of the extension.
122typedef NS_OPTIONS(uint8_t, GPBExtensionOptions) {
123  GPBExtensionNone          = 0,
124  // These map to standard protobuf concepts.
125  GPBExtensionRepeated      = 1 << 0,
126  GPBExtensionPacked        = 1 << 1,
127  GPBExtensionSetWireFormat = 1 << 2,
128};
129
130// An extension
131typedef struct GPBExtensionDescription {
132  GPBGenericValue defaultValue;
133  const char *singletonName;
134  // Before 3.12, `extendedClass` was just a `const char *`. Thanks to nested
135  // initialization (https://en.cppreference.com/w/c/language/struct_initialization#Nested_initialization)
136  // old generated code with `.extendedClass = GPBStringifySymbol(Something)`
137  // still works; and the current generator can use `extendedClass.clazz`, to
138  // pass a Class reference.
139  union {
140    const char *name;
141    Class clazz;
142  } extendedClass;
143  // Before 3.12, this was `const char *messageOrGroupClassName`. In the
144  // initial 3.12 release, we moved the `union messageOrGroupClass`, and failed
145  // to realize that would break existing source code for extensions. So to
146  // keep existing source code working, we added an unnamed union (C11) to
147  // provide both the old field name and the new union. This keeps both older
148  // and newer code working.
149  // Background: https://github.com/protocolbuffers/protobuf/issues/7555
150  union {
151    const char *messageOrGroupClassName;
152    union {
153     const char *name;
154     Class clazz;
155   } messageOrGroupClass;
156  };
157  GPBEnumDescriptorFunc enumDescriptorFunc;
158  int32_t fieldNumber;
159  GPBDataType dataType;
160  GPBExtensionOptions options;
161} GPBExtensionDescription;
162
163typedef NS_OPTIONS(uint32_t, GPBDescriptorInitializationFlags) {
164  GPBDescriptorInitializationFlag_None              = 0,
165  GPBDescriptorInitializationFlag_FieldsWithDefault = 1 << 0,
166  GPBDescriptorInitializationFlag_WireFormat        = 1 << 1,
167
168  // This is used as a stopgap as we move from using class names to class
169  // references. The runtime needs to support both until we allow a
170  // breaking change in the runtime.
171  GPBDescriptorInitializationFlag_UsesClassRefs     = 1 << 2,
172
173  // This flag is used to indicate that the generated sources already contain
174  // the `GPBFieldClearHasIvarOnZero` flag and it doesn't have to be computed
175  // at startup. This allows older generated code to still work with the
176  // current runtime library.
177  GPBDescriptorInitializationFlag_Proto3OptionalKnown = 1 << 3,
178};
179
180@interface GPBDescriptor () {
181 @package
182  NSArray *fields_;
183  NSArray *oneofs_;
184  uint32_t storageSize_;
185}
186
187// fieldDescriptions have to be long lived, they are held as raw pointers.
188+ (instancetype)
189    allocDescriptorForClass:(Class)messageClass
190                  rootClass:(Class)rootClass
191                       file:(GPBFileDescriptor *)file
192                     fields:(void *)fieldDescriptions
193                 fieldCount:(uint32_t)fieldCount
194                storageSize:(uint32_t)storageSize
195                      flags:(GPBDescriptorInitializationFlags)flags;
196
197- (instancetype)initWithClass:(Class)messageClass
198                         file:(GPBFileDescriptor *)file
199                       fields:(NSArray *)fields
200                  storageSize:(uint32_t)storage
201                   wireFormat:(BOOL)wireFormat;
202
203// Called right after init to provide extra information to avoid init having
204// an explosion of args. These pointers are recorded, so they are expected
205// to live for the lifetime of the app.
206- (void)setupOneofs:(const char **)oneofNames
207              count:(uint32_t)count
208      firstHasIndex:(int32_t)firstHasIndex;
209- (void)setupExtraTextInfo:(const char *)extraTextFormatInfo;
210- (void)setupExtensionRanges:(const GPBExtensionRange *)ranges count:(int32_t)count;
211- (void)setupContainingMessageClass:(Class)msgClass;
212- (void)setupMessageClassNameSuffix:(NSString *)suffix;
213
214// Deprecated. Use setupContainingMessageClass instead.
215- (void)setupContainingMessageClassName:(const char *)msgClassName;
216
217@end
218
219@interface GPBFileDescriptor ()
220- (instancetype)initWithPackage:(NSString *)package
221                     objcPrefix:(NSString *)objcPrefix
222                         syntax:(GPBFileSyntax)syntax;
223- (instancetype)initWithPackage:(NSString *)package
224                         syntax:(GPBFileSyntax)syntax;
225@end
226
227@interface GPBOneofDescriptor () {
228 @package
229  const char *name_;
230  NSArray *fields_;
231  SEL caseSel_;
232}
233// name must be long lived.
234- (instancetype)initWithName:(const char *)name fields:(NSArray *)fields;
235@end
236
237@interface GPBFieldDescriptor () {
238 @package
239  GPBMessageFieldDescription *description_;
240  GPB_UNSAFE_UNRETAINED GPBOneofDescriptor *containingOneof_;
241
242  SEL getSel_;
243  SEL setSel_;
244  SEL hasOrCountSel_;  // *Count for map<>/repeated fields, has* otherwise.
245  SEL setHasSel_;
246}
247
248// Single initializer
249// description has to be long lived, it is held as a raw pointer.
250- (instancetype)initWithFieldDescription:(void *)description
251                         includesDefault:(BOOL)includesDefault
252                           usesClassRefs:(BOOL)usesClassRefs
253                     proto3OptionalKnown:(BOOL)proto3OptionalKnown
254                                  syntax:(GPBFileSyntax)syntax;
255
256@end
257
258@interface GPBEnumDescriptor ()
259// valueNames, values and extraTextFormatInfo have to be long lived, they are
260// held as raw pointers.
261+ (instancetype)
262    allocDescriptorForName:(NSString *)name
263                valueNames:(const char *)valueNames
264                    values:(const int32_t *)values
265                     count:(uint32_t)valueCount
266              enumVerifier:(GPBEnumValidationFunc)enumVerifier;
267+ (instancetype)
268    allocDescriptorForName:(NSString *)name
269                valueNames:(const char *)valueNames
270                    values:(const int32_t *)values
271                     count:(uint32_t)valueCount
272              enumVerifier:(GPBEnumValidationFunc)enumVerifier
273       extraTextFormatInfo:(const char *)extraTextFormatInfo;
274
275- (instancetype)initWithName:(NSString *)name
276                  valueNames:(const char *)valueNames
277                      values:(const int32_t *)values
278                       count:(uint32_t)valueCount
279                enumVerifier:(GPBEnumValidationFunc)enumVerifier;
280@end
281
282@interface GPBExtensionDescriptor () {
283 @package
284  GPBExtensionDescription *description_;
285}
286@property(nonatomic, readonly) GPBWireFormat wireType;
287
288// For repeated extensions, alternateWireType is the wireType with the opposite
289// value for the packable property.  i.e. - if the extension was marked packed
290// it would be the wire type for unpacked; if the extension was marked unpacked,
291// it would be the wire type for packed.
292@property(nonatomic, readonly) GPBWireFormat alternateWireType;
293
294// description has to be long lived, it is held as a raw pointer.
295- (instancetype)initWithExtensionDescription:(GPBExtensionDescription *)desc
296                               usesClassRefs:(BOOL)usesClassRefs;
297// Deprecated. Calls above with `usesClassRefs = NO`
298- (instancetype)initWithExtensionDescription:(GPBExtensionDescription *)desc;
299
300- (NSComparisonResult)compareByFieldNumber:(GPBExtensionDescriptor *)other;
301@end
302
303CF_EXTERN_C_BEGIN
304
305// Direct access is use for speed, to avoid even internally declaring things
306// read/write, etc. The warning is enabled in the project to ensure code calling
307// protos can turn on -Wdirect-ivar-access without issues.
308#pragma clang diagnostic push
309#pragma clang diagnostic ignored "-Wdirect-ivar-access"
310
311GPB_INLINE BOOL GPBFieldIsMapOrArray(GPBFieldDescriptor *field) {
312  return (field->description_->flags &
313          (GPBFieldRepeated | GPBFieldMapKeyMask)) != 0;
314}
315
316GPB_INLINE GPBDataType GPBGetFieldDataType(GPBFieldDescriptor *field) {
317  return field->description_->dataType;
318}
319
320GPB_INLINE int32_t GPBFieldHasIndex(GPBFieldDescriptor *field) {
321  return field->description_->hasIndex;
322}
323
324GPB_INLINE uint32_t GPBFieldNumber(GPBFieldDescriptor *field) {
325  return field->description_->number;
326}
327
328#pragma clang diagnostic pop
329
330uint32_t GPBFieldTag(GPBFieldDescriptor *self);
331
332// For repeated fields, alternateWireType is the wireType with the opposite
333// value for the packable property.  i.e. - if the field was marked packed it
334// would be the wire type for unpacked; if the field was marked unpacked, it
335// would be the wire type for packed.
336uint32_t GPBFieldAlternateTag(GPBFieldDescriptor *self);
337
338GPB_INLINE BOOL GPBHasPreservingUnknownEnumSemantics(GPBFileSyntax syntax) {
339  return syntax == GPBFileSyntaxProto3;
340}
341
342GPB_INLINE BOOL GPBExtensionIsRepeated(GPBExtensionDescription *description) {
343  return (description->options & GPBExtensionRepeated) != 0;
344}
345
346GPB_INLINE BOOL GPBExtensionIsPacked(GPBExtensionDescription *description) {
347  return (description->options & GPBExtensionPacked) != 0;
348}
349
350GPB_INLINE BOOL GPBExtensionIsWireFormat(GPBExtensionDescription *description) {
351  return (description->options & GPBExtensionSetWireFormat) != 0;
352}
353
354// Helper for compile time assets.
355#ifndef GPBInternalCompileAssert
356  #if __has_feature(c_static_assert) || __has_extension(c_static_assert)
357    #define GPBInternalCompileAssert(test, msg) _Static_assert((test), #msg)
358  #else
359    // Pre-Xcode 7 support.
360    #define GPBInternalCompileAssertSymbolInner(line, msg) GPBInternalCompileAssert ## line ## __ ## msg
361    #define GPBInternalCompileAssertSymbol(line, msg) GPBInternalCompileAssertSymbolInner(line, msg)
362    #define GPBInternalCompileAssert(test, msg) \
363        typedef char GPBInternalCompileAssertSymbol(__LINE__, msg) [ ((test) ? 1 : -1) ]
364  #endif  // __has_feature(c_static_assert) || __has_extension(c_static_assert)
365#endif // GPBInternalCompileAssert
366
367// Sanity check that there isn't padding between the field description
368// structures with and without a default.
369GPBInternalCompileAssert(sizeof(GPBMessageFieldDescriptionWithDefault) ==
370                         (sizeof(GPBGenericValue) +
371                          sizeof(GPBMessageFieldDescription)),
372                         DescriptionsWithDefault_different_size_than_expected);
373
374CF_EXTERN_C_END
375