"Google Protocol buffers" Protocol buffer base: C + + article

Note: This is my translation, may not be accurate, may have errors, but basically understandable, hope to be helpful to everyone. (reproduced please specify the source: This article from Learnhard Blog: http://www.codelast.com/& http://blog.csdn.net/learnhard/)

This tutorial provides a basic C + + Programmer ' s introduction to working with protocol buffers. By walking through creating a simple example application, it shows

· Define message formats in a. proto file.

· Use the protocol buffer compiler.

· Use the C + + protocol buffer API to write and read messages.

This tutorial provides a C + + Programmer's protocol Buffers the basic introduction. By creating a simple sample program, it teaches you how to:

L defines The message format for the. proto file.

L A compiler using protocol buffer .

L use the C + + API of Protoco buffer to read and write messages.

This isn ' t a comprehensive guide to using protocol buffers in C + +. For more detailed reference information, the Protocol Buffer Language Guide, the C + + API reference, the C + + generated Code Guide, and the Encoding Reference.

This article is not about protocol Buffers of the C + + use a comprehensive tutorial. To see more detailed references, read the following:Protocol Buffer Language guide,c++ API reference,c++ generated Code Guide, and /c16>encoding Reference.

Why use Protocol buffers? Why to use protocol Buffers .

The example we ' re going to be a very simple "address Book" application which can read and write people ' s contact detail s to and from a file. Each person in the Address book has a name, an ID, an email address, and a contact phone number.

How do you serialize and retrieve structured the data like this? There are a few ways to solve this problem:

· The raw in-memory data structures can is sent/saved in binary form. Over time, which is a fragile approach, as the receiving/reading code must being compiled with exactly the same memory, Endianness, etc. Also, as files accumulate data in the raw format and copies of software that are wired for this format are spread around, It ' s very hard to extend the format.

· You can invent an ad-hoc way to encode of the data items into a single String–such as encoding 4 ints as "12:3:-23:67". This is a simple and flexible approach, although it does require writing one-off and encoding code, and the parsing G imposes a small run-time cost. This works best for encoding very simple data.

· Serialize the data to XML. This approach can to very attractive since XML is (sort of) human readable and there are binding to for libraries of LAN Guages. This can is a good choice if you are want to share the data with the other applications/projects. However, XML is notoriously spaces intensive, and encoding/decoding it can impose a huge performance penalty on application S. Also, navigating an XML DOM's considerably more complicated than navigating simple fields in a class normally Wou LD be.

Protocol buffers are the flexible, efficient, automated solution to solve exactly. With protocol buffers, your write a. Proto description of the data structure you wish to store. From this, the protocol buffer compiler creates a class that implements automatic encoding and parsing of the Protocol BUF Fer data with an efficient binary format. The generated class provides getters and setters for the fields the protocol buffer and takes care LS of reading and writing the protocol buffer as a unit. Importantly, the protocol buffer format supports the idea of extending the format over time in such a way this code CA n still read data encoded with the "old" format.

(This passage does not translate, uninteresting)

Where to find the Example Code where to find the sample code

The example code is included in the source code package, under the "Examples" directory. Download it here.

The sample code is contained in the source code package in the examples "directory. Click here to download .

defining Your Protocol Format define your own protocol format

To create your address book application and you'll need to start with a. proto file. The definitions in a. proto file are simple:you add a for each data structure you want to serialize, then specify A name and a type for each field in the message. This is the proto file, defines your messages, Addressbook.proto.

to create your address book application, you need to write a . Proto file start. the definition of the . Proto file is simpler: Add a message to each data structure you need to serialize, and then the message each field (field) specifies a name and a type. Here's a file that defines your multiple messages (messages) addressbook.proto:

Package tutorial;

Message person {

Required String name = 1;

Required Int32 id = 2;

Optional String email = 3;

Enum Phonetype {

MOBILE = 0;

home = 1;

WORK = 2;

}

Message PhoneNumber {

Required String number = 1;

Optional Phonetype type = 2 [default = home];

}

Repeated PhoneNumber phone = 4;

}

Message AddressBook {

Repeated person person = 1;

}

As you can, the syntax are similar to C + + or Java. Let's go through the file and the what it does.

as you can see, the syntax is similar to the C + + or Java the syntax. Let's take a look at the role of each part of the document in turn.

 

The. Proto file starts with a package declaration, which helps to prevent naming, conflicts and between different. In C + +, your generated classes is placed in a namespace matching the package name.

. Proto file with a Package The declaration begins. This statement is intended to prevent naming conflicts between different projects. corresponding to C + + , the class you generate with this . Proto file will be placed in the same namespace as the package name.

(reprint please indicate source: This article comes from Learnhard's blog:http://www.codelast.com/& http://blog.csdn.net/learnhard/)

Next, you have your message definitions. A is just a aggregate containing a set of typed fields. Many standard simple data types are available as field types, including bool, int32, float, double, a Nd string. You can also add further structure to your messages by using other message types as field types–in the above the  person message Contains phonenumber messages, while The addressbook message Contains person messages. Can even define message types nested inside other messages–as you can and The phonenumber type is defined Inside person. can also define enum types if you want one of the your fields to have one of a predefined list of Values–here You are want to specify which a phone number can be one of mobile, home, or work.

looking down, there are several messages ( Message ) has been defined. A message is a collection of certain types of fields. Many standard, simple data types can be used as field types, including bool,int32,float, Double, and string. You can also use other messagetypes as your field type--in the example above, the message person is an example of a field type.

The "= 1", "= 2" markers on each element identify the unique "tag" of that field uses in the binary encoding. Tag numbers 1-15 require one less byte to encode than higher-numbers, so as a optimization you can decide to use those TA GS for the commonly used or repeated elements, leaving tags and higher for less-commonly used. Each element in a repeated field requires re-encoding the tag number, so repeated fields are particularly good candidates For this optimization.

at the back of each item, similar to " = 1 "," = 2 "indicates that the field's unique identity is used in binary encoding ( Tag ) ". the number of bytes required for an ID 1~15 encoding is 1 less than the number of bytes used for a larger identification number , so if you are looking for optimizations, you can use 1~ for frequently used or repetitive items. the logo (tag), other frequently used optional items using ≥ Identification (tag). In a repeating field, each entry requires a recoding identification number (tagnumbers), so duplicate fields are particularly useful for this optimization.

Each field must is annotated with one of the following modifiers:

         required:a value for the field must is provided, otherwise the Messa GE would be considered "uninitialized". If libprotobuf is compiled in debug mode, serializing a uninitialized message would cause an assertion failure. In optimized builds, the check are skipped and the message would be written anyway. However, parsing a uninitialized message would always fail (by Returning false from the Parse method). The other than this, a required field behaves exactly like a optional field.

· optional:the field may or May is set. If a optional field value isn ' t set, a default value is used. For simple types, your can specify your own default value, as we ' ve done for the phone number type in the example. Otherwise, a system default is Used:zero to numeric types, the empty string for strings, and false for Bools. For embedded messages, the default value is always the ' default instance ' or ' prototype ' of the message, which has none of Its fields set. Calling the accessor to get the value of a optional (or required) field which has not been explicitly set always returns That field ' s default value.

· Repeated:the field May is repeated any number of the times (including zero). The order of the repeated values would be preserved in the protocol buffer. Repeated fields as dynamically sized arrays.

Each field must be decorated with one of the following modifiers:

L Required: The field value must be supplied, otherwise the corresponding message will be considered "uninitialized." If libprotobuf is compiled in debug mode, serializes an uninitialized message ) will result in an assertion error. In an optimized compilation scenario (such as release), the check is skipped and the message is written. However, parsing an uninitialized message still fails (the parse function returns false). In addition, a required field is no different from a optional field.

L Optional: Either the field value is specified or not. If you do not specify a optional field value, it uses the default value. For simple types, you can specify your own default values, as we did with the type field of phone number in the example above . If you do not specify a default value, the system defaults are used: The default value for the data type is 0, andstring 's default is an empty string,bool The default value is false . For nested messages, the default value is always the "default instance" or "prototype" of the message, that is, none of the fields have a value specified. Calling the access class to the value of a optional(or required) field that does not explicitly specify its valuealways returns the default value for the field.

L repeated: The field repeats n times (n can be 0). The order of the duplicate values is saved in the protocol buffer . You can just consider repeating fields as dynamic sized arrays.

Required is Forever You are should be very careful about marking fields as required. If at some-wish to stop writing or sending a required field, it'll be problematic to change the field to a op tional Field–old readers'll consider messages without this field to is incomplete and may reject or drop them unintent Ionally. You are should consider writing application-specific custom validation routines for your buffers. Some engineers at Google have come to the conclusion, which using required does more harm good; They prefer to use onlyoptional and repeated. However, this view isn't universal.

Required is permanent: When a field is identified as Required , you should be especially careful. If in some cases you do not want to write or send a required field, then changing the field to optional may encounter problems--the old version of the reader: Read, ParsingA message is considered incomplete by a message that does not contain the field, which may deny parsing. In this case, you should consider writing a custom message validation function specifically for your application. Some of Google's engineers have come to the conclusion that using required is more harmful than profit; they prefer to use optional and repeated rather than Required . Of course, this view is not universal.

(reprint please indicate source: This article comes from Learnhard's blog:http://www.codelast.com/& http://blog.csdn.net/learnhard/)

You'll find a complete guide to writing. Proto files–including the possible field types–in the Protocol Buffer Lan Guage Guide. Don ' t go looking for facilities similar to class inheritance, Though–protocol buffers don ' t.

you can in The complete guide to writing a . Proto file (including all possible field types) is found in the Protocol Buffer Language Guide. However, don't try to find features similar to the class inheritance in it, because protocol buffers is not doing this.

compiling Your Protocol buffers Compile your protocol Buffers

Now this you have a. Proto, the next thing your need to be generate the classes you ' ll need to read and write Addressboo K (and hence personand phonenumber) messages. To doing this, you need to run the protocol buffer compiler PROTOC on your. Proto:

1.    If you haven ' t installed the compiler,