123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537 |
- // Protocol Buffers - Google's data interchange format
- // Copyright 2008 Google Inc. All rights reserved.
- //
- // Use of this source code is governed by a BSD-style
- // license that can be found in the LICENSE file or at
- // https://developers.google.com/open-source/licenses/bsd
- #import <Foundation/Foundation.h>
- #import "GPBBootstrap.h"
- #import "GPBCodedInputStream.h"
- #import "GPBCodedOutputStream.h"
- #import "GPBDescriptor.h"
- #import "GPBExtensionRegistry.h"
- #import "GPBUnknownFieldSet.h"
- #import "GPBUnknownFields.h"
- @class GPBCodedInputStream;
- @class GPBCodedOutputStream;
- @class GPBUnknownFieldSet;
- @class GPBUnknownFields;
- 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 supports NSSecureCoding, if the message has any
- * extensions, they will end up reloaded in the unknown fields 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 __attribute__((
- deprecated("Use GPBUnknownFields and the -initFromMessage: initializer and "
- "mergeUnknownFields:extensionRegistry:error: to add the data back to a message.")));
- /**
- * 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;
- /**
- * Clears any unknown fields on this message.
- *
- * Note: To clear this message's unknown field and all the unknown fields of the
- * messages within the fields of this message, use
- * `GPBMessageDropUnknownFieldsRecursively()`.
- **/
- - (void)clearUnknownFields;
- /**
- * Merges in the data from an `GPBUnknownFields`, meaning the data from the unknown fields gets
- * re-parsed so any known fields will be properly set.
- *
- * If the intent is to *replace* the message's unknown fields, call `-clearUnknownFields` first.
- *
- * Since the data from the GPBUnknownFields will always be well formed, this call will almost never
- * fail. What could cause it to fail is if the GPBUnknownFields contains a field value that is
- * an error for the message's schema - i.e.: if it contains a length delimited field where the
- * field number for the message is defined to be a _string_ field, however the length delimited
- * data provide is not a valid UTF8 string, or if the field is a _packed_ number field, but the
- * data provided is not a valid for that field.
- *
- * @param unknownFields The unknown fields to merge the data from.
- * @param extensionRegistry The extension registry to use to look up extensions, can be `nil`.
- * @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)mergeUnknownFields:(GPBUnknownFields *)unknownFields
- extensionRegistry:(nullable id<GPBExtensionRegistry>)extensionRegistry
- error:(NSError **)errorPtr;
- @end
- NS_ASSUME_NONNULL_END
|