Skip to content

P
protobuf
Commit 32fadc0d authored by Sergio Campamá's avatar Sergio Campamá Committed by Thomas Van Lenten
Browse files
Options

Migrating documentation of the ObjectiveC runtime code to appledoc. (#1867) 

Work for #1866 

Migrates all the public class docs over to appledoc format.  While Xcode is fine with blank lines in `///` comments, appledoc (used by cocoadocs) isn't and was leaving a bunch of info off the doc pages.

The generator still needs to be updated to do this also; that will be a follow up CL.
parent 1102a8a7
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 515 additions and 180 deletions
objectivec/GPBArray.h
View file @ 32fadc0d
This diff is collapsed.
objectivec/GPBBootstrap.h
View file @ 32fadc0d
......@@ -28,11 +28,13 @@
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
// The Objective C runtime has complete enough info that most protos don’t end
// up using this, so leaving it on is no cost or very little cost. If you
// happen to see it causing bloat, this is the way to disable it. If you do
// need to disable it, try only disabling it for Release builds as having
// full TextFormat can be useful for debugging.
/**
* The Objective C runtime has complete enough info that most protos don’t end
* up using this, so leaving it on is no cost or very little cost. If you
* happen to see it causing bloat, this is the way to disable it. If you do
* need to disable it, try only disabling it for Release builds as having
* full TextFormat can be useful for debugging.
**/
#ifndef GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS
#define GPBOBJC_SKIP_MESSAGE_TEXTFORMAT_EXTRAS 0
#endif
......@@ -42,6 +44,7 @@
#if !__has_feature(objc_fixed_enum)
#error All supported Xcode versions should support objc_fixed_enum.
#endif
// If the headers are imported into Objective-C++, we can run into an issue
// where the defintion of NS_ENUM (really CF_ENUM) changes based on the C++
// standard that is in effect. If it isn't C++11 or higher, the definition
......@@ -53,19 +56,29 @@
#else
#define GPB_ENUM(X) NS_ENUM(int32_t, X)
#endif
// GPB_ENUM_FWD_DECLARE is used for forward declaring enums, ex:
// GPB_ENUM_FWD_DECLARE(Foo_Enum)
// @property (nonatomic) Foo_Enum value;
/**
* GPB_ENUM_FWD_DECLARE is used for forward declaring enums, for example:
*
* ```
* GPB_ENUM_FWD_DECLARE(Foo_Enum)
* @property (nonatomic) Foo_Enum value;
* ```
**/
#define GPB_ENUM_FWD_DECLARE(X) enum X : int32_t
// Based upon CF_INLINE. Forces inlining in release.
/**
* Based upon CF_INLINE. Forces inlining in non DEBUG builds.
**/
#if !defined(DEBUG)
#define GPB_INLINE static __inline__ __attribute__((always_inline))
#else
#define GPB_INLINE static __inline__
#endif
// For use in public headers that might need to deal with ARC.
/**
* For use in public headers that might need to deal with ARC.
**/
#ifndef GPB_UNSAFE_UNRETAINED
#if __has_feature(objc_arc)
#define GPB_UNSAFE_UNRETAINED __unsafe_unretained
......@@ -76,10 +89,14 @@
// If property name starts with init we need to annotate it to get past ARC.
// http://stackoverflow.com/questions/18723226/how-do-i-annotate-an-objective-c-property-with-an-objc-method-family/18723227#18723227
//
// Meant to be used internally by generated code.
#define GPB_METHOD_FAMILY_NONE __attribute__((objc_method_family(none)))
// The protoc-gen-objc version which works with the current version of the
// generated Objective C sources. In general we don't want to change the
// runtime interfaces (or this version) as it means everything has to be
// regenerated.
//
// Meant to be used internally by generated code.
#define GOOGLE_PROTOBUF_OBJC_GEN_VERSION 30001
objectivec/GPBCodedInputStream.h
View file @ 32fadc0d
......@@ -37,125 +37,194 @@ NS_ASSUME_NONNULL_BEGIN
CF_EXTERN_C_BEGIN
/// GPBCodedInputStream exception name. Exceptions raised from
/// GPBCodedInputStream contain an underlying error in the userInfo dictionary
/// under the GPBCodedInputStreamUnderlyingErrorKey key.
/**
* @c GPBCodedInputStream exception name. Exceptions raised from
* @c GPBCodedInputStream contain an underlying error in the userInfo dictionary
* under the GPBCodedInputStreamUnderlyingErrorKey key.
**/
extern NSString *const GPBCodedInputStreamException;
/// The key under which the underlying NSError from the exception is stored.
/** The key under which the underlying NSError from the exception is stored. */
extern NSString *const GPBCodedInputStreamUnderlyingErrorKey;
/// NSError domain used for GPBCodedInputStream errors.
/** NSError domain used for @c GPBCodedInputStream errors. */
extern NSString *const GPBCodedInputStreamErrorDomain;
/// Error code for NSError with GPBCodedInputStreamErrorDomain.
/**
* Error code for NSError with @c GPBCodedInputStreamErrorDomain.
**/
typedef NS_ENUM(NSInteger, GPBCodedInputStreamErrorCode) {
/// The size does not fit in the remaining bytes to be read.
/** The size does not fit in the remaining bytes to be read. */
GPBCodedInputStreamErrorInvalidSize = -100,
/// Attempted to read beyond the subsection limit.
/** Attempted to read beyond the subsection limit. */
GPBCodedInputStreamErrorSubsectionLimitReached = -101,
/// The requested subsection limit is invalid.
/** The requested subsection limit is invalid. */
GPBCodedInputStreamErrorInvalidSubsectionLimit = -102,
/// Invalid tag read.
/** Invalid tag read. */
GPBCodedInputStreamErrorInvalidTag = -103,
/// Invalid UTF-8 character in a string.
/** Invalid UTF-8 character in a string. */
GPBCodedInputStreamErrorInvalidUTF8 = -104,
/// Invalid VarInt read.
/** Invalid VarInt read. */
GPBCodedInputStreamErrorInvalidVarInt = -105,
/// The maximum recursion depth of messages was exceeded.
/** The maximum recursion depth of messages was exceeded. */
GPBCodedInputStreamErrorRecursionDepthExceeded = -106,
};
CF_EXTERN_C_END
/// Reads and decodes protocol message fields.
///
/// The common uses of protocol buffers shouldn't need to use this class.
/// @c GPBMessage's provide a @c +parseFromData:error: and @c
/// +parseFromData:extensionRegistry:error: method that will decode a
/// message for you.
///
/// @note Subclassing of GPBCodedInputStream is NOT supported.
/**
* Reads and decodes protocol message fields.
*
* The common uses of protocol buffers shouldn't need to use this class.
* @c GPBMessage's provide a @c +parseFromData:error: and
* @c +parseFromData:extensionRegistry:error: method that will decode a
* message for you.
*
* @note Subclassing of @c GPBCodedInputStream is NOT supported.
**/
@interface GPBCodedInputStream : NSObject
/// Creates a new stream wrapping some data.
/**
* Creates a new stream wrapping some data.
*
* @param data The data to wrap inside the stream.
*
* @return A newly instanced GPBCodedInputStream.
**/
+ (instancetype)streamWithData:(NSData *)data;
/// Initializes a stream wrapping some data.
/**
* Initializes a stream wrapping some data.
*
* @param data The data to wrap inside the stream.
*
* @return A newly initialized GPBCodedInputStream.
**/
- (instancetype)initWithData:(NSData *)data;
/// Attempt to read a field tag, returning zero if we have reached EOF.
/// Protocol message parsers use this to read tags, since a protocol message
/// may legally end wherever a tag occurs, and zero is not a valid tag number.
/**
* Attempts to read a field tag, returning zero if we have reached EOF.
* Protocol message parsers use this to read tags, since a protocol message
* may legally end wherever a tag occurs, and zero is not a valid tag number.
*
* @return The field tag, or zero if EOF was reached.
**/
- (int32_t)readTag;
/// Read and return a double.
/**
* @return A double read from the stream.
**/
- (double)readDouble;
/// Read and return a float.
/**
* @return A float read from the stream.
**/
- (float)readFloat;
/// Read and return a uint64.
/**
* @return A uint64 read from the stream.
**/
- (uint64_t)readUInt64;
/// Read and return a uint32.
/**
* @return A uint32 read from the stream.
**/
- (uint32_t)readUInt32;
/// Read and return an int64.
/**
* @return An int64 read from the stream.
**/
- (int64_t)readInt64;
/// Read and return an int32.
/**
* @return An int32 read from the stream.
**/
- (int32_t)readInt32;
/// Read and return a fixed64.
/**
* @return A fixed64 read from the stream.
**/
- (uint64_t)readFixed64;
/// Read and return a fixed32.
/**
* @return A fixed32 read from the stream.
**/
- (uint32_t)readFixed32;
/// Read and return an enum (int).
/**
* @return An enum read from the stream.
**/
- (int32_t)readEnum;
/// Read and return a sfixed32.
/**
* @return A sfixed32 read from the stream.
**/
- (int32_t)readSFixed32;
/// Read and return a sfixed64.
/**
* @return A fixed64 read from the stream.
**/
- (int64_t)readSFixed64;
/// Read and return a sint32.
/**
* @return A sint32 read from the stream.
**/
- (int32_t)readSInt32;
/// Read and return a sint64.
/**
* @return A sint64 read from the stream.
**/
- (int64_t)readSInt64;
/// Read and return a boolean.
/**
* @return A boolean read from the stream.
**/
- (BOOL)readBool;
/// Read and return a string.
/**
* @return A string read from the stream.
**/
- (NSString *)readString;
/// Read and return length delimited data.
/**
* @return Data read from the stream.
**/
- (NSData *)readBytes;
/// Read an embedded message field value from the stream.
///
/// @param message The message to set fields on as they are read.
/// @param extensionRegistry An optional extension registry to use to lookup
/// extensions for @c message.
/**
* Read an embedded message field value from the stream.
*
* @param message The message to set fields on as they are read.
* @param extensionRegistry An optional extension registry to use to lookup
* extensions for message.
**/
- (void)readMessage:(GPBMessage *)message
extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry;
/// Reads and discards a single field, given its tag value.
///
/// @param tag The tag number of the field to skip.
///
/// @return NO if the tag is an endgroup tag (in which case nothing is skipped),
/// YES in all other cases.
/**
* Reads and discards a single field, given its tag value.
*
* @param tag The tag number of the field to skip.
*
* @return NO if the tag is an endgroup tag (in which case nothing is skipped),
* YES in all other cases.
**/
- (BOOL)skipField:(int32_t)tag;
/// Reads and discards an entire message. This will read either until EOF
/// or until an endgroup tag, whichever comes first.
/**
* Reads and discards an entire message. This will read either until EOF or
* until an endgroup tag, whichever comes first.
**/
- (void)skipMessage;
/// Check to see if the logical end of the stream has been reached.
///
/// This can return NO when there is no more data, but the current parsing
/// expected more data.
/**
* Check to see if the logical end of the stream has been reached.
*
* @note This can return NO when there is no more data, but the current parsing
* expected more data.
*
* @return YES if the logical end of the stream has been reached, NO otherwise.
**/
- (BOOL)isAtEnd;
/// The offset into the stream.
/**
* @return The offset into the stream.
**/
- (size_t)position;
/// Verifies that the last call to @c -readTag returned the given tag value.
/// This is used to verify that a nested group ended with the correct end tag.
/// Throws @c NSParseErrorException if value does not match the last tag.
///
/// @param expected The tag that was expected.
/**
* Verifies that the last call to -readTag returned the given tag value. This
* is used to verify that a nested group ended with the correct end tag.
*
* @exception NSParseErrorException If the value does not match the last tag.
*
* @param expected The tag that was expected.
**/
- (void)checkLastTagWas:(int32_t)expected;
@end
......
objectivec/GPBCodedOutputStream.h
View file @ 32fadc0d
This diff is collapsed.
objectivec/GPBDescriptor.h
View file @ 32fadc0d
......@@ -39,104 +39,241 @@
NS_ASSUME_NONNULL_BEGIN
/** Syntax used in the proto file. */
typedef NS_ENUM(uint8_t, GPBFileSyntax) {
/** Unknown syntax. */
GPBFileSyntaxUnknown = 0,
/** Proto2 syntax. */
GPBFileSyntaxProto2 = 2,
/** Proto3 syntax. */
GPBFileSyntaxProto3 = 3,
};
/** Type of proto field. */
typedef NS_ENUM(uint8_t, GPBFieldType) {
GPBFieldTypeSingle, // optional/required
GPBFieldTypeRepeated, // repeated
GPBFieldTypeMap, // map<K,V>
/** Optional/required field. Only valid for proto2 fields. */
GPBFieldTypeSingle,
/** Repeated field. */
GPBFieldTypeRepeated,
/** Map field. */
GPBFieldTypeMap,
};
/**
* Describes a proto message.
**/
@interface GPBDescriptor : NSObject<NSCopying>
/** Name of the message. */
@property(nonatomic, readonly, copy) NSString *name;
/** Fields declared in the message. */
@property(nonatomic, readonly, strong, nullable) NSArray<GPBFieldDescriptor*> *fields;
/** Oneofs declared in the message. */
@property(nonatomic, readonly, strong, nullable) NSArray<GPBOneofDescriptor*> *oneofs;
/** Extension range declared for the message. */
@property(nonatomic, readonly, nullable) const GPBExtensionRange *extensionRanges;
/** Number of extension ranges declared for the message. */
@property(nonatomic, readonly) uint32_t extensionRangesCount;
/** Descriptor for the file where the message was defined. */
@property(nonatomic, readonly, assign) GPBFileDescriptor *file;
/** Whether the message is in wire format or not. */
@property(nonatomic, readonly, getter=isWireFormat) BOOL wireFormat;
/** The class of this message. */
@property(nonatomic, readonly) Class messageClass;
/**
* Gets the field for the given number.
*
* @param fieldNumber The number for the field to get.
*
* @return The field descriptor for the given number, or nil if not found.
**/
- (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber;
/**
* Gets the field for the given name.
*
* @param name The name for the field to get.
*
* @return The field descriptor for the given name, or nil if not found.
**/
- (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name;
/**
* Gets the oneof for the given name.
*
* @param name The name for the oneof to get.
*
* @return The oneof descriptor for the given name, or nil if not found.
**/
- (nullable GPBOneofDescriptor *)oneofWithName:(NSString *)name;
@end
/**
* Describes a proto file.
**/
@interface GPBFileDescriptor : NSObject
/** The package declared in the proto file. */
@property(nonatomic, readonly, copy) NSString *package;
/** The syntax of the proto file. */
@property(nonatomic, readonly) GPBFileSyntax syntax;
@end
/**
* Describes a oneof field.
**/
@interface GPBOneofDescriptor : NSObject
/** Name of the oneof field. */
@property(nonatomic, readonly) NSString *name;
/** Fields declared in the oneof. */
@property(nonatomic, readonly) NSArray<GPBFieldDescriptor*> *fields;
/**
* Gets the field for the given number.
*
* @param fieldNumber The number for the field to get.
*
* @return The field descriptor for the given number, or nil if not found.
**/
- (nullable GPBFieldDescriptor *)fieldWithNumber:(uint32_t)fieldNumber;
/**
* Gets the field for the given name.
*
* @param name The name for the field to get.
*
* @return The field descriptor for the given name, or nil if not found.
**/
- (nullable GPBFieldDescriptor *)fieldWithName:(NSString *)name;
@end
/**
* Describes a proto field.
**/
@interface GPBFieldDescriptor : NSObject
/** Name of the field. */
@property(nonatomic, readonly, copy) NSString *name;
/** Number associated with the field. */
@property(nonatomic, readonly) uint32_t number;
/** Data type contained in the field. */
@property(nonatomic, readonly) GPBDataType dataType;
/** Whether it has a default value or not. */
@property(nonatomic, readonly) BOOL hasDefaultValue;
/** Default value for the field. */
@property(nonatomic, readonly) GPBGenericValue defaultValue;
/** Whether this field is required. Only valid for proto2 fields. */
@property(nonatomic, readonly, getter=isRequired) BOOL required;
/** Whether this field is optional. */
@property(nonatomic, readonly, getter=isOptional) BOOL optional;
/** Type of field (single, repeated, map). */
@property(nonatomic, readonly) GPBFieldType fieldType;
// If it is a map, the value type is in -type.
/** Type of the key if the field is a map. The value's type is -fieldType. */
@property(nonatomic, readonly) GPBDataType mapKeyDataType;
/** Whether the field is packable. */
@property(nonatomic, readonly, getter=isPackable) BOOL packable;
/** The containing oneof if this field is part of one, nil otherwise. */
@property(nonatomic, readonly, assign, nullable) GPBOneofDescriptor *containingOneof;
// Message properties
/** Class of the message if the field is of message type. */
@property(nonatomic, readonly, assign, nullable) Class msgClass;
// Enum properties
/** Descriptor for the enum if this field is an enum. */
@property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor;
/**
* Checks whether the given enum raw value is a valid enum value.
*
* @param value The raw enum value to check.
*
* @return YES if value is a valid enum raw value.
**/
- (BOOL)isValidEnumValue:(int32_t)value;
// For now, this will return nil if it doesn't know the name to use for
// TextFormat.
/** @return Name for the text format, or nil if not known. */
- (nullable NSString *)textFormatName;
@end
/**
* Describes a proto enum.
**/
@interface GPBEnumDescriptor : NSObject
/** Name of the enum. */
@property(nonatomic, readonly, copy) NSString *name;
/** Function that validates that raw values are valid enum values. */
@property(nonatomic, readonly) GPBEnumValidationFunc enumVerifier;
/**
* Returns the enum value name for the given raw enum.
*
* @param number The raw enum value.
*
* @return The name of the enum value passed, or nil if not valid.
**/
- (nullable NSString *)enumNameForValue:(int32_t)number;
/**
* Gets the enum raw value for the given enum name.
*
* @param outValue A pointer where the value will be set.
* @param name The enum name for which to get the raw value.
*
* @return YES if a value was copied into the pointer, NO otherwise.
**/
- (BOOL)getValue:(nullable int32_t *)outValue forEnumName:(NSString *)name;
/**
* Returns the text format for the given raw enum value.
*
* @param number The raw enum value.
*
* @return The text format name for the raw enum value, or nil if not valid.
**/
- (nullable NSString *)textFormatNameForValue:(int32_t)number;
/**
* Gets the enum raw value for the given text format name.
*
* @param outValue A pointer where the value will be set.
* @param textFormatName The text format name for which to get the raw value.
*
* @return YES if a value was copied into the pointer, NO otherwise.
**/
- (BOOL)getValue:(nullable int32_t *)outValue forEnumTextFormatName:(NSString *)textFormatName;
@end
/**
* Describes a proto extension.
**/
@interface GPBExtensionDescriptor : NSObject<NSCopying>
/** Field number under which the extension is stored. */
@property(nonatomic, readonly) uint32_t fieldNumber;
/** The containing message class, i.e. the class extended by this extension. */
@property(nonatomic, readonly) Class containingMessageClass;
/** Data type contained in the extension. */
@property(nonatomic, readonly) GPBDataType dataType;
/** Whether the extension is repeated. */
@property(nonatomic, readonly, getter=isRepeated) BOOL repeated;
/** Whether the extension is packable. */
@property(nonatomic, readonly, getter=isPackable) BOOL packable;
/** The class of the message if the extension is of message type. */
@property(nonatomic, readonly, assign) Class msgClass;
/** The singleton name for the extension. */
@property(nonatomic, readonly) NSString *singletonName;
/** The enum descriptor if the extension is of enum type. */
@property(nonatomic, readonly, strong, nullable) GPBEnumDescriptor *enumDescriptor;
/** The default value for the extension. */
@property(nonatomic, readonly, nullable) id defaultValue;
@end
NS_ASSUME_NONNULL_END
objectivec/GPBDictionary.h
View file @ 32fadc0d
This diff is collapsed.
objectivec/GPBExtensionRegistry.h
View file @ 32fadc0d
......@@ -35,45 +35,50 @@
NS_ASSUME_NONNULL_BEGIN
/// A table of known extensions, searchable by name or field number. When
/// parsing a protocol message that might have extensions, you must provide a
/// @c GPBExtensionRegistry in which you have registered any extensions that you
/// want to be able to parse. Otherwise, those extensions will just be treated
/// like unknown fields.
///
/// The @c *Root classes provide @c +extensionRegistry for the extensions defined
/// in a given file *and* all files it imports. You can also create a
/// @c GPBExtensionRegistry, and merge those registries to handle parsing
/// extensions defined from non overlapping files.
///
/// @code
/// GPBExtensionRegistry *registry =
/// [[[MyProtoFileRoot extensionRegistry] copy] autorelease];
/// [registry addExtension:[OtherMessage neededExtension]; // Not in MyProtoFile
/// NSError *parseError = nil;
/// MyMessage *msg = [MyMessage parseData:data
/// extensionRegistry:registry
/// error:&parseError];
/// @endcode
/**
* A table of known extensions, searchable by name or field number. When
* parsing a protocol message that might have extensions, you must provide a
* GPBExtensionRegistry in which you have registered any extensions that you
* want to be able to parse. Otherwise, those extensions will just be treated
* like unknown fields.
*
* The *Root classes provide `+extensionRegistry` for the extensions defined
* in a given file *and* all files it imports. You can also create a
* GPBExtensionRegistry, and merge those registries to handle parsing
* extensions defined from non overlapping files.
*
* ```
* GPBExtensionRegistry *registry = [[MyProtoFileRoot extensionRegistry] copy];
* [registry addExtension:[OtherMessage neededExtension]]; // Not in MyProtoFile
* NSError *parseError;
* MyMessage *msg = [MyMessage parseData:data extensionRegistry:registry error:&parseError];
* ```
**/
@interface GPBExtensionRegistry : NSObject<NSCopying>
/// Add the given @c GPBExtensionDescriptor to this registry.
///
/// @param extension The extension description to add.
/**
* Adds the given GPBExtensionDescriptor to this registry.
*
* @param extension The extension description to add.
**/
- (void)addExtension:(GPBExtensionDescriptor *)extension;
/// Adds all the extensions from another registry to this registry.
///
/// @param registry The registry to merge into this registry.
/**
* Adds all the extensions from another registry to this registry.
*
* @param registry The registry to merge into this registry.
**/
- (void)addExtensions:(GPBExtensionRegistry *)registry;
/// Looks for the extension registered for the given field number on a given
/// @c GPBDescriptor.
///
/// @param descriptor The descriptor to look for a registered extension on.
/// @param fieldNumber The field number of an extension to look for.
///
/// @return The registered @c GPBExtensionDescripto or nil if none was found.
/**
* Looks for the extension registered for the given field number on a given
* GPBDescriptor.
*
* @param descriptor The descriptor to look for a registered extension on.
* @param fieldNumber The field number of the extension to look for.
*
* @return The registered GPBExtensionDescripto or nil if none was found.
**/
- (nullable GPBExtensionDescriptor *)extensionForDescriptor:(GPBDescriptor *)descriptor
fieldNumber:(NSInteger)fieldNumber;
......
objectivec/GPBMessage.h
View file @ 32fadc0d
This diff is collapsed.
objectivec/GPBRootObject.h
View file @ 32fadc0d
......@@ -34,12 +34,17 @@
NS_ASSUME_NONNULL_BEGIN
/// Every generated proto file defines a local "Root" class that exposes a
/// @c GPBExtensionRegistry for all the extensions defined by that file and
/// the files it depends on.
/**
* Every generated proto file defines a local "Root" class that exposes a
* GPBExtensionRegistry for all the extensions defined by that file and
* the files it depends on.
**/
@interface GPBRootObject : NSObject
/// An extension registry for the given file and all the files it depends on.
/**
* @return An extension registry for the given file and all the files it depends
* on.
**/
+ (GPBExtensionRegistry *)extensionRegistry;
@end
......
objectivec/GPBRuntimeTypes.h
View file @ 32fadc0d
......@@ -36,21 +36,28 @@
@class GPBMessage;
@class GPBInt32Array;
// Function used to verify that a given value can be represented by an
// enum type.
/**
* Verifies that a given value can be represented by an enum type.
* */
typedef BOOL (*GPBEnumValidationFunc)(int32_t);
// Function used to fetch an EnumDescriptor.
/**
* Fetches an EnumDescriptor.
* */
typedef GPBEnumDescriptor *(*GPBEnumDescriptorFunc)(void);
// Magic values used for when an the at runtime to indicate an enum value
// that wasn't know at compile time.
/**
* Magic value used at runtime to indicate an enum value that wasn't know at
* compile time.
* */
enum {
kGPBUnrecognizedEnumeratorValue = (int32_t)0xFBADBEEF,
};
// A union for storing all possible Protobuf values.
// Note that owner is responsible for memory management of object types.
/**
* A union for storing all possible Protobuf values. Note that owner is
* responsible for memory management of object types.
* */
typedef union {
BOOL valueBool;
int32_t valueInt32;
......@@ -65,38 +72,73 @@ typedef union {
int32_t valueEnum;
} GPBGenericValue;
// Do not change the order of this enum (or add things to it) without thinking
// about it very carefully. There are several things that depend on the order.
/**
* Enum listing the possible data types that a field can contain.
*
* @note Do not change the order of this enum (or add things to it) without
* thinking about it very carefully. There are several things that depend
* on the order.
* */
typedef NS_ENUM(uint8_t, GPBDataType) {
/** Field contains boolean value(s). */
GPBDataTypeBool = 0,
/** Field contains unsigned 4 byte value(s). */
GPBDataTypeFixed32,
/** Field contains signed 4 byte value(s). */
GPBDataTypeSFixed32,
/** Field contains float value(s). */
GPBDataTypeFloat,
/** Field contains unsigned 8 byte value(s). */
GPBDataTypeFixed64,
/** Field contains signed 8 byte value(s). */
GPBDataTypeSFixed64,
/** Field contains double value(s). */
GPBDataTypeDouble,
/**
* Field contains variable length value(s). Inefficient for encoding negative
* numbers – if your field is likely to have negative values, use
* GPBDataTypeSInt32 instead.
**/
GPBDataTypeInt32,
/**
* Field contains variable length value(s). Inefficient for encoding negative
* numbers – if your field is likely to have negative values, use
* GPBDataTypeSInt64 instead.
**/
GPBDataTypeInt64,
/** Field contains signed variable length integer value(s). */
GPBDataTypeSInt32,
/** Field contains signed variable length integer value(s). */
GPBDataTypeSInt64,
/** Field contains unsigned variable length integer value(s). */
GPBDataTypeUInt32,
/** Field contains unsigned variable length integer value(s). */
GPBDataTypeUInt64,
/** Field contains an arbitrary sequence of bytes. */
GPBDataTypeBytes,
/** Field contains UTF-8 encoded or 7-bit ASCII text. */
GPBDataTypeString,
/** Field contains message type(s). */
GPBDataTypeMessage,
/** Field contains message type(s). */
GPBDataTypeGroup,
/** Field contains enum value(s). */
GPBDataTypeEnum,
};
enum {
// A count of the number of types in GPBDataType. Separated out from the
// GPBDataType enum to avoid warnings regarding not handling
// GPBDataType_Count in switch statements.
/**
* A count of the number of types in GPBDataType. Separated out from the
* GPBDataType enum to avoid warnings regarding not handling GPBDataType_Count
* in switch statements.
**/
GPBDataType_Count = GPBDataTypeEnum + 1
};
// An extension range.
/** An extension range. */
typedef struct GPBExtensionRange {
uint32_t start; // inclusive
uint32_t end; // exclusive
/** Inclusive. */
uint32_t start;
/** Exclusive. */
uint32_t end;
} GPBExtensionRange;
objectivec/GPBUnknownField.h
View file @ 32fadc0d
......@@ -36,52 +36,59 @@
@class GPBUnknownFieldSet;
NS_ASSUME_NONNULL_BEGIN
/// Store an unknown field. These are used in conjunction with @c GPBUnknownFieldSet
/**
* Store an unknown field. These are used in conjunction with
* GPBUnknownFieldSet.
**/
@interface GPBUnknownField : NSObject<NSCopying>
/// The field number the data is stored under.
/** The field number the data is stored under. */
@property(nonatomic, readonly, assign) int32_t number;
/// An array of varint values for this field.
/** An array of varint values for this field. */
@property(nonatomic, readonly, strong) GPBUInt64Array *varintList;
/// An array of fixed32 values for this field.
/** An array of fixed32 values for this field. */
@property(nonatomic, readonly, strong) GPBUInt32Array *fixed32List;
/// An array of fixed64 values for this field.
/** An array of fixed64 values for this field. */
@property(nonatomic, readonly, strong) GPBUInt64Array *fixed64List;
/// An array of data values for this field.
/** An array of data values for this field. */
@property(nonatomic, readonly, strong) NSArray<NSData*> *lengthDelimitedList;
/// An array of groups of values for this field.
/** An array of groups of values for this field. */
@property(nonatomic, readonly, strong) NSArray<GPBUnknownFieldSet*> *groupList;
/// Add a value to the varintList.
///
/// @param value The value to add.
/**
* Add a value to the varintList.
*
* @param value The value to add.
**/
- (void)addVarint:(uint64_t)value;
/// Add a value to the fixed32List.
///
/// @param value The value to add.
/**
* Add a value to the fixed32List.
*
* @param value The value to add.
**/
- (void)addFixed32:(uint32_t)value;
/// Add a value to the fixed64List.
///
/// @param value The value to add.
/**
* Add a value to the fixed64List.
*
* @param value The value to add.
**/
- (void)addFixed64:(uint64_t)value;
/// Add a value to the lengthDelimitedList.
///
/// @param value The value to add.
/**
* Add a value to the lengthDelimitedList.
*
* @param value The value to add.
**/
- (void)addLengthDelimited:(NSData *)value;
/// Add a value to the groupList.
///
/// @param value The value to add.
/**
* Add a value to the groupList.
*
* @param value The value to add.
**/
- (void)addGroup:(GPBUnknownFieldSet *)value;
@end
......
objectivec/GPBUnknownFieldSet.h
View file @ 32fadc0d
......@@ -34,31 +34,48 @@
NS_ASSUME_NONNULL_BEGIN
/// A collection of unknown fields.
/**
* A collection of unknown fields. Fields parsed from the binary representation
* of a message that are unknown end up in an instance of this set. This only
* applies for files declared with the "proto2" syntax. Files declared with the
* "proto3" syntax discard the unknown values.
**/
@interface GPBUnknownFieldSet : NSObject<NSCopying>
/// Tests to see if the given field number has a value.
///
/// @param number The field number to check.
///
/// @return YES if there is an unknown field for the given field number.
/**
* Tests to see if the given field number has a value.
*
* @param number The field number to check.
*
* @return YES if there is an unknown field for the given field number.
**/
- (BOOL)hasField:(int32_t)number;
/// Fetches the @c GPBUnknownField for the given field number.
///
/// @param number The field number to look up.
///
/// @return The @c GPBUnknownField or nil.
/**
* Fetches the GPBUnknownField for the given field number.
*
* @param number The field number to look up.
*
* @return The GPBUnknownField or nil if none found.
**/
- (nullable GPBUnknownField *)getField:(int32_t)number;
/// Returns the number of fields in this set.
/**
* @return The number of fields in this set.
**/
- (NSUInteger)countOfFields;
/// Adds the given field to the set.
/**
* Adds the given field to the set.
*
* @param field The field to add to the set.
**/
- (void)addField:(GPBUnknownField *)field;
/// Returns an NSArray of the @c GPBUnknownFields sorted by the field numbers.
- (NSArray<GPBUnknownField*> *)sortedFields;
/**
* @return An array of the GPBUnknownFields sorted by the field numbers.
**/
- (NSArray<GPBUnknownField *> *)sortedFields;
@end
......
objectivec/GPBUtilities.h
View file @ 32fadc0d
This diff is collapsed.
objectivec/GPBWellKnownTypes.h
View file @ 32fadc0d
......@@ -46,18 +46,54 @@
NS_ASSUME_NONNULL_BEGIN
// Extension to GPBTimestamp to work with standard Foundation time/date types.
/**
* Category for GPBTimestamp to work with standard Foundation time/date types.
**/
@interface GPBTimestamp (GBPWellKnownTypes)
/** The NSDate representation of this GPBTimestamp. */
@property(nonatomic, readwrite, strong) NSDate *date;
/** The NSTimeInterval representation of this GPBTimestamp. */
@property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970;
/**
* Initializes a GPBTimestamp with the given NSDate.
*
* @param date The date to configure the GPBTimestamp with.
*
* @return A newly initialized GPBTimestamp.
**/
- (instancetype)initWithDate:(NSDate *)date;
/**
* Initializes a GPBTimestamp with the given NSTimeInterval.
*
* @param timeIntervalSince1970 Time interval to configure the GPBTimestamp with.
*
* @return A newly initialized GPBTimestamp.
**/
- (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970;
@end
// Extension to GPBDuration to work with standard Foundation time type.
/**
* Category for GPBDuration to work with standard Foundation time type.
**/
@interface GPBDuration (GBPWellKnownTypes)
/** The NSTimeInterval representation of this GPBTimestamp. */
@property(nonatomic, readwrite) NSTimeInterval timeIntervalSince1970;
/**
* Initializes a GPBDuration with the given NSTimeInterval.
*
* @param timeIntervalSince1970 Time interval to configure the GPBDuration with.
*
* @return A newly initialized GPBTimestamp.
**/
- (instancetype)initWithTimeIntervalSince1970:(NSTimeInterval)timeIntervalSince1970;
@end
NS_ASSUME_NONNULL_END
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment