ProtoBuf
5. proto3语法详解
5.3 enum类型
定义规则:
proto3支持我们定义枚举类型并使用:
枚举类型的名称采用驼峰命名法且首字母大写,如 MyEnum ,这样的命名方式符合常见的编程规范,能够提高代码的可读性。例如,ColorEnum 、StatusEnum 等都是符合要求的枚举类型名称。
对于枚举常量值的名称,使用全大写字母并用 _ 连接,如 ENUM_CONST = 0; 。这种命名方式可以明确区分常量值和普通变量,增强代码的自解释性。例如,STATUS_SUCCESS = 0; 、COLOR_RED = 1;
我们可以定义⼀个名为 PhoneType 的枚举类型:
enum PhoneType {
MP = 0; // 移动电话
TEL = 1; // 固定电话
}
要注意枚举类型的定义有以下几种规则:
规则 1:0 值常量必须存在且作为第一个元素:在枚举类型中,将 0 值常量置于首位并作为默认值,这是为了保持与 proto2 语义的兼容性。例如:
enum Phone {
DEFAULT_VALUE = 0;
MP = 1;
TEL = 2;
}
这样,当没有明确指定枚举值时,默认就会使用 DEFAULT_VALUE 。
规则 2:枚举类型可以在消息外或消息体内定义(嵌套)在消息外定义的枚举类型可以被多个消息使用,而在消息体内定义的枚举类型则仅能在该消息中使用。消息外定义的示例:
enum Phone {
MP = 0;
TEL = 1;
}
message Message {
Phone phone = 1;
}
消息体内定义(嵌套)的示例:
message Message {
enum Phone {
MP = 0;
TEL = 1;
}
Phone phone = 1;
}
规则 3:枚举的常量值在 32 位整数范围内,但因负值无效因而不建议使用。 由于编码规则的原因,负值在枚举常量值中不太有效且不被推荐使用。例如,有效的常量值可以是 0 到 2147483647 之间的整数。
定义时注意:
将两个 ‘具有相同枚举值名称
’ 的枚举类型放在单个 .proto 文件下测试时,编译后会报错:某某某常量已经被定义!所以这里要注意:
(1)当在单个 .proto 文件中,同级(同层)的枚举类型中,各个枚举类型的常量不能重名。
enum PhoneType {
MP = 0; // 移动电话
TEL = 1; // 固定电话
}
enum PhoneTypeCopy {
MP = 0; // 移动电话 // 编译后报错:MP 已经定义
}
(2)但单个 .proto 文件下,最外层枚举类型和嵌套枚举类型不算同级。
enum PhoneTypeCopy {
MP = 0; // 移动电话 // ⽤法正确
}
message Phone {
string number = 1; // 电话号码
enum PhoneType {
MP = 0; // 移动电话
TEL = 1; // 固定电话
}
}
(3)在多个 .proto 文件的情况下,如果一个文件引入了其他文件,且每个文件都未声明package,每个文件中的枚举类型都在最外层,此时算同级,不能有重名的常量。
// phone1.proto
import "phone1.proto"
enum PhoneType {
MP = 0; // 移动电话 // 编译后报错:MP 已经定义
TEL = 1; // 固定电话
}
// phone2.proto
enum PhoneTypeCopy {
MP = 0; // 移动电话
}
(4)在多个 .proto 文件的情况下,如果一个文件引入了其他文件,而如果每个文件都声明了 package,则不算同级,可以有相同名称的枚举类型。
// phone1.proto
import "phone1.proto"
package phone1;
enum PhoneType {
MP = 0; // 移动电话 // ⽤法正确
TEL = 1; // 固定电话
}
// phone2.proto
package phone2;
enum PhoneTypeCopy {
MP = 0; // 移动电话
}
使用枚举类型向我们的字段中添加电话类型:
syntax = "proto3";
package contacts;
// 联系⼈
message PeopleInfo {
string name = 1; // 姓名
int32 age = 2; // 年龄
message Phone
{
string number = 1; // 电话号码
enum PhoneType
{
MP = 0; // 移动电话
TEL = 1; // 固定电话
}
PhoneType type = 2; // 类型
}
repeated Phone phone = 3; // 电话
}
// 通讯录
message Contacts {
repeated PeopleInfo contacts = 1;
}
protoc编译文件:
protoc --cpp_out=. contacts.proto
查看contacts.pb.h文件,这就是自动生成的有关enum的函数:
bool PeopleInfo_Phone_PhoneType_IsValid(int value)
:这个函数检查一个整数是不是有效的 PeopleInfo_Phone_PhoneType 枚举值,返回是或否。
inline bool PeopleInfo_Phone_PhoneType_Parse(::PROTOBUF_NAMESPACE_ID::ConstStringParam name, PeopleInfo_Phone_PhoneType* value)
:它把一个字符串转成 PeopleInfo_Phone_PhoneType 枚举值存到指定位置,返回转成功还是没成功。
template<typename T> inline const std::string& PeopleInfo_Phone_PhoneType_Name(T enum_t_value)
:这是个模板函数,能得到给定的 PeopleInfo_Phone_PhoneType 枚举值对应的名字字符串。
枚举类型中的成员也有自己的函数:
更新 write.cc :
#include <iostream>
#include <fstream>
#include "contacts.pb.h"
using namespace std;
using namespace contacts;
/**
* 新增联系⼈
*/
void AddPeopleInfo(PeopleInfo *people_info_ptr)
{
cout << "-------------新增联系⼈-------------" << endl;
cout << "请输⼊联系⼈姓名: ";
string name;
getline(cin, name);
people_info_ptr->set_name(name);
cout << "请输⼊联系⼈年龄: ";
int age;
cin >> age;
people_info_ptr->set_age(age);
cin.ignore(256, '\n');
for (int i = 1;; i++)
{
cout << "请输⼊联系⼈电话" << i << "(只输⼊回⻋完成电话新增): ";
string number;
getline(cin, number);
if (number.empty())
{
break;
}
PeopleInfo_Phone *phone = people_info_ptr->add_phone();
phone->set_number(number);
cout << "选择此电话类型 (1、移动电话 2、固定电话) : ";
int type;
cin >> type;
cin.ignore(256, '\n');
switch (type)
{
case 1:
phone->set_type(PeopleInfo_Phone_PhoneType::PeopleInfo_Phone_PhoneType_MP);
break;
case 2:
phone->set_type(PeopleInfo_Phone_PhoneType::PeopleInfo_Phone_PhoneType_TEL);
break;
default:
cout << "⾮法选择,使⽤默认值!" << endl;
break;
}
}
cout << "-----------添加联系⼈成功-----------" << endl;
}
int main(int argc, char *argv[])
{
GOOGLE_PROTOBUF_VERIFY_VERSION;
if (argc != 2)
{
cerr << "Usage: " << argv[0] << " CONTACTS_FILE" << endl;
return -1;
}
Contacts contacts;
// 先读取已存在的 contacts
fstream input(argv[1], ios::in | ios::binary);
if (!input)
{
cout << argv[1] << ": File not found. Creating a new file." << endl;
}
else if (!contacts.ParseFromIstream(&input))
{
cerr << "Failed to parse contacts." << endl;
input.close();
return -1;
}
// 新增⼀个联系⼈
AddPeopleInfo(contacts.add_contacts());
// 向磁盘⽂件写⼊新的 contacts
fstream output(argv[1], ios::out | ios::trunc | ios::binary);
if (!contacts.SerializeToOstream(&output))
{
cerr << "Failed to write contacts." << endl;
input.close();
output.close();
return -1;
}
input.close();
output.close();
google::protobuf::ShutdownProtobufLibrary();
return 0;
}
更新 read.cc :
#include <iostream>
#include <fstream>
#include "contacts.pb.h"
using namespace std;
using namespace contacts;
/**
* 打印联系⼈列表
*/
void PrintfContacts(const Contacts &contacts)
{
for (int i = 0; i < contacts.contacts_size(); ++i)
{
const PeopleInfo &people = contacts.contacts(i);
cout << "------------联系⼈" << i + 1 << "------------" << endl;
cout << "姓名:" << people.name() << endl;
cout << "年龄:" << people.age() << endl;
int j = 1;
for (const PeopleInfo_Phone &phone : people.phone())
{
cout << "电话" << j++ << ": " << phone.number();
cout << " (" << phone.PhoneType_Name(phone.type()) << ")" << endl;
}
}
}
int main(int argc, char *argv[])
{
GOOGLE_PROTOBUF_VERIFY_VERSION;
if (argc != 2)
{
cerr << "Usage: " << argv[0] << "CONTACTS_FILE" << endl;
return -1;
}
// 以⼆进制⽅式读取 contacts
Contacts contacts;
fstream input(argv[1], ios::in | ios::binary);
if (!contacts.ParseFromIstream(&input))
{
cerr << "Failed to parse contacts." << endl;
input.close();
return -1;
}
// 打印 contacts
PrintfContacts(contacts);
input.close();
google::protobuf::ShutdownProtobufLibrary();
return 0;
}
makfile编译:
all:write read
write:write.cc contacts.pb.cc
g++ -o $@ $^ -std=c++11 -lprotobuf
read:read.cc contacts.pb.cc
g++ -o $@ $^ -std=c++11 -lprotobuf
.PHONY:clean
clean:
rm -f write read
5.4 Any类型
当字段被声明为 Any 类型时,它就具有了很大的灵活性,可以容纳各种不同的消息类型。
比如说,您可能有一个消息结构,其中某个字段需要能够存储不同类型的详细信息,这时候就可以使用 Any 类型。
repeated 修饰符用于表示该字段可以是一个元素的列表。
message MyMessage {
repeated google.protobuf.Any details = 1;
}
在实际使用中,Any 类型是由 Google 预先定义好的。当您安装 Protocol Buffers 后,可以在其 include 目录下找到所有 Google 已经定义好的 .proto 文件。
我们使用any 类型的字段来存储地址信息:
syntax = "proto3";
package contacts;
import "google/protobuf/any.proto"; // 引⼊ any.proto ⽂件
// 地址
message Address{
string home_address = 1; // 家庭地址
string unit_address = 2; // 单位地址
}
// 联系⼈
message PeopleInfo {
string name = 1; // 姓名
int32 age = 2; // 年龄
message Phone {
string number = 1; // 电话号码
enum PhoneType {
MP = 0; // 移动电话
TEL = 1; // 固定电话
}
PhoneType type = 2; // 类型
}
repeated Phone phone = 3; // 电话
google.protobuf.Any data = 4;
}
// 通讯录
message Contacts {
repeated PeopleInfo contacts = 1;
}
protoc编译文件:
protoc --cpp_out=. contacts.proto
查看contacts.pb.h文件,这就是自动生成的有关any的函数:
bool has_data() const
:用于检查是否存在 data 。
void clear_data()
:用于清除 data 。
const ::PROTOBUF_NAMESPACE_ID::Any& data() const
:获取不可变的 data 引用。
PROTOBUF_NODISCARD ::PROTOBUF_NAMESPACE_ID::Any* release_data()
:释放并返回 data 指针。
::PROTOBUF_NAMESPACE_ID::Any* mutable_data()
:获取可变的 data 指针。
更新 write.cc :
#include <iostream>
#include <fstream>
#include "contacts.pb.h"
using namespace std;
using namespace contacts;
/**
* 新增联系⼈
*/
void AddPeopleInfo(PeopleInfo *people_info_ptr)
{
cout << "-------------新增联系⼈-------------" << endl;
cout << "请输⼊联系⼈姓名: ";
string name;
getline(cin, name);
people_info_ptr->set_name(name);
cout << "请输⼊联系⼈年龄: ";
int age;
cin >> age;
people_info_ptr->set_age(age);
cin.ignore(256, '\n');
for (int i = 1;; i++)
{
cout << "请输⼊联系⼈电话" << i << "(只输⼊回⻋完成电话新增): ";
string number;
getline(cin, number);
if (number.empty())
{
break;
}
PeopleInfo_Phone *phone = people_info_ptr->add_phone();
phone->set_number(number);
cout << "选择此电话类型 (1、移动电话 2、固定电话) : ";
int type;
cin >> type;
cin.ignore(256, '\n');
switch (type)
{
case 1:
phone -> set_type(PeopleInfo_Phone_PhoneType::PeopleInfo_Phone_PhoneType_MP);
break;
case 2:
phone -> set_type(PeopleInfo_Phone_PhoneType::PeopleInfo_Phone_PhoneType_TEL);
break;
default:
cout << "⾮法选择,使⽤默认值!" << endl;
break;
}
}
Address address;
cout << "请输⼊联系⼈家庭地址: ";
string home_address;
getline(cin, home_address);
address.set_home_address(home_address);
cout << "请输⼊联系⼈单位地址: ";
string unit_address;
getline(cin, unit_address);
address.set_unit_address(unit_address);
google::protobuf::Any *data = people_info_ptr->mutable_data();
data->PackFrom(address);
cout << "-----------添加联系⼈成功-----------" << endl;
}
int main(int argc, char *argv[])
{
GOOGLE_PROTOBUF_VERIFY_VERSION;
if (argc != 2)
{
cerr << "Usage: " << argv[0] << " CONTACTS_FILE" << endl;
return -1;
}
Contacts contacts;
// 先读取已存在的 contacts
fstream input(argv[1], ios::in | ios::binary);
if (!input)
{
cout << argv[1] << ": File not found. Creating a new file." << endl;
}
else if (!contacts.ParseFromIstream(&input))
{
cerr << "Failed to parse contacts." << endl;
input.close();
return -1;
}
// 新增⼀个联系⼈
AddPeopleInfo(contacts.add_contacts());
// 向磁盘⽂件写⼊新的 contacts
fstream output(argv[1], ios::out | ios::trunc | ios::binary);
if (!contacts.SerializeToOstream(&output))
{
cerr << "Failed to write contacts." << endl;
input.close();
output.close();
return -1;
}
input.close();
output.close();
google::protobuf::ShutdownProtobufLibrary();
return 0;
}
更新 read.cc :
#include <iostream>
#include <fstream>
#include "contacts.pb.h"
using namespace std;
using namespace contacts;
/**
* 打印联系⼈列表
*/
void PrintfContacts(const Contacts &contacts)
{
for (int i = 0; i < contacts.contacts_size(); ++i)
{
const PeopleInfo &people = contacts.contacts(i);
cout << "------------联系⼈" << i + 1 << "------------" << endl;
cout << "姓名:" << people.name() << endl;
cout << "年龄:" << people.age() << endl;
int j = 1;
for (const PeopleInfo_Phone &phone : people.phone())
{
cout << "电话" << j++ << ": " << phone.number();
cout << " (" << phone.PhoneType_Name(phone.type()) << ")" << endl;
}
if (people.has_data() && people.data().Is<Address>())
{
Address address;
people.data().UnpackTo(&address);
if (!address.home_address().empty())
{
cout << "家庭地址:" << address.home_address() << endl;
}
if (!address.unit_address().empty())
{
cout << "单位地址:" << address.unit_address() << endl;
}
}
}
}
int main(int argc, char *argv[])
{
GOOGLE_PROTOBUF_VERIFY_VERSION;
if (argc != 2)
{
cerr << "Usage: " << argv[0] << "CONTACTS_FILE" << endl;
return -1;
}
// 以⼆进制⽅式读取 contacts
Contacts contacts;
fstream input(argv[1], ios::in | ios::binary);
if (!contacts.ParseFromIstream(&input))
{
cerr << "Failed to parse contacts." << endl;
input.close();
return -1;
}
// 打印 contacts
PrintfContacts(contacts);
input.close();
google::protobuf::ShutdownProtobufLibrary();
return 0;
}
makfile编译:
all:write read
write:write.cc contacts.pb.cc
g++ -o $@ $^ -std=c++11 -lprotobuf
read:read.cc contacts.pb.cc
g++ -o $@ $^ -std=c++11 -lprotobuf
.PHONY:clean
clean:
rm -f write read