Also tagged with one or more of these keywords binary option
This guide describes how to use the protocol buffer language to structure your protocol buffer data, including. Also tagged with one or more of these keywords binary option covers the proto2 version of the protocol buffers language: This is a reference guide — for a step by step example that uses many of the features described in this document, see the tutorial for your chosen language.
Defining A Message Type First let's look at a very simple example. Let's say you want to define a search request message format, where each search request has a query string, the particular page of results you are also tagged with one or more of these keywords binary option in, and a number of results per page. Each field has a name and a type. Specifying Field Types In the above example, all the fields are scalar types: However, you can also specify composite types for your fields, including enumerations and other message types.
Assigning Tags As you can see, each field in the message definition has a unique numbered tag. These tags are used to identify your fields in the message binary formatand should not be changed once your message type is in use. Note that tags with values in the range 1 through 15 take one byte to encode, including the identifying number and the field's type you can find out more about this in Protocol Buffer Encoding.
Tags in the range 16 through take two bytes. So you should reserve the tags 1 through 15 for very frequently occurring message elements. Remember to leave some room for frequently occurring elements that might be added in the also tagged with one or more of these keywords binary option.
The smallest tag number you can specify is 1, and the largest is 2 29 - 1, or , You also cannot use the numbers through FieldDescriptor:: Similarly, you cannot use any previously reserved tags. Specifying Field Rules You specify that message fields are one of the following: The order of the repeated values will be preserved. For historical reasons, repeated fields of scalar numeric types aren't encoded as efficiently as they could be.
Required Is Forever You should be very careful about marking fields as required. If at some point you wish to stop writing or sending a required field, it will be problematic to change the field to an optional field — old readers will consider messages without this field to be incomplete and may reject or drop them unintentionally. You should consider writing application-specific custom validation routines for your buffers instead.
Some engineers at Google have come to the conclusion that using required does more harm than good; they prefer to use only optional and repeated. However, this view is not universal. Adding More Message Types Multiple message types can be defined in a single. This is useful if you are defining multiple related messages — so, for example, if you wanted to define the reply message format that corresponds to your SearchResponse message type, you could add it to the same.
It's recommended to include as few message types per. Adding Comments To add comments to your. This can cause severe issues if they later load old versions of the same. The protocol buffer compiler will complain if any future users try to use these field identifiers.
What's Generated From Your. When you run the protocol buffer compiler on a. For Javathe compiler generates a. Python is a little different — the Python compiler generates a module with a static descriptor of each message type in your. For Gothe compiler generates a. You can find out more about using the APIs for each language by following the tutorial for your chosen language.
Scalar Value Types A scalar message field can have one of the following types — the table shows the type specified in the. Inefficient for encoding negative numbers — if your field is likely to have negative values, use sint32 instead.
Inefficient for encoding negative numbers — if your field is likely to have negative values, use sint64 instead. These more efficiently encode negative numbers than regular int32s. These more efficiently encode negative numbers than regular int64s.
More efficient than uint32 if values are often greater than 2 More efficient than uint64 if values are often greater than 2 In all cases, the value must fit in the type represented when set. As mentioned above, elements in a message description can be labeled optional.
A well-formed message may or may not contain an optional element. When a message is parsed, if it does not contain an optional element, the corresponding field in the parsed object is set to the default value for that field. The default value can be specified as part of the message description. For bools, the default value is false. For numeric types, the default value is zero.
For enums, the default value is the first value listed in the enum's type definition. This means care must be taken when adding a value to the beginning of an enum value list.
See the Updating A Message Type section for guidelines on how to safely change definitions. Enumerations When you're defining a message type, you might want one of its fields to only have one of a pre-defined list of values. You can do this very simply by adding an enum to your message definition - a field with an enum type can only have one of a specified set of constants as its value if you try to provide a different value, the parser will treat it like an unknown field.
In the following example we've added an enum called Corpus with all the possible values, and a field of type Corpus: Since enum values use varint encoding on the wire, negative values are inefficient and thus not recommended. You can define enum s within a message definition, as in the above example, or outside — these enum s can be reused also tagged with one or more of these keywords binary option any message definition in your.
You can also use an enum type declared in one message as the type of a field in a different message, using the syntax MessageType. For more information about how to work with message enum s in your applications, see the generated code guide for your chosen language. Reserved Values If you update an enum type by entirely removing an enum entry, or commenting it out, future users can reuse the numeric value when making their own updates to the type.
The protocol buffer compiler will complain if any future users try to use these identifiers. You can specify that your reserved numeric value range goes up to the maximum possible value using the max keyword. Using Other Message Types You can use other message types as field also tagged with one or more of these keywords binary option. For example, let's say you wanted to include Result messages in each SearchResponse message — to do this, you can define a Result message type in the same.
You can use definitions from other. However, sometimes you may need to move a. Instead of moving the. If no flag was given, it looks in the directory in which the compiler was invoked. It's possible also tagged with one or more of these keywords binary option import proto3 message types and use them in your proto2 messages, and vice versa. However, proto2 enums cannot be used in proto3 syntax. Nested Types You can define and use message types inside other message types, as in the following example — here the Result message is defined inside the SearchResponse message: Groups are another way to nest information in your message definitions.
For example, another way to specify a SearchResponse containing a number of Result s is as follows: In your code, you can treat this message just as if it had a Result type field called result the latter name is converted to lower-case so that it does not conflict with the former. Therefore, this example is exactly equivalent to the SearchResponse above, except that the message has a different wire format. Updating A Message Type If an existing message type no longer meets all your needs — for example, you'd like the message format to have an extra field — but you'd still like to use code created with the old format, don't worry!
It's very simple to update message types without breaking any of your existing code. Just remember the following rules: Don't change the numeric tags for any existing fields.
Any new fields that you add should be optional or repeated. This means that any messages serialized by code using your "old" message format can be parsed by your new generated code, as they won't be missing any required elements. You should set up sensible default values for these elements so that new code can properly interact with messages generated by old code. Similarly, messages created by your new code can be parsed by your old code: However, the unknown fields are not discarded, and if the message is later serialized, the unknown fields are serialized along with it — so if the message is passed on to new code, the new fields are still available.
Non-required fields can be removed, as long as the tag number is not used again in your updated message type. A non-required field can be converted to an extension and vice versa, as long as the type and number stay the same. Embedded messages are compatible with bytes if the bytes contain an encoded version of the message. Given serialized data of a repeated field as input, clients that expect this field to be optional will take the last input value if it's a primitive type field or merge all input elements if it's a message type field.
Also tagged with one or more of these keywords binary option a default value is generally OK, as long as you remember that default values are never sent over the wire.
Thus, if a program receives a message in which a particular field isn't set, the program will see the default value as it was defined in that program's version of the protocol. It will NOT see the default value that was defined in the sender's code. Notably, unrecognized enum values are discarded when the message is deserialized, which makes the field's has.
In the case of repeated enum fields, any unrecognized values are stripped out of the list. However, an integer field also tagged with one or more of these keywords binary option always preserve its value.
Because of this, you need to be very careful when upgrading an integer to an enum in terms of receiving out of bounds enum values on the wire. Note that this can result in strange behavior if this data is serialized and then reparsed by a client that recognizes these values.
In the case of optional fields, even if a new value was written after the original message was deserialized, the old value will be still read by clients that recognize it.