Index: third_party/protobuf/objectivec/GPBMessage.h |
diff --git a/third_party/protobuf/objectivec/GPBMessage.h b/third_party/protobuf/objectivec/GPBMessage.h |
index 332393edc930b2deeb4eedbe7529d5d274f14bb4..58c42d02ee1d63875a30d2698f188a5a5394269e 100644 |
--- a/third_party/protobuf/objectivec/GPBMessage.h |
+++ b/third_party/protobuf/objectivec/GPBMessage.h |
@@ -44,23 +44,27 @@ NS_ASSUME_NONNULL_BEGIN |
CF_EXTERN_C_BEGIN |
-// NSError domain used for errors. |
+/// NSError domain used for errors. |
extern NSString *const GPBMessageErrorDomain; |
+/// Error code for NSError with GPBMessageErrorDomain. |
typedef NS_ENUM(NSInteger, GPBMessageErrorCode) { |
+ /// The data being parsed is bad and a message can not be created from it. |
GPBMessageErrorCodeMalformedData = -100, |
+ /// A message can't be serialized because it is missing required fields. |
GPBMessageErrorCodeMissingRequiredField = -101, |
}; |
-// In DEBUG ONLY, an NSException is thrown when a parsed message doesn't |
-// contain required fields. This key allows you to retrieve the parsed message |
-// from the exception's |userInfo| dictionary. |
#ifdef DEBUG |
+/// In DEBUG ONLY, an NSException is thrown when a parsed message doesn't |
+/// contain required fields. This key allows you to retrieve the parsed message |
+/// from the exception's @c userInfo dictionary. |
extern NSString *const GPBExceptionMessageKey; |
#endif // DEBUG |
CF_EXTERN_C_END |
+/// Base class for all of the generated message classes. |
@interface GPBMessage : NSObject<NSSecureCoding, NSCopying> |
// NOTE: If you add a instance method/property to this class that may conflict |
@@ -68,108 +72,235 @@ CF_EXTERN_C_END |
// The main cases are methods that take no arguments, or setFoo:/hasFoo: type |
// methods. |
+/// The unknown fields for this message. |
+/// |
+/// Only messages from proto files declared with "proto2" syntax support unknown |
+/// fields. For "proto3" syntax, any unknown fields found while parsing are |
+/// dropped. |
@property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields; |
-// Are all required fields in the message and all embedded messages set. |
+/// Are all required fields set in the message and all embedded messages. |
@property(nonatomic, readonly, getter=isInitialized) BOOL initialized; |
-// Returns an autoreleased instance. |
+/// Returns an autoreleased instance. |
+ (instancetype)message; |
-// Create a message based on a variety of inputs. If there is a data parse |
-// error, nil is returned and if not NULL, errorPtr is filled in. |
-// NOTE: In DEBUG ONLY, the message is also checked for all required field, |
-// if one is missing, the parse will fail (returning nil, filling in errorPtr). |
+/// Creates a new instance by parsing the data. This method should be sent to |
+/// the generated message class that the data should be interpreted as. If |
+/// there is an error the method returns nil and the error is returned in |
+/// errorPtr (when provided). |
+/// |
+/// @note In DEBUG builds, the parsed message is checked to be sure all required |
+/// fields were provided, and the parse will fail if some are missing. |
+/// |
+/// @param data The data to parse. |
+/// @param errorPtr An optional error pointer to fill in with a failure reason if |
+/// the data can not be parsed. |
+/// |
+/// @return A new instance of the class messaged. |
+ (instancetype)parseFromData:(NSData *)data error:(NSError **)errorPtr; |
+ |
+/// Creates a new instance by parsing the data. This method should be sent to |
+/// the generated message class that the data should be interpreted as. If |
+/// there is an error the method returns nil and the error is returned in |
+/// errorPtr (when provided). |
+/// |
+/// @note In DEBUG builds, the parsed message is checked to be sure all required |
+/// fields were provided, and the parse will fail if some are missing. |
+/// |
+/// @param data The data to parse. |
+/// @param extensionRegistry The extension registry to use to look up extensions. |
+/// @param errorPtr An optional error pointer to fill in with a failure |
+/// reason if the data can not be parsed. |
+/// |
+/// @return A new instance of the class messaged. |
+ (instancetype)parseFromData:(NSData *)data |
extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry |
error:(NSError **)errorPtr; |
+ |
+/// Creates a new instance by parsing the data from the given input stream. This |
+/// method should be sent to the generated message class that the data should |
+/// be interpreted as. If there is an error the method returns nil and the error |
+/// is returned in errorPtr (when provided). |
+/// |
+/// @note In DEBUG builds, the parsed message is checked to be sure all required |
+/// fields were provided, and the parse will fail if some are missing. |
+/// |
+/// @param input The stream to read data from. |
+/// @param extensionRegistry The extension registry to use to look up extensions. |
+/// @param errorPtr An optional error pointer to fill in with a failure |
+/// reason if the data can not be parsed. |
+/// |
+/// @return A new instance of the class messaged. |
+ (instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input |
extensionRegistry: |
(nullable GPBExtensionRegistry *)extensionRegistry |
error:(NSError **)errorPtr; |
-// Create a message based on delimited input. If there is a data parse |
-// error, nil is returned and if not NULL, errorPtr is filled in. |
+/// Creates a new instance by parsing the data from the given input stream. This |
+/// method should be sent to the generated message class that the data should |
+/// be interpreted as. If there is an error the method returns nil and the error |
+/// is returned in errorPtr (when provided). |
+/// |
+/// @note Unlike the parseFrom... methods, this never checks to see if all of |
+/// the required fields are set. So this method can be used to reload |
+/// messages that may not be complete. |
+/// |
+/// @param input The stream to read data from. |
+/// @param extensionRegistry The extension registry to use to look up extensions. |
+/// @param errorPtr An optional error pointer to fill in with a failure |
+/// reason if the data can not be parsed. |
+/// |
+/// @return A new instance of the class messaged. |
+ (instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input |
extensionRegistry: |
(nullable GPBExtensionRegistry *)extensionRegistry |
error:(NSError **)errorPtr; |
-// If there is a data parse error, nil is returned and if not NULL, errorPtr is |
-// filled in. |
-// NOTE: In DEBUG ONLY, the message is also checked for all required field, |
-// if one is missing, the parse will fail (returning nil, filling in errorPtr). |
+/// Initializes an instance by parsing the data. This method should be sent to |
+/// the generated message class that the data should be interpreted as. If |
+/// there is an error the method returns nil and the error is returned in |
+/// errorPtr (when provided). |
+/// |
+/// @note In DEBUG builds, the parsed message is checked to be sure all required |
+/// fields were provided, and the parse will fail if some are missing. |
+/// |
+/// @param data The data to parse. |
+/// @param errorPtr An optional error pointer to fill in with a failure reason if |
+/// the data can not be parsed. |
- (instancetype)initWithData:(NSData *)data error:(NSError **)errorPtr; |
+ |
+/// Initializes an instance by parsing the data. This method should be sent to |
+/// the generated message class that the data should be interpreted as. If |
+/// there is an error the method returns nil and the error is returned in |
+/// errorPtr (when provided). |
+/// |
+/// @note In DEBUG builds, the parsed message is checked to be sure all required |
+/// fields were provided, and the parse will fail if some are missing. |
+/// |
+/// @param data The data to parse. |
+/// @param extensionRegistry The extension registry to use to look up extensions. |
+/// @param errorPtr An optional error pointer to fill in with a failure |
+/// reason if the data can not be parsed. |
- (instancetype)initWithData:(NSData *)data |
extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry |
error:(NSError **)errorPtr; |
+ |
+/// Initializes an instance by parsing the data from the given input stream. This |
+/// method should be sent to the generated message class that the data should |
+/// be interpreted as. If there is an error the method returns nil and the error |
+/// is returned in errorPtr (when provided). |
+/// |
+/// @note Unlike the parseFrom... methods, this never checks to see if all of |
+/// the required fields are set. So this method can be used to reload |
+/// messages that may not be complete. |
+/// |
+/// @param input The stream to read data from. |
+/// @param extensionRegistry The extension registry to use to look up extensions. |
+/// @param errorPtr An optional error pointer to fill in with a failure |
+/// reason if the data can not be parsed. |
- (instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input |
extensionRegistry: |
(nullable GPBExtensionRegistry *)extensionRegistry |
error:(NSError **)errorPtr; |
-// Serializes the message and writes it to output. |
+/// Writes out the message to the given output stream. |
- (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output; |
+/// Writes out the message to the given output stream. |
- (void)writeToOutputStream:(NSOutputStream *)output; |
-// Serializes the message and writes it to output, but writes the size of the |
-// message as a variant before writing the message. |
+/// Writes out a varint for the message size followed by the the message to |
+/// the given output stream. |
- (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output; |
+/// Writes out a varint for the message size followed by the the message to |
+/// the given output stream. |
- (void)writeDelimitedToOutputStream:(NSOutputStream *)output; |
-// Serializes the message to an NSData. Note that this value is not cached, so |
-// if you are using it repeatedly, cache it yourself. If there is an error |
-// while generating the data, nil is returned. |
-// NOTE: In DEBUG ONLY, the message is also checked for all required field, |
-// if one is missing, nil will be returned. |
+/// Serializes the message to a @c NSData. |
+/// |
+/// If there is an error while generating the data, nil is returned. |
+/// |
+/// @note This value is not cached, so if you are using it repeatedly, cache |
+/// it yourself. |
+/// |
+/// @note In DEBUG ONLY, the message is also checked for all required field, |
+/// if one is missing, nil will be returned. |
- (nullable NSData *)data; |
-// Same as -[data], except a delimiter is added to the start of the data |
-// indicating the size of the message data that follows. |
+/// Serializes a varint with the message size followed by the message data, |
+/// returning that as a @c NSData. |
+/// |
+/// @note This value is not cached, so if you are using it repeatedly, cache |
+/// it yourself. |
- (NSData *)delimitedData; |
-// Returns the size of the object if it were serialized. |
-// This is not a cached value. If you are following a pattern like this: |
-// size_t size = [aMsg serializedSize]; |
-// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; |
-// [foo writeSize:size]; |
-// [foo appendData:[aMsg data]]; |
-// you would be better doing: |
-// NSData *data = [aMsg data]; |
-// NSUInteger size = [aMsg length]; |
-// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; |
-// [foo writeSize:size]; |
-// [foo appendData:data]; |
+/// Calculates the size of the object if it were serialized. |
+/// |
+/// This is not a cached value. If you are following a pattern like this: |
+/// @code |
+/// size_t size = [aMsg serializedSize]; |
+/// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; |
+/// [foo writeSize:size]; |
+/// [foo appendData:[aMsg data]]; |
+/// @endcode |
+/// you would be better doing: |
+/// @code |
+/// NSData *data = [aMsg data]; |
+/// NSUInteger size = [aMsg length]; |
+/// NSMutableData *foo = [NSMutableData dataWithCapacity:size + sizeof(size)]; |
+/// [foo writeSize:size]; |
+/// [foo appendData:data]; |
+/// @endcode |
- (size_t)serializedSize; |
-// Return the descriptor for the message |
+/// Return the descriptor for the message class. |
+ (GPBDescriptor *)descriptor; |
+/// Return the descriptor for the message. |
- (GPBDescriptor *)descriptor; |
-// Extensions use boxed values (NSNumbers) for PODs, NSMutableArrays for |
-// repeated. If the extension is a Message one will be auto created for you |
-// and returned similar to fields. |
+/// Test to see if the given extension is set on the message. |
- (BOOL)hasExtension:(GPBExtensionDescriptor *)extension; |
+ |
+/// Fetches the given extension's value for this message. |
+/// |
+/// Extensions use boxed values (NSNumbers) for PODs and NSMutableArrays for |
+/// repeated fields. If the extension is a Message one will be auto created for you |
+/// and returned similar to fields. |
- (nullable id)getExtension:(GPBExtensionDescriptor *)extension; |
+ |
+/// Sets the given extension's value for this message. This is only for single |
+/// field extensions (i.e. - not repeated fields). |
+/// |
+/// Extensions use boxed values (@c NSNumbers). |
- (void)setExtension:(GPBExtensionDescriptor *)extension value:(nullable id)value; |
+ |
+/// Adds the given value to the extension for this message. This is only for |
+/// repeated field extensions. If the field is a repeated POD type the @c value |
+/// is a @c NSNumber. |
- (void)addExtension:(GPBExtensionDescriptor *)extension value:(id)value; |
+ |
+/// Replaces the given value at an index for the extension on this message. This |
+/// is only for repeated field extensions. If the field is a repeated POD type |
+/// the @c value is a @c NSNumber. |
- (void)setExtension:(GPBExtensionDescriptor *)extension |
index:(NSUInteger)index |
value:(id)value; |
+ |
+/// Clears the given extension for this message. |
- (void)clearExtension:(GPBExtensionDescriptor *)extension; |
-// Resets all fields to their default values. |
+/// Resets all of the fields of this message to their default values. |
- (void)clear; |
-// Parses a message of this type from the input and merges it with this |
-// message. |
-// NOTE: This will throw if there is an error parsing the data. |
+/// Parses a message of this type from the input and merges it with this |
+/// message. |
+/// |
+/// @note This will throw if there is an error parsing the data. |
- (void)mergeFromData:(NSData *)data |
extensionRegistry:(nullable GPBExtensionRegistry *)extensionRegistry; |
-// Merges the fields from another message (of the same type) into this |
-// message. |
+/// Merges the fields from another message (of the same type) into this |
+/// message. |
- (void)mergeFrom:(GPBMessage *)other; |
@end |