objectivec/GPBMessage.h - third_party/protobuf - Git at Google

 // Protocol Buffers - Google's data interchange format
 // Copyright 2008 Google Inc.  All rights reserved.
 // https://developers.google.com/protocol-buffers/
 //
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 // notice, this list of conditions and the following disclaimer.
 //     * Redistributions in binary form must reproduce the above
 // copyright notice, this list of conditions and the following disclaimer
 // in the documentation and/or other materials provided with the
 // distribution.
 //     * Neither the name of Google Inc. nor the names of its
 // contributors may be used to endorse or promote products derived from
 // this software without specific prior written permission.
 //
 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 #import <Foundation/Foundation.h>

 #import "GPBBootstrap.h"
 #import "GPBExtensionRegistry.h"

 @class GPBDescriptor;
 @class GPBCodedInputStream;
 @class GPBCodedOutputStream;
 @class GPBExtensionDescriptor;
 @class GPBFieldDescriptor;
 @class GPBUnknownFieldSet;

 NS_ASSUME_NONNULL_BEGIN

 CF_EXTERN_C_BEGIN

 /** NSError domain used for errors. */
 extern NSString *const GPBMessageErrorDomain;

 /** Error codes for NSErrors originated in GPBMessage. */
 typedef NS_ENUM(NSInteger, GPBMessageErrorCode) {
   /** Uncategorized error. */
   GPBMessageErrorCodeOther = -100,
   /** Message couldn't be serialized because it is missing required fields. */
   GPBMessageErrorCodeMissingRequiredField = -101,
 };

 /**
  * Key under which the GPBMessage error's reason is stored inside the userInfo
  * dictionary.
  **/
 extern NSString *const GPBErrorReasonKey;

 /**
  * An exception name raised during serialization when the message would be
  * larger than the 2GB limit.
  **/
 extern NSString *const GPBMessageExceptionMessageTooLarge;

 CF_EXTERN_C_END

 /**
  * Base class that each generated message subclasses from.
  *
  * @note @c NSCopying support is a "deep copy", in that all sub objects are
  *       copied.  Just like you wouldn't want a UIView/NSView trying to
  *       exist in two places, you don't want a sub message to be a property
  *       property of two other messages.
  *
  * @note While the class support NSSecureCoding, if the message has any
  *       extensions, they will end up reloaded in @c unknownFields as there is
  *       no way for the @c NSCoding plumbing to pass through a
  *       @c GPBExtensionRegistry. To support extensions, instead of passing the
  *       calls off to the Message, simple store the result of @c data, and then
  *       when loading, fetch the data and use
  *       @c +parseFromData:extensionRegistry:error: to provide an extension
  *       registry.
  **/
 @interface GPBMessage : NSObject <NSSecureCoding, NSCopying>

 // If you add an instance method/property to this class that may conflict with
 // fields declared in protos, you need to update objective_helpers.cc. The main
 // cases are methods that take no arguments, or setFoo:/hasFoo: type methods.

 /**
  * The set of unknown fields for this message.
  **/
 @property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields;

 /**
  * Whether the message, along with all submessages, have the required fields
  * set.
  **/
 @property(nonatomic, readonly, getter=isInitialized) BOOL initialized;

 /**
  * @return An autoreleased message with the default values set.
  **/
 + (instancetype)message;

 /**
  * Creates a new instance by parsing the provided 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.
  *
  * @note The errors returned are likely coming from the domain and codes listed
  *       at the top of this file and GPBCodedInputStream.h.
  *
  * @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 generated class.
  **/
 + (nullable 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.
  *
  * @note The errors returned are likely coming from the domain and codes listed
  *       at the top of this file and GPBCodedInputStream.h.
  *
  * @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 generated class.
  **/
 + (nullable instancetype)parseFromData:(NSData *)data
                      extensionRegistry:(nullable id<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.
  *
  * @note The errors returned are likely coming from the domain and codes listed
  *       at the top of this file and GPBCodedInputStream.h.
  *
  * @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 generated class.
  **/
 + (nullable instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input
                                  extensionRegistry:
                                      (nullable id<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 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.
  *
  * @note The errors returned are likely coming from the domain and codes listed
  *       at the top of this file and GPBCodedInputStream.h.
  *
  * @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 generated class.
  **/
 + (nullable instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input
                                           extensionRegistry:
                                               (nullable id<GPBExtensionRegistry>)extensionRegistry
                                                       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.
  *
  * @note The errors returned are likely coming from the domain and codes listed
  *       at the top of this file and GPBCodedInputStream.h.
  *
  * @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 An initialized instance of the generated class.
  **/
 - (nullable 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.
  *
  * @note The errors returned are likely coming from the domain and codes listed
  *       at the top of this file and GPBCodedInputStream.h.
  *
  * @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 An initialized instance of the generated class.
  **/
 - (nullable instancetype)initWithData:(NSData *)data
                     extensionRegistry:(nullable id<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.
  *
  * @note The errors returned are likely coming from the domain and codes listed
  *       at the top of this file and GPBCodedInputStream.h.
  *
  * @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 An initialized instance of the generated class.
  **/
 - (nullable instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input
                                 extensionRegistry:
                                     (nullable id<GPBExtensionRegistry>)extensionRegistry
                                             error:(NSError **)errorPtr;

 /**
  * Parses the given data as this message's class, and merges those values into
  * this message.
  *
  * @param data              The binary representation of the message to merge.
  * @param extensionRegistry The extension registry to use to look up extensions.
  *
  * @exception GPBCodedInputStreamException Exception thrown when parsing was
  *                                         unsuccessful.
  **/
 - (void)mergeFromData:(NSData *)data
     extensionRegistry:(nullable id<GPBExtensionRegistry>)extensionRegistry
     __attribute__((deprecated(
         "Use -mergeFromData:extensionRegistry:error: instead, especaily if calling from Swift.")));

 /**
  * Parses the given data as this message's class, and merges those values into
  * this message.
  *
  * @param data              The binary representation of the message to merge.
  * @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. Will only be
  *                          filled in if the data failed to be parsed.
  *
  * @return Boolean indicating success. errorPtr will only be fill in on failure.
  **/
 - (BOOL)mergeFromData:(NSData *)data
     extensionRegistry:(nullable id<GPBExtensionRegistry>)extensionRegistry
                 error:(NSError **)errorPtr;

 /**
  * Merges the fields from another message (of the same type) into this
  * message.
  *
  * @param other Message to merge into this message.
  **/
 - (void)mergeFrom:(GPBMessage *)other;

 /**
  * Writes out the message to the given coded output stream.
  *
  * @param output The coded output stream into which to write the message.
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  *
  * @note The most common cause of this failing is from one thread calling this
  *       while another thread has a reference to this message or a message used
  *       within a field and that other thread mutating the message while this
  *       serialization is taking place.
  **/
 - (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;

 /**
  * Writes out the message to the given output stream.
  *
  * @param output The output stream into which to write the message.
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  *
  * @note The most common cause of this failing is from one thread calling this
  *       while another thread has a reference to this message or a message used
  *       within a field and that other thread mutating the message while this
  *       serialization is taking place.
  **/
 - (void)writeToOutputStream:(NSOutputStream *)output;

 /**
  * Writes out a varint for the message size followed by the message to
  * the given output stream.
  *
  * @param output The coded output stream into which to write the message.
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  *
  * @note The most common cause of this failing is from one thread calling this
  *       while another thread has a reference to this message or a message used
  *       within a field and that other thread mutating the message while this
  *       serialization is taking place.
  **/
 - (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;

 /**
  * Writes out a varint for the message size followed by the message to
  * the given output stream.
  *
  * @param output The output stream into which to write the message.
  *
  * @note This can raise the GPBCodedOutputStreamException_* exceptions.
  *
  * @note The most common cause of this failing is from one thread calling this
  *       while another thread has a reference to this message or a message used
  *       within a field and that other thread mutating the message while this
  *       serialization is taking place.
  **/
 - (void)writeDelimitedToOutputStream:(NSOutputStream *)output;

 /**
  * Serializes the message to an 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.
  *
  * @note The most common cause of this failing is from one thread calling this
  *       while another thread has a reference to this message or a message used
  *       within a field and that other thread mutating the message while this
  *       serialization is taking place.
  *
  * @return The binary representation of the message.
  **/
 - (nullable NSData *)data;

 /**
  * Serializes a varint with the message size followed by the message data,
  * returning that as an NSData.
  *
  * @note This value is not cached, so if you are using it repeatedly, it is
  *       recommended to keep a local copy.
  *
  * @note The most common cause of this failing is from one thread calling this
  *       while another thread has a reference to this message or a message used
  *       within a field and that other thread mutating the message while this
  *       serialization is taking place.
  *
  * @return The binary representation of the size along with the message.
  **/
 - (NSData *)delimitedData;

 /**
  * Calculates 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];
  * ```
  *
  * @return The size of the message in it's binary representation.
  **/
 - (size_t)serializedSize;

 /**
  * @return The descriptor for the message class.
  **/
 + (GPBDescriptor *)descriptor;

 /**
  * Return the descriptor for the message.
  **/
 - (GPBDescriptor *)descriptor;

 /**
  * @return An array with the extension descriptors that are currently set on the
  * message.
  **/
 - (NSArray *)extensionsCurrentlySet;

 /**
  * Checks whether there is an extension set on the message which matches the
  * given extension descriptor.
  *
  * @param extension Extension descriptor to check if it's set on the message.
  *
  * @return Whether the extension is currently 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.
  *
  * NOTE: For Enum extensions, if the enum was _closed_, then unknown values
  * were parsed into the message's unknown fields instead of ending up in the
  * extensions, just like what happens with singular/repeated fields. For open
  * enums, the _raw_ value will be in the NSNumber, meaning if one does a
  * `switch` on the values, a `default` case should also be included.
  *
  * @param extension The extension descriptor of the extension to fetch.
  *
  * @return The extension matching the given descriptor, or nil if none found.
  **/
 - (nullable id)getExtension:(GPBExtensionDescriptor *)extension;

 /**
  * Sets the given extension's value for this message. This only applies for
  * single field extensions (i.e. - not repeated fields).
  *
  * Extensions use boxed values (NSNumbers).
  *
  * @param extension The extension descriptor under which to set the value.
  * @param value     The value to be set as the extension.
  **/
 - (void)setExtension:(GPBExtensionDescriptor *)extension value:(nullable id)value;

 /**
  * Adds the given value to the extension for this message. This only applies
  * to repeated field extensions. If the field is a repeated POD type, the value
  * should be an NSNumber.
  *
  * @param extension The extension descriptor under which to add the value.
  * @param value     The value to be added to the repeated extension.
  **/
 - (void)addExtension:(GPBExtensionDescriptor *)extension value:(id)value;

 /**
  * Replaces the value at the given index with the given value for the extension
  * on this message. This only applies to repeated field extensions. If the field
  * is a repeated POD type, the value is should be an NSNumber.
  *
  * @param extension The extension descriptor under which to replace the value.
  * @param index     The index of the extension to be replaced.
  * @param value     The value to be replaced in the repeated extension.
  **/
 - (void)setExtension:(GPBExtensionDescriptor *)extension index:(NSUInteger)index value:(id)value;

 /**
  * Clears the given extension for this message.
  *
  * @param extension The extension descriptor to be cleared from this message.
  **/
 - (void)clearExtension:(GPBExtensionDescriptor *)extension;

 /**
  * Resets all of the fields of this message to their default values.
  **/
 - (void)clear;

 @end

 NS_ASSUME_NONNULL_END
	// Protocol Buffers - Google's data interchange format
	// Copyright 2008 Google Inc. All rights reserved.
	// https://developers.google.com/protocol-buffers/
	//
	// Redistribution and use in source and binary forms, with or without
	// modification, are permitted provided that the following conditions are
	// met:
	//
	// * Redistributions of source code must retain the above copyright
	// notice, this list of conditions and the following disclaimer.
	// * Redistributions in binary form must reproduce the above
	// copyright notice, this list of conditions and the following disclaimer
	// in the documentation and/or other materials provided with the
	// distribution.
	// * Neither the name of Google Inc. nor the names of its
	// contributors may be used to endorse or promote products derived from
	// this software without specific prior written permission.
	//
	// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
	// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
	// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
	// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
	// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
	// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
	// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
	// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
	// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

	#import <Foundation/Foundation.h>

	#import "GPBBootstrap.h"
	#import "GPBExtensionRegistry.h"

	@class GPBDescriptor;
	@class GPBCodedInputStream;
	@class GPBCodedOutputStream;
	@class GPBExtensionDescriptor;
	@class GPBFieldDescriptor;
	@class GPBUnknownFieldSet;

	NS_ASSUME_NONNULL_BEGIN

	CF_EXTERN_C_BEGIN

	/** NSError domain used for errors. */
	extern NSString *const GPBMessageErrorDomain;

	/** Error codes for NSErrors originated in GPBMessage. */
	typedef NS_ENUM(NSInteger, GPBMessageErrorCode) {
	/** Uncategorized error. */
	GPBMessageErrorCodeOther = -100,
	/** Message couldn't be serialized because it is missing required fields. */
	GPBMessageErrorCodeMissingRequiredField = -101,
	};

	/**
	* Key under which the GPBMessage error's reason is stored inside the userInfo
	* dictionary.
	**/
	extern NSString *const GPBErrorReasonKey;

	/**
	* An exception name raised during serialization when the message would be
	* larger than the 2GB limit.
	**/
	extern NSString *const GPBMessageExceptionMessageTooLarge;

	CF_EXTERN_C_END

	/**
	* Base class that each generated message subclasses from.
	*
	* @note @c NSCopying support is a "deep copy", in that all sub objects are
	* copied. Just like you wouldn't want a UIView/NSView trying to
	* exist in two places, you don't want a sub message to be a property
	* property of two other messages.
	*
	* @note While the class support NSSecureCoding, if the message has any
	* extensions, they will end up reloaded in @c unknownFields as there is
	* no way for the @c NSCoding plumbing to pass through a
	* @c GPBExtensionRegistry. To support extensions, instead of passing the
	* calls off to the Message, simple store the result of @c data, and then
	* when loading, fetch the data and use
	* @c +parseFromData:extensionRegistry:error: to provide an extension
	* registry.
	**/
	@interface GPBMessage : NSObject <NSSecureCoding, NSCopying>

	// If you add an instance method/property to this class that may conflict with
	// fields declared in protos, you need to update objective_helpers.cc. The main
	// cases are methods that take no arguments, or setFoo:/hasFoo: type methods.

	/**
	* The set of unknown fields for this message.
	**/
	@property(nonatomic, copy, nullable) GPBUnknownFieldSet *unknownFields;

	/**
	* Whether the message, along with all submessages, have the required fields
	* set.
	**/
	@property(nonatomic, readonly, getter=isInitialized) BOOL initialized;

	/**
	* @return An autoreleased message with the default values set.
	**/
	+ (instancetype)message;

	/**
	* Creates a new instance by parsing the provided 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.
	*
	* @note The errors returned are likely coming from the domain and codes listed
	* at the top of this file and GPBCodedInputStream.h.
	*
	* @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 generated class.
	**/
	+ (nullable 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.
	*
	* @note The errors returned are likely coming from the domain and codes listed
	* at the top of this file and GPBCodedInputStream.h.
	*
	* @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 generated class.
	**/
	+ (nullable instancetype)parseFromData:(NSData *)data
	extensionRegistry:(nullable id<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.
	*
	* @note The errors returned are likely coming from the domain and codes listed
	* at the top of this file and GPBCodedInputStream.h.
	*
	* @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 generated class.
	**/
	+ (nullable instancetype)parseFromCodedInputStream:(GPBCodedInputStream *)input
	extensionRegistry:
	(nullable id<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 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.
	*
	* @note The errors returned are likely coming from the domain and codes listed
	* at the top of this file and GPBCodedInputStream.h.
	*
	* @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 generated class.
	**/
	+ (nullable instancetype)parseDelimitedFromCodedInputStream:(GPBCodedInputStream *)input
	extensionRegistry:
	(nullable id<GPBExtensionRegistry>)extensionRegistry
	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.
	*
	* @note The errors returned are likely coming from the domain and codes listed
	* at the top of this file and GPBCodedInputStream.h.
	*
	* @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 An initialized instance of the generated class.
	**/
	- (nullable 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.
	*
	* @note The errors returned are likely coming from the domain and codes listed
	* at the top of this file and GPBCodedInputStream.h.
	*
	* @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 An initialized instance of the generated class.
	**/
	- (nullable instancetype)initWithData:(NSData *)data
	extensionRegistry:(nullable id<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.
	*
	* @note The errors returned are likely coming from the domain and codes listed
	* at the top of this file and GPBCodedInputStream.h.
	*
	* @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 An initialized instance of the generated class.
	**/
	- (nullable instancetype)initWithCodedInputStream:(GPBCodedInputStream *)input
	extensionRegistry:
	(nullable id<GPBExtensionRegistry>)extensionRegistry
	error:(NSError **)errorPtr;

	/**
	* Parses the given data as this message's class, and merges those values into
	* this message.
	*
	* @param data The binary representation of the message to merge.
	* @param extensionRegistry The extension registry to use to look up extensions.
	*
	* @exception GPBCodedInputStreamException Exception thrown when parsing was
	* unsuccessful.
	**/
	- (void)mergeFromData:(NSData *)data
	extensionRegistry:(nullable id<GPBExtensionRegistry>)extensionRegistry
	__attribute__((deprecated(
	"Use -mergeFromData:extensionRegistry:error: instead, especaily if calling from Swift.")));

	/**
	* Parses the given data as this message's class, and merges those values into
	* this message.
	*
	* @param data The binary representation of the message to merge.
	* @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. Will only be
	* filled in if the data failed to be parsed.
	*
	* @return Boolean indicating success. errorPtr will only be fill in on failure.
	**/
	- (BOOL)mergeFromData:(NSData *)data
	extensionRegistry:(nullable id<GPBExtensionRegistry>)extensionRegistry
	error:(NSError **)errorPtr;

	/**
	* Merges the fields from another message (of the same type) into this
	* message.
	*
	* @param other Message to merge into this message.
	**/
	- (void)mergeFrom:(GPBMessage *)other;

	/**
	* Writes out the message to the given coded output stream.
	*
	* @param output The coded output stream into which to write the message.
	*
	* @note This can raise the GPBCodedOutputStreamException_* exceptions.
	*
	* @note The most common cause of this failing is from one thread calling this
	* while another thread has a reference to this message or a message used
	* within a field and that other thread mutating the message while this
	* serialization is taking place.
	**/
	- (void)writeToCodedOutputStream:(GPBCodedOutputStream *)output;

	/**
	* Writes out the message to the given output stream.
	*
	* @param output The output stream into which to write the message.
	*
	* @note This can raise the GPBCodedOutputStreamException_* exceptions.
	*
	* @note The most common cause of this failing is from one thread calling this
	* while another thread has a reference to this message or a message used
	* within a field and that other thread mutating the message while this
	* serialization is taking place.
	**/
	- (void)writeToOutputStream:(NSOutputStream *)output;

	/**
	* Writes out a varint for the message size followed by the message to
	* the given output stream.
	*
	* @param output The coded output stream into which to write the message.
	*
	* @note This can raise the GPBCodedOutputStreamException_* exceptions.
	*
	* @note The most common cause of this failing is from one thread calling this
	* while another thread has a reference to this message or a message used
	* within a field and that other thread mutating the message while this
	* serialization is taking place.
	**/
	- (void)writeDelimitedToCodedOutputStream:(GPBCodedOutputStream *)output;

	/**
	* Writes out a varint for the message size followed by the message to
	* the given output stream.
	*
	* @param output The output stream into which to write the message.
	*
	* @note This can raise the GPBCodedOutputStreamException_* exceptions.
	*
	* @note The most common cause of this failing is from one thread calling this
	* while another thread has a reference to this message or a message used
	* within a field and that other thread mutating the message while this
	* serialization is taking place.
	**/
	- (void)writeDelimitedToOutputStream:(NSOutputStream *)output;

	/**
	* Serializes the message to an 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.
	*
	* @note The most common cause of this failing is from one thread calling this
	* while another thread has a reference to this message or a message used
	* within a field and that other thread mutating the message while this
	* serialization is taking place.
	*
	* @return The binary representation of the message.
	**/
	- (nullable NSData *)data;

	/**
	* Serializes a varint with the message size followed by the message data,
	* returning that as an NSData.
	*
	* @note This value is not cached, so if you are using it repeatedly, it is
	* recommended to keep a local copy.
	*
	* @note The most common cause of this failing is from one thread calling this
	* while another thread has a reference to this message or a message used
	* within a field and that other thread mutating the message while this
	* serialization is taking place.
	*
	* @return The binary representation of the size along with the message.
	**/
	- (NSData *)delimitedData;

	/**
	* Calculates 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];
	* ```
	*
	* @return The size of the message in it's binary representation.
	**/
	- (size_t)serializedSize;

	/**
	* @return The descriptor for the message class.
	**/
	+ (GPBDescriptor *)descriptor;

	/**
	* Return the descriptor for the message.
	**/
	- (GPBDescriptor *)descriptor;

	/**
	* @return An array with the extension descriptors that are currently set on the
	* message.
	**/
	- (NSArray *)extensionsCurrentlySet;

	/**
	* Checks whether there is an extension set on the message which matches the
	* given extension descriptor.
	*
	* @param extension Extension descriptor to check if it's set on the message.
	*
	* @return Whether the extension is currently 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.
	*
	* NOTE: For Enum extensions, if the enum was _closed_, then unknown values
	* were parsed into the message's unknown fields instead of ending up in the
	* extensions, just like what happens with singular/repeated fields. For open
	* enums, the _raw_ value will be in the NSNumber, meaning if one does a
	* `switch` on the values, a `default` case should also be included.
	*
	* @param extension The extension descriptor of the extension to fetch.
	*
	* @return The extension matching the given descriptor, or nil if none found.
	**/
	- (nullable id)getExtension:(GPBExtensionDescriptor *)extension;

	/**
	* Sets the given extension's value for this message. This only applies for
	* single field extensions (i.e. - not repeated fields).
	*
	* Extensions use boxed values (NSNumbers).
	*
	* @param extension The extension descriptor under which to set the value.
	* @param value The value to be set as the extension.
	**/
	- (void)setExtension:(GPBExtensionDescriptor *)extension value:(nullable id)value;

	/**
	* Adds the given value to the extension for this message. This only applies
	* to repeated field extensions. If the field is a repeated POD type, the value
	* should be an NSNumber.
	*
	* @param extension The extension descriptor under which to add the value.
	* @param value The value to be added to the repeated extension.
	**/
	- (void)addExtension:(GPBExtensionDescriptor *)extension value:(id)value;

	/**
	* Replaces the value at the given index with the given value for the extension
	* on this message. This only applies to repeated field extensions. If the field
	* is a repeated POD type, the value is should be an NSNumber.
	*
	* @param extension The extension descriptor under which to replace the value.
	* @param index The index of the extension to be replaced.
	* @param value The value to be replaced in the repeated extension.
	**/
	- (void)setExtension:(GPBExtensionDescriptor *)extension index:(NSUInteger)index value:(id)value;

	/**
	* Clears the given extension for this message.
	*
	* @param extension The extension descriptor to be cleared from this message.
	**/
	- (void)clearExtension:(GPBExtensionDescriptor *)extension;

	/**
	* Resets all of the fields of this message to their default values.
	**/
	- (void)clear;

	@end

	NS_ASSUME_NONNULL_END