C++ 程式碼產生指南

精確描述協定緩衝區編譯器為任何給定的協定定義產生的 C++ 程式碼。

強調 proto2 和 proto3 產生的程式碼之間的任何差異 - 請注意，這些差異是在本文件中描述的產生的程式碼中，而不是在基本訊息類別/介面中，它們在這兩個版本中是相同的。您應該在閱讀本文檔之前閱讀proto2 語言指南和/或proto3 語言指南。

編譯器調用

當使用 --cpp_out= 命令列標誌調用時，協定緩衝區編譯器會產生 C++ 輸出。 --cpp_out= 選項的參數是您希望編譯器寫入 C++ 輸出的目錄。編譯器會為每個 .proto 檔案輸入建立一個標頭檔和一個實作檔。輸出檔案的名稱是透過取得 .proto 檔案的名稱並進行兩個變更來計算的

  • 擴展名 (.proto) 會被替換為標頭檔的 .pb.h 或實作檔的 .pb.cc。
  • proto 路徑 (使用 --proto_path= 或 -I 命令列標誌指定) 會被替換為輸出路徑 (使用 --cpp_out= 標誌指定)。

因此，舉例來說，假設您如下調用編譯器

protoc --proto_path=src --cpp_out=build/gen src/foo.proto src/bar/baz.proto

編譯器將會讀取 src/foo.proto 和 src/bar/baz.proto 檔案，並產生四個輸出檔案：build/gen/foo.pb.h、build/gen/foo.pb.cc、build/gen/bar/baz.pb.h、build/gen/bar/baz.pb.cc。如果需要，編譯器會自動建立目錄 build/gen/bar，但它*不會*建立 build 或 build/gen；它們必須已經存在。

套件

如果 .proto 檔案包含 package 宣告，則該檔案的全部內容將會被放置在相應的 C++ 命名空間中。例如，假設有 package 宣告

package foo.bar;

檔案中的所有宣告都將位於 foo::bar 命名空間中。

訊息

假設有一個簡單的訊息宣告

message Foo {}

協定緩衝區編譯器會產生一個名為 Foo 的類別，它公開繼承自 google::protobuf::Message。該類別是一個具體類別；沒有未實作的純虛擬方法。 Message 中為虛擬但非純虛擬的方法，可能會或可能不會被 Foo 覆寫，具體取決於最佳化模式。預設情況下，Foo 會為所有方法實作專門的版本，以獲得最大速度。但是，如果 .proto 檔案包含以下行

option optimize_for = CODE_SIZE;

那麼 Foo 將僅覆寫運作所需的最少方法，並依賴基於反射的其餘方法實作。這會顯著減少產生的程式碼大小，但也降低了效能。或者，如果 .proto 檔案包含

option optimize_for = LITE_RUNTIME;

那麼 Foo 將包含所有方法的快速實作，但會實作 google::protobuf::MessageLite 介面，該介面僅包含 Message 方法的子集。特別是，它不支援描述符或反射。但是，在這種模式下，產生的程式碼只需要連結到 libprotobuf-lite.so (Windows 上為 libprotobuf-lite.lib)，而不是 libprotobuf.so (libprotobuf.lib)。「精簡」程式庫比完整程式庫小得多，更適合行動電話等資源受限的系統。

您*不應該*建立自己的 Foo 子類別。如果您將此類別子類化並覆寫虛擬方法，則覆寫可能會被忽略，因為許多產生的方法呼叫會去虛擬化以提高效能。

Message 介面定義了一些方法，讓您可以檢查、操作、讀取或寫入整個訊息，包括從二進位字串解析和序列化為二進位字串。

  • bool ParseFromString(const string& data)：從給定的序列化二進位字串 (也稱為線路格式) 解析訊息。
  • bool SerializeToString(string* output) const：將給定的訊息序列化為二進位字串。
  • string DebugString()：傳回一個字串，其中包含 proto 的 text_format 表示法 (僅應用於偵錯)。

除了這些方法之外，Foo 類別還定義了以下方法

  • Foo()：預設建構子。
  • ~Foo()：預設解構子。
  • Foo(const Foo& other)：複製建構子。
  • Foo(Foo&& other)：移動建構子。
  • Foo& operator=(const Foo& other)：指派運算子。
  • Foo& operator=(Foo&& other)：移動指派運算子。
  • void Swap(Foo* other)：與另一個訊息交換內容。
  • const UnknownFieldSet& unknown_fields() const：傳回在解析此訊息時遇到的未知欄位集。如果在 .proto 檔案中指定了 option optimize_for = LITE_RUNTIME，則傳回類型會變更為 std::string&。
  • UnknownFieldSet* mutable_unknown_fields()：傳回指向在解析此訊息時遇到的可變未知欄位集的指標。如果在 .proto 檔案中指定了 option optimize_for = LITE_RUNTIME，則傳回類型會變更為 std::string*。

該類別還定義了以下靜態方法

  • static const Descriptor* descriptor()：傳回類型的描述符。其中包含有關該類型的資訊，包括它有哪些欄位及其類型。這可以用於 反射，以程式設計方式檢查欄位。
  • static const Foo& default_instance()：傳回 Foo 的 const 單例執行個體，該執行個體與新建構的 Foo 執行個體相同 (因此所有單數欄位都未設定，並且所有重複欄位都是空的)。請注意，訊息的預設執行個體可以透過呼叫其 New() 方法來用作工廠。

產生的檔名

保留關鍵字會在產生的輸出中附加底線。

例如，以下 proto3 定義語法

message MyMessage {
  string false = 1;
  string myFalse = 2;
}

產生以下部分輸出

  void clear_false_() ;
  const std::string& false_() const;
  void set_false_(Arg_&& arg, Args_... args);
  std::string* mutable_false_();
  PROTOBUF_NODISCARD std::string* release_false_();
  void set_allocated_false_(std::string* ptr);

  void clear_myfalse() ;
  const std::string& myfalse() const;
  void set_myfalse(Arg_&& arg, Args_... args);
  std::string* mutable_myfalse();
  PROTOBUF_NODISCARD std::string* release_myfalse();
  void set_allocated_myfalse(std::string* ptr);

巢狀類型

可以在另一個訊息中宣告訊息。例如

message Foo {
  message Bar {}
}

在這種情況下，編譯器會產生兩個類別：Foo 和 Foo_Bar。此外，編譯器會在 Foo 中產生一個 typedef，如下所示

typedef Foo_Bar Bar;

這表示您可以像使用巢狀類別 Foo::Bar 一樣使用巢狀類型的類別。但是，請注意，C++ 不允許巢狀類型進行前向宣告。如果您想在另一個檔案中前向宣告 Bar 並使用該宣告，則必須將其識別為 Foo_Bar。

欄位

除了前一節描述的方法之外，協議緩衝區編譯器還會為 .proto 檔案中定義的訊息內的每個欄位產生一組存取器方法。這些方法是小寫/蛇形命名法，例如 has_foo() 和 clear_foo()。

除了存取器方法之外，編譯器還會為每個欄位產生一個整數常數，其中包含其欄位編號。常數名稱是字母 k，後面接著轉換為駝峰式命名的欄位名稱，最後加上 FieldNumber。例如，給定欄位 optional int32 foo_bar = 5;，編譯器會產生常數 static const int kFooBarFieldNumber = 5;。

對於傳回 const 參考的欄位存取器，當下次對訊息進行修改存取時，該參考可能會失效。這包括呼叫任何欄位的非 const 存取器、呼叫任何從 Message 繼承的非 const 方法，或通過其他方式修改訊息（例如，使用訊息作為 Swap() 的引數）。相應地，只有在沒有對訊息進行修改存取的情況下，傳回參考的位址才能保證在不同呼叫存取器時相同。

對於傳回指標的欄位存取器，當下次對訊息進行修改或非修改存取時，該指標可能會失效。這包括，無論是否為 const，呼叫任何欄位的任何存取器、呼叫任何從 Message 繼承的方法或通過其他方式存取訊息（例如，使用複製建構函式複製訊息）。相應地，傳回指標的值永遠不能保證在兩個不同的存取器呼叫中相同。

可選的數值欄位 (proto2 和 proto3)

對於以下任一欄位定義

optional int32 foo = 1;
required int32 foo = 1;

編譯器將產生以下存取器方法

  • bool has_foo() const：如果欄位已設定，則傳回 true。
  • int32 foo() const：傳回欄位的目前值。如果欄位未設定，則傳回預設值。
  • void set_foo(int32 value)：設定欄位的值。呼叫此方法後，has_foo() 將傳回 true，而 foo() 將傳回 value。
  • void clear_foo()：清除欄位的值。呼叫此方法後，has_foo() 將傳回 false，而 foo() 將傳回預設值。

對於其他數值欄位類型（包括 bool），int32 會根據純量值類型表替換為相應的 C++ 類型。

隱式存在數值欄位 (proto3)

對於以下欄位定義

int32 foo = 1;  // no field label specified, defaults to implicit presence.

編譯器將產生以下存取器方法

  • int32 foo() const：傳回欄位的目前值。如果欄位未設定，則傳回 0。
  • void set_foo(int32 value)：設定欄位的值。呼叫此方法後，foo() 將傳回 value。
  • void clear_foo()：清除欄位的值。呼叫此方法後，foo() 將傳回 0。

對於其他數值欄位類型（包括 bool），int32 會根據純量值類型表替換為相應的 C++ 類型。

可選的字串/位元組欄位 (proto2 和 proto3)

對於以下任一欄位定義

optional string foo = 1;
required string foo = 1;
optional bytes foo = 1;
required bytes foo = 1;

編譯器將產生以下存取器方法

  • bool has_foo() const：如果欄位已設定，則傳回 true。
  • const string& foo() const：傳回欄位的目前值。如果欄位未設定，則傳回預設值。
  • void set_foo(const string& value)：設定欄位的值。呼叫此方法後，has_foo() 將傳回 true，而 foo() 將傳回 value 的副本。
  • void set_foo(string&& value)（C++11 及更高版本）：設定欄位的值，從傳遞的字串移動。呼叫此方法後，has_foo() 將傳回 true，而 foo() 將傳回 value 的副本。
  • void set_foo(const char* value)：使用 C 樣式的以 null 終止的字串設定欄位的值。呼叫此方法後，has_foo() 將傳回 true，而 foo() 將傳回 value 的副本。
  • void set_foo(const char* value, int size)：與上述相同，但字串大小是明確給定的，而不是通過尋找 null 終止位元組來確定。
  • string* mutable_foo()：傳回指向儲存欄位值的可變 string 物件的指標。如果欄位在呼叫之前未設定，則傳回的字串將為空（而非預設值）。呼叫此方法後，has_foo() 將傳回 true，而 foo() 將傳回寫入給定字串的任何值。
  • void clear_foo()：清除欄位的值。呼叫此方法後，has_foo() 將傳回 false，而 foo() 將傳回預設值。
  • void set_allocated_foo(string* value)：將 string 物件設定到欄位，並在存在時釋放先前的欄位值。如果 string 指標不是 NULL，則訊息會取得已配置 string 物件的所有權，且 has_foo() 將傳回 true。訊息可以隨時刪除已配置的 string 物件，因此對該物件的參考可能會失效。否則，如果 value 是 NULL，則行為與呼叫 clear_foo() 相同。
  • string* release_foo()：釋放欄位的所有權，並傳回 string 物件的指標。呼叫此方法後，呼叫者取得已配置 string 物件的所有權，has_foo() 將傳回 false，而 foo() 將傳回預設值。

隱式存在字串/位元組欄位 (proto3)

對於以下任一欄位定義

string foo = 1;  // no field label specified, defaults to implicit presence.
bytes foo = 1;

編譯器將產生以下存取器方法

  • const string& foo() const：傳回欄位的目前值。如果欄位未設定，則傳回空字串/空位元組。
  • void set_foo(const string& value)：設定欄位的值。呼叫此方法後，foo() 將傳回 value 的副本。
  • void set_foo(string&& value)（C++11 及更高版本）：設定欄位的值，從傳遞的字串移動。呼叫此方法後，foo() 將傳回 value 的副本。
  • void set_foo(const char* value)：使用 C 樣式的以 null 終止的字串設定欄位的值。呼叫此方法後，foo() 將傳回 value 的副本。
  • void set_foo(const char* value, int size)：與上述相同，但字串大小是明確給定的，而不是通過尋找 null 終止位元組來確定。
  • string* mutable_foo()：傳回指向儲存欄位值的可變 string 物件的指標。如果欄位在呼叫之前未設定，則傳回的字串將為空。呼叫此方法後，foo() 將傳回寫入給定字串的任何值。
  • void clear_foo()：清除欄位的值。呼叫此方法後，foo() 將傳回空字串/空位元組。
  • void set_allocated_foo(string* value)：將 string 物件設定到欄位，並在存在時釋放先前的欄位值。如果 string 指標不是 NULL，則訊息會取得已配置 string 物件的所有權。訊息可以隨時刪除已配置的 string 物件，因此對該物件的參考可能會失效。否則，如果 value 是 NULL，則行為與呼叫 clear_foo() 相同。
  • string* release_foo()：釋放欄位的所有權，並傳回 string 物件的指標。呼叫此方法後，呼叫者取得已配置 string 物件的所有權，而 foo() 將傳回空字串/空位元組。

支援 Cord 的單一位元組欄位

v23.0 新增了對單數 bytes 欄位（包括oneof 欄位）的 absl::Cord 的支援。單數 string、repeated string 和 repeated bytes 欄位不支援使用 Cord。

若要設定單數 bytes 欄位以使用 absl::Cord 儲存資料，請使用以下語法

optional bytes foo = 25 [ctype=CORD];
bytes bar = 26 [ctype=CORD];

repeated bytes 欄位不適用 cord。Protoc 會忽略這些欄位上的 [ctype=CORD] 設定。

編譯器將產生以下存取器方法

  • const ::absl::Cord& foo() const：傳回欄位的目前值。如果欄位未設定，則傳回空的 Cord (proto3) 或預設值 (proto2)。
  • void set_foo(const ::absl::Cord& value)：設定欄位的值。呼叫此方法後，foo() 將傳回 value。
  • void set_foo(::absl::string_view value)：設定欄位的值。呼叫此方法後，foo() 將以 absl::Cord 的形式傳回 value。
  • void clear_foo()：清除欄位的值。呼叫此方法後，foo() 將傳回空的 Cord (proto3) 或預設值 (proto2)。
  • bool has_foo()：如果欄位已設定，則傳回 true。

可選的列舉欄位 (proto2 和 proto3)

給定列舉類型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

對於以下任一欄位定義

optional Bar foo = 1;
required Bar foo = 1;

編譯器將產生以下存取器方法

  • bool has_foo() const：如果欄位已設定，則傳回 true。
  • Bar foo() const：傳回欄位的目前值。如果欄位未設定，則傳回預設值。
  • void set_foo(Bar value)：設定欄位的值。呼叫此方法後，has_foo() 將傳回 true，而 foo() 將傳回 value。在偵錯模式下（即，未定義 NDEBUG），如果 value 與為 Bar 定義的任何值都不匹配，此方法將中止程序。
  • void clear_foo()：清除欄位的值。呼叫此方法後，has_foo() 將傳回 false，而 foo() 將傳回預設值。

隱式存在列舉欄位 (proto3)

給定列舉類型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

對於此欄位定義

Bar foo = 1;  // no field label specified, defaults to implicit presence.

編譯器將產生以下存取器方法

  • Bar foo() const：傳回欄位的目前值。如果欄位未設定，則傳回預設值 (0)。
  • void set_foo(Bar value)：設定欄位的值。呼叫此方法後，foo() 將傳回 value。
  • void clear_foo()：清除欄位的值。呼叫此方法後，foo() 將傳回預設值。

可選的嵌入訊息欄位 (proto2 和 proto3)

給定訊息類型

message Bar {}

對於以下任一欄位定義

//proto2
optional Bar foo = 1;
required Bar foo = 1;

//proto3
Bar foo = 1;

編譯器將產生以下存取器方法

  • bool has_foo() const：如果欄位已設定，則傳回 true。
  • const Bar& foo() const：傳回欄位的目前值。如果欄位未設定，則傳回未設定任何欄位的 Bar（可能是 Bar::default_instance()）。
  • Bar* mutable_foo()：傳回指向儲存欄位值的可變 Bar 物件的指標。如果欄位在呼叫之前未設定，則傳回的 Bar 將不會設定任何欄位（即，它將與新配置的 Bar 相同）。呼叫此方法後，has_foo() 將傳回 true，而 foo() 將傳回對同一個 Bar 執行個體的參考。
  • void clear_foo()：清除欄位的值。呼叫此方法後，has_foo() 將傳回 false，而 foo() 將傳回預設值。
  • void set_allocated_foo(Bar* bar)：將 Bar 物件設定到欄位，並在存在時釋放先前的欄位值。如果 Bar 指標不是 NULL，則訊息會取得已配置 Bar 物件的所有權，且 has_foo() 將傳回 true。否則，如果 Bar 是 NULL，則行為與呼叫 clear_foo() 相同。
  • Bar* release_foo()：釋放欄位的所有權，並傳回 Bar 物件的指標。呼叫此方法後，呼叫者取得已配置 Bar 物件的所有權，has_foo() 將傳回 false，而 foo() 將傳回預設值。

重複的數值欄位

對於此欄位定義

repeated int32 foo = 1;

編譯器將產生以下存取器方法

  • int foo_size() const：傳回目前欄位中的元素數量。若要檢查是否為空集合，請考慮使用基礎 RepeatedField 中的 empty() 方法，而不是此方法。
  • int32 foo(int index) const：傳回指定從零開始的索引處的元素。使用超出 [0, foo_size()) 範圍的索引呼叫此方法會產生未定義的行為。
  • void set_foo(int index, int32 value)：設定指定從零開始的索引處的元素值。
  • void add_foo(int32 value)：將具有給定值的新元素附加到欄位的末尾。
  • void clear_foo()：從欄位中移除所有元素。呼叫此方法後，foo_size() 將傳回零。
  • const RepeatedField<int32>& foo() const：傳回儲存欄位元素的基礎 RepeatedField。此容器類別提供類似 STL 的迭代器和其他方法。
  • RepeatedField<int32>* mutable_foo()：傳回指向儲存欄位元素的可變基礎 RepeatedField 的指標。此容器類別提供類似 STL 的迭代器和其他方法。

對於其他數值欄位類型（包括 bool），int32 會根據純量值類型表替換為相應的 C++ 類型。

重複的字串欄位

對於以下任一欄位定義

repeated string foo = 1;
repeated bytes foo = 1;

編譯器將產生以下存取器方法

  • int foo_size() const：傳回目前欄位中的元素數量。若要檢查是否為空集合，請考慮使用基礎 RepeatedField 中的 empty() 方法，而不是此方法。
  • const string& foo(int index) const：傳回指定從零開始的索引處的元素。使用超出 [0, foo_size()-1] 範圍的索引呼叫此方法會產生未定義的行為。
  • void set_foo(int index, const string& value)：設定指定從零開始的索引處的元素值。
  • void set_foo(int index, const char* value)：使用 C 風格的 null 字元結尾字串，設定指定從零開始的索引位置的元素值。
  • void set_foo(int index, const char* value, int size)：與上述類似，但字串大小是明確給定的，而不是透過尋找 null 字元結尾位元組來決定。
  • string* mutable_foo(int index)：傳回可變的 string 物件的指標，該物件儲存指定從零開始的索引位置的元素值。使用超出 [0, foo_size()) 範圍的索引呼叫此方法會產生未定義的行為。
  • void add_foo(const string& value)：將具有指定值的新元素附加到欄位的末尾。
  • void add_foo(const char* value)：使用 C 風格的 null 字元結尾字串，將新元素附加到欄位的末尾。
  • void add_foo(const char* value, int size)：與上述類似，但字串大小是明確給定的，而不是透過尋找 null 字元結尾位元組來決定。
  • string* add_foo()：將新的空字串元素附加到欄位的末尾，並傳回指向該元素的指標。
  • void clear_foo()：從欄位中移除所有元素。呼叫此方法後，foo_size() 將傳回零。
  • const RepeatedPtrField<string>& foo() const：傳回儲存欄位元素的底層 RepeatedPtrField。此容器類別提供類似 STL 的迭代器和其他方法。
  • RepeatedPtrField<string>* mutable_foo()：傳回指向儲存欄位元素的可變底層 RepeatedPtrField 的指標。此容器類別提供類似 STL 的迭代器和其他方法。

重複的列舉欄位

給定列舉類型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

對於此欄位定義

repeated Bar foo = 1;

編譯器將產生以下存取器方法

  • int foo_size() const：傳回目前欄位中的元素數量。若要檢查是否為空集合，請考慮使用基礎 RepeatedField 中的 empty() 方法，而不是此方法。
  • Bar foo(int index) const：傳回指定從零開始的索引位置的元素。使用超出 [0, foo_size()) 範圍的索引呼叫此方法會產生未定義的行為。
  • void set_foo(int index, Bar value)：設定指定從零開始的索引位置的元素值。在偵錯模式（即未定義 NDEBUG）下，如果 value 與為 Bar 定義的任何值都不符，此方法會中止程序。
  • void add_foo(Bar value)：將具有指定值的新元素附加到欄位的末尾。在偵錯模式（即未定義 NDEBUG）下，如果 value 與為 Bar 定義的任何值都不符，此方法會中止程序。
  • void clear_foo()：從欄位中移除所有元素。呼叫此方法後，foo_size() 將傳回零。
  • const RepeatedField<int>& foo() const：傳回儲存欄位元素的底層 RepeatedField。此容器類別提供類似 STL 的迭代器和其他方法。
  • RepeatedField<int>* mutable_foo()：傳回指向儲存欄位元素的可變底層 RepeatedField 的指標。此容器類別提供類似 STL 的迭代器和其他方法。

重複的嵌入訊息欄位

給定訊息類型

message Bar {}

針對此欄位定義

repeated Bar foo = 1;

編譯器將產生以下存取器方法

  • int foo_size() const：傳回目前欄位中的元素數量。若要檢查是否為空集合，請考慮使用基礎 RepeatedField 中的 empty() 方法，而不是此方法。
  • const Bar& foo(int index) const：傳回指定從零開始的索引位置的元素。使用超出 [0, foo_size()) 範圍的索引呼叫此方法會產生未定義的行為。
  • Bar* mutable_foo(int index)：傳回可變的 Bar 物件的指標，該物件儲存指定從零開始的索引位置的元素值。使用超出 [0, foo_size()) 範圍的索引呼叫此方法會產生未定義的行為。
  • Bar* add_foo()：將新元素附加到欄位的末尾，並傳回指向該元素的指標。傳回的 Bar 是可變的，並且其所有欄位都不會設定（即它會與新分配的 Bar 相同）。
  • void clear_foo()：從欄位中移除所有元素。呼叫此方法後，foo_size() 將傳回零。
  • const RepeatedPtrField<Bar>& foo() const：傳回儲存欄位元素的底層 RepeatedPtrField。此容器類別提供類似 STL 的迭代器和其他方法。
  • RepeatedPtrField<Bar>* mutable_foo()：傳回指向儲存欄位元素的可變底層 RepeatedPtrField 的指標。此容器類別提供類似 STL 的迭代器和其他方法。

Oneof 數值欄位

針對此 oneof 欄位定義

oneof example_name {
    int32 foo = 1;
    ...
}

編譯器將產生以下存取器方法

  • bool has_foo() const：如果 oneof 情況為 kFoo，則傳回 true。
  • int32 foo() const：如果 oneof 情況為 kFoo，則傳回欄位的目前值。否則，傳回預設值。
  • void set_foo(int32 value):
    • 如果設定了同一個 oneof 中的任何其他 oneof 欄位，則會呼叫 clear_example_name()。
    • 設定此欄位的值，並將 oneof 情況設定為 kFoo。
    • has_foo() 將傳回 true，foo() 將傳回 value，而 example_name_case() 將傳回 kFoo。
  • void clear_foo():
    • 如果 oneof 情況不是 kFoo，則不會變更任何內容。
    • 如果 oneof 情況是 kFoo，則清除欄位的值和 oneof 情況。has_foo() 將傳回 false，foo() 將傳回預設值，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。

對於其他數值欄位類型（包括 bool），int32 會根據 純量值類型表 替換為對應的 C++ 類型。

Oneof 字串欄位

針對任何這些 oneof 欄位定義

oneof example_name {
    string foo = 1;
    ...
}
oneof example_name {
    bytes foo = 1;
    ...
}

編譯器將產生以下存取器方法

  • bool has_foo() const：如果 oneof 情況為 kFoo，則傳回 true。
  • const string& foo() const：如果 oneof 情況為 kFoo，則傳回欄位的目前值。否則，傳回預設值。
  • void set_foo(const string& value):
    • 如果設定了同一個 oneof 中的任何其他 oneof 欄位，則會呼叫 clear_example_name()。
    • 設定此欄位的值，並將 oneof 情況設定為 kFoo。
    • has_foo() 將傳回 true，foo() 將傳回 value 的複本，而 example_name_case() 將傳回 kFoo。
  • void set_foo(const char* value):
    • 如果設定了同一個 oneof 中的任何其他 oneof 欄位，則會呼叫 clear_example_name()。
    • 使用 C 風格的 null 字元結尾字串設定欄位的值，並將 oneof 情況設定為 kFoo。
    • has_foo() 將傳回 true，foo() 將傳回 value 的複本，而 example_name_case() 將傳回 kFoo。
  • void set_foo(const char* value, int size)：與上述相同，但字串大小是明確給定的，而不是通過尋找 null 終止位元組來確定。
  • string* mutable_foo():
    • 如果設定了同一個 oneof 中的任何其他 oneof 欄位，則會呼叫 clear_example_name()。
    • 將 oneof 情況設定為 kFoo，並傳回指向儲存欄位值的可變字串物件的指標。如果呼叫之前 oneof 情況不是 kFoo，則傳回的字串將為空（不是預設值）。
    • has_foo() 將傳回 true，foo() 將傳回寫入給定字串的任何值，而 example_name_case() 將傳回 kFoo。
  • void clear_foo():
    • 如果 oneof 情況不是 kFoo，則不會變更任何內容。
    • 如果 oneof 情況是 kFoo，則釋放欄位並清除 oneof 情況。has_foo() 將傳回 false，foo() 將傳回預設值，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。
  • void set_allocated_foo(string* value):
    • 呼叫 clear_example_name()。
    • 如果字串指標不是 NULL：將字串物件設定到欄位，並將 oneof 情況設定為 kFoo。訊息取得已分配的字串物件的所有權，has_foo() 將傳回 true，而 example_name_case() 將傳回 kFoo。
    • 如果字串指標是 NULL，則 has_foo() 將傳回 false，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。
  • string* release_foo():
    • 如果 oneof 情況不是 kFoo，則傳回 NULL。
    • 清除 oneof 情況，釋放欄位的所有權，並傳回字串物件的指標。呼叫此方法後，呼叫者取得已分配的字串物件的所有權，has_foo() 將傳回 false，foo() 將傳回預設值，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。

Oneof 列舉欄位

給定列舉類型

enum Bar {
  BAR_UNSPECIFIED = 0;
  BAR_VALUE = 1;
  BAR_OTHER_VALUE = 2;
}

針對 oneof 欄位定義

oneof example_name {
    Bar foo = 1;
    ...
}

編譯器將產生以下存取器方法

  • bool has_foo() const：如果 oneof 情況為 kFoo，則傳回 true。
  • Bar foo() const：如果 oneof 情況是 kFoo，則傳回欄位的目前值。否則，傳回預設值。
  • void set_foo(Bar value):
    • 如果設定了同一個 oneof 中的任何其他 oneof 欄位，則會呼叫 clear_example_name()。
    • 設定此欄位的值，並將 oneof 情況設定為 kFoo。
    • has_foo() 將傳回 true，foo() 將傳回 value，而 example_name_case() 將傳回 kFoo。
    • 在偵錯模式（即未定義 NDEBUG）下，如果 value 與為 Bar 定義的任何值都不符，此方法會中止程序。
  • void clear_foo():
    • 如果 oneof 情況不是 kFoo，則不會變更任何內容。
    • 如果 oneof 情況是 kFoo，則清除欄位的值和 oneof 情況。has_foo() 將傳回 false，foo() 將傳回預設值，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。

Oneof 嵌入訊息欄位

給定訊息類型

message Bar {}

針對 oneof 欄位定義

oneof example_name {
    Bar foo = 1;
    ...
}

編譯器將產生以下存取器方法

  • bool has_foo() const：如果 oneof 情況為 kFoo，則傳回 true。
  • const Bar& foo() const：如果 oneof 情況是 kFoo，則傳回欄位的目前值。否則，傳回一個未設定任何欄位的 Bar（可能是 Bar::default_instance()）。
  • Bar* mutable_foo():
    • 如果設定了同一個 oneof 中的任何其他 oneof 欄位，則會呼叫 clear_example_name()。
    • 將 oneof 情況設定為 kFoo，並傳回指向儲存欄位值的可變 Bar 物件的指標。如果呼叫之前 oneof 情況不是 kFoo，則傳回的 Bar 將不會設定任何欄位（即它會與新分配的 Bar 相同）。
    • 呼叫此方法後，has_foo() 將傳回 true，foo() 將傳回對同一個 Bar 執行個體的參考，而 example_name_case() 將傳回 kFoo。
  • void clear_foo():
    • 如果 oneof 情況不是 kFoo，則不會變更任何內容。
    • 如果 oneof 情況等於 kFoo，則釋放欄位並清除 oneof 情況。has_foo() 將傳回 false，foo() 將傳回預設值，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。
  • void set_allocated_foo(Bar* bar):
    • 呼叫 clear_example_name()。
    • 如果 Bar 指標不是 NULL：將 Bar 物件設定到欄位，並將 oneof 情況設定為 kFoo。訊息取得已分配的 Bar 物件的所有權，has_foo() 將傳回 true，而 example_name_case() 將傳回 kFoo。
    • 如果指標是 NULL，則 has_foo() 將傳回 false，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。（行為類似於呼叫 clear_example_name()）
  • Bar* release_foo():
    • 如果 oneof 情況不是 kFoo，則傳回 NULL。
    • 如果 oneof 情況是 kFoo，則清除 oneof 情況，釋放欄位的所有權，並傳回 Bar 物件的指標。呼叫此方法後，呼叫者取得已分配的 Bar 物件的所有權，has_foo() 將傳回 false，foo() 將傳回預設值，而 example_name_case() 將傳回 EXAMPLE_NAME_NOT_SET。

Map 欄位

針對此 map 欄位定義

map<int32, int32> weight = 1;

編譯器將產生以下存取器方法

  • const google::protobuf::Map<int32, int32>& weight();：傳回不可變的 Map。
  • google::protobuf::Map<int32, int32>* mutable_weight();：傳回可變的 Map。

google::protobuf::Map 是協定緩衝區中用於儲存 map 欄位的特殊容器類型。如您從其下方的介面所見，它使用 std::map 和 std::unordered_map 方法的常用子集。

注意： 這些 map 是無序的。

template<typename Key, typename T> {
class Map {
  // Member types
  typedef Key key_type;
  typedef T mapped_type;
  typedef MapPair< Key, T > value_type;

  // Iterators
  iterator begin();
  const_iterator begin() const;
  const_iterator cbegin() const;
  iterator end();
  const_iterator end() const;
  const_iterator cend() const;
  // Capacity
  int size() const;
  bool empty() const;

  // Element access
  T& operator[](const Key& key);
  const T& at(const Key& key) const;
  T& at(const Key& key);

  // Lookup
  bool contains(const Key& key) const;
  int count(const Key& key) const;
  const_iterator find(const Key& key) const;
  iterator find(const Key& key);

  // Modifiers
  pair<iterator, bool> insert(const value_type& value);
  template<class InputIt>
  void insert(InputIt first, InputIt last);
  size_type erase(const Key& Key);
  iterator erase(const_iterator pos);
  iterator erase(const_iterator first, const_iterator last);
  void clear();

  // Copy
  Map(const Map& other);
  Map& operator=(const Map& other);
}

新增資料最簡單的方式是使用一般的 map 語法，例如

std::unique_ptr<ProtoName> my_enclosing_proto(new ProtoName);
(*my_enclosing_proto->mutable_weight())[my_key] = my_value;

pair<iterator, bool> insert(const value_type& value) 會隱式地對 value_type 實例進行深層複製。將新值插入 google::protobuf::Map 最有效率的方式如下：

T& operator[](const Key& key): map[new_key] = new_mapped;

將 google::protobuf::Map 與標準 map 搭配使用

google::protobuf::Map 支援與 std::map 和 std::unordered_map 相同的迭代器 API。如果您不想直接使用 google::protobuf::Map，您可以透過執行以下操作將 google::protobuf::Map 轉換為標準 map：

std::map<int32, int32> standard_map(message.weight().begin(),
                                    message.weight().end());

請注意，這會對整個 map 進行深層複製。

您也可以透過以下方式從標準 map 建構 google::protobuf::Map：

google::protobuf::Map<int32, int32> weight(standard_map.begin(), standard_map.end());

剖析未知值

在傳輸時，.proto map 相當於每個鍵/值對的 map 條目訊息，而 map 本身則是 map 條目的重複欄位。與一般訊息類型一樣，剖析過的 map 條目訊息可能會包含未知欄位：例如，在定義為 map<int32, string> 的 map 中，類型為 int64 的欄位。

如果 map 條目訊息的傳輸格式中存在未知欄位，這些欄位將會被捨棄。

如果 map 條目訊息的傳輸格式中存在未知的列舉值，則 proto2 和 proto3 的處理方式會有所不同。在 proto2 中，整個 map 條目訊息會被放入包含訊息的未知欄位集。在 proto3 中，它會被放入 map 欄位中，就像它是已知的列舉值一樣。

Any

假設有如下的 Any 欄位：

import "google/protobuf/any.proto";

message ErrorStatus {
  string message = 1;
  google.protobuf.Any details = 2;
}

在我們產生的程式碼中，details 欄位的 getter 會傳回 google::protobuf::Any 的實例。這提供了以下特殊方法來打包和解包 Any 的值：

class Any {
 public:
  // Packs the given message into this Any using the default type URL
  // prefix “type.googleapis.com”. Returns false if serializing the message failed.
  bool PackFrom(const google::protobuf::Message& message);

  // Packs the given message into this Any using the given type URL
  // prefix. Returns false if serializing the message failed.
  bool PackFrom(const google::protobuf::Message& message,
                const string& type_url_prefix);

  // Unpacks this Any to a Message. Returns false if this Any
  // represents a different protobuf type or parsing fails.
  bool UnpackTo(google::protobuf::Message* message) const;

  // Returns true if this Any represents the given protobuf type.
  template<typename T> bool Is() const;
}

Oneof

假設有如下的 oneof 定義：

oneof example_name {
    int32 foo_int = 4;
    string foo_string = 9;
    ...
}

編譯器將會產生以下的 C++ 列舉類型：

enum ExampleNameCase {
  kFooInt = 4,
  kFooString = 9,
  EXAMPLE_NAME_NOT_SET = 0
}

此外，它將會產生這些方法：

  • ExampleNameCase example_name_case() const：傳回列舉，指出設定了哪個欄位。如果沒有設定任何欄位，則傳回 EXAMPLE_NAME_NOT_SET。
  • void clear_example_name()：如果設定的 oneof 欄位使用指標 (訊息或字串)，則釋放物件，並將 oneof 案例設定為 EXAMPLE_NAME_NOT_SET。

列舉

假設有如下的列舉定義：

enum Foo {
  VALUE_A = 0;
  VALUE_B = 5;
  VALUE_C = 1234;
}

protocol buffer 編譯器將會產生一個名為 Foo 的 C++ 列舉類型，其中包含相同的值集。此外，編譯器將會產生以下函式：

  • const EnumDescriptor* Foo_descriptor()：傳回類型的描述器，其中包含有關此列舉類型定義哪些值的資訊。
  • bool Foo_IsValid(int value)：如果給定的數值與 Foo 定義的值之一相符，則傳回 true。在上面的範例中，如果輸入為 0、5 或 1234，則會傳回 true。
  • const string& Foo_Name(int value)：傳回給定數值的名稱。如果不存在此類值，則傳回空字串。如果多個值具有此數值，則傳回定義的第一個值。在上面的範例中，Foo_Name(5) 將會傳回 "VALUE_B"。
  • bool Foo_Parse(const string& name, Foo* value)：如果 name 是此列舉的有效值名稱，則將該值指派給 value 並傳回 true。否則傳回 false。在上面的範例中，Foo_Parse("VALUE_C", &some_foo) 將會傳回 true，並將 some_foo 設定為 1234。
  • const Foo Foo_MIN：列舉的最小有效值（範例中的 VALUE_A）。
  • const Foo Foo_MAX：列舉的最大有效值（範例中的 VALUE_C）。
  • const int Foo_ARRAYSIZE：始終定義為 Foo_MAX + 1。

將整數轉換為 proto2 列舉時請務必小心。如果將整數轉換為 proto2 列舉值，則整數必須是該列舉的有效值之一，否則結果可能未定義。如有疑問，請使用產生的 Foo_IsValid() 函式來測試轉換是否有效。將 proto2 訊息的列舉類型欄位設定為無效值可能會導致判斷提示失敗。如果在剖析 proto2 訊息時讀取到無效的列舉值，則會將其視為未知欄位。這些語意已在 proto3 中變更。只要將任何整數轉換為 proto3 列舉值適合 int32，就是安全的。在剖析 proto3 訊息時，也會保留無效的列舉值，並由列舉欄位存取器傳回。

在 switch 陳述式中使用 proto3 列舉時請務必小心。Proto3 列舉是開放列舉類型，其可能的值超出指定符號的範圍。在剖析 proto3 訊息時，將會保留無法辨識的列舉值，並由列舉欄位存取器傳回。即使列出所有已知欄位，沒有預設案例的 proto3 列舉 switch 陳述式也無法捕捉所有案例。這可能會導致非預期的行為，包括資料損毀和執行階段當機。請務必新增預設案例，或在 switch 陳述式之外明確呼叫 Foo_IsValid(int) 來處理未知的列舉值。

您可以在訊息類型內定義列舉。在此情況下，protocol buffer 編譯器會產生程式碼，使其看起來像是列舉類型本身宣告在訊息的類別內。Foo_descriptor() 和 Foo_IsValid() 函式宣告為靜態方法。實際上，列舉類型本身及其值是在全域範圍內宣告的，並帶有修飾名稱，並且使用 typedef 和一系列常數定義匯入類別的範圍。這樣做只是為了規避宣告順序的問題。請勿依賴修飾的頂層名稱；請假裝列舉確實巢狀在訊息類別中。

擴充 (僅限 proto2)

假設有具有擴充範圍的訊息：

message Foo {
  extensions 100 to 199;
}

protocol buffer 編譯器將會為 Foo 產生一些額外的方法：HasExtension()、ExtensionSize()、ClearExtension()、GetExtension()、SetExtension()、MutableExtension()、AddExtension()、SetAllocatedExtension() 和 ReleaseExtension()。這些方法中的每一個方法都會將擴充識別碼（如下所述）作為其第一個參數，該識別碼會識別擴充欄位。其餘參數和傳回值與為與擴充識別碼類型相同的正常（非擴充）欄位產生的對應存取器方法完全相同。（GetExtension() 對應於沒有特殊前置詞的存取器。）

假設有擴充定義：

extend Foo {
  optional int32 bar = 123;
  repeated int32 repeated_bar = 124;
  optional Bar message_bar = 125;
}

對於單數擴充欄位 bar，protocol buffer 編譯器會產生一個名為 bar 的「擴充識別碼」，您可以使用 Foo 的擴充存取器來存取此擴充，如下所示：

Foo foo;
assert(!foo.HasExtension(bar));
foo.SetExtension(bar, 1);
assert(foo.HasExtension(bar));
assert(foo.GetExtension(bar) == 1);
foo.ClearExtension(bar);
assert(!foo.HasExtension(bar));

對於訊息擴充欄位 message_bar，如果未設定該欄位，則 foo.GetExtension(message_bar) 會傳回未設定任何欄位的 Bar（可能是 Bar::default_instance()）。

同樣地，對於重複的擴充欄位 repeated_bar，編譯器會產生一個名為 repeated_bar 的擴充識別碼，您也可以將其與 Foo 的擴充存取器搭配使用：

Foo foo;
for (int i = 0; i < kSize; ++i) {
  foo.AddExtension(repeated_bar, i)
}
assert(foo.ExtensionSize(repeated_bar) == kSize)
for (int i = 0; i < kSize; ++i) {
  assert(foo.GetExtension(repeated_bar, i) == i)
}

（擴充識別碼的確切實作很複雜，並且涉及範本的神奇用法，但是，您不需要擔心擴充識別碼如何運作即可使用它們。）

擴充可以宣告在另一種類型內。例如，常見的模式是執行如下操作：

message Baz {
  extend Foo {
    optional Baz foo_ext = 124;
  }
}

在此情況下，擴充識別碼 foo_ext 宣告在 Baz 內。它可以使用如下：

Foo foo;
Baz* baz = foo.MutableExtension(Baz::foo_ext);
FillInMyBaz(baz);

Arena 配置

Arena 配置是 C++ 專用的功能，可協助您最佳化記憶體使用量並在處理 protocol buffer 時提高效能。在 .proto 中啟用 Arena 配置會為您的 C++ 產生程式碼新增其他用於處理 arena 的程式碼。您可以在Arena 配置指南中找到有關 Arena 配置 API 的詳細資訊。

服務

如果 .proto 檔案包含以下行：

option cc_generic_services = true;

然後，protocol buffer 編譯器將會根據本節所述的檔案中找到的服務定義產生程式碼。但是，產生的程式碼可能不理想，因為它不與任何特定的 RPC 系統相關聯，因此需要比針對一個系統量身打造的程式碼更多的間接層級。如果您不希望產生此程式碼，請將此行新增至檔案：

option cc_generic_services = false;

如果未提供上述任何一行，則選項預設為 false，因為一般服務已遭到淘汰。（請注意，在 2.4.0 之前，選項預設為 true）

基於 .proto 語言服務定義的 RPC 系統應提供外掛程式來產生適用於該系統的程式碼。這些外掛程式可能需要停用抽象服務，以便它們可以產生相同名稱的自己的類別。

本節的其餘部分描述當啟用抽象服務時，protocol buffer 編譯器會產生什麼。

介面

假設有服務定義：

service Foo {
  rpc Bar(FooRequest) returns(FooResponse);
}

protocol buffer 編譯器將會產生一個類別 Foo 來表示此服務。Foo 將會為服務定義中定義的每個方法提供一個虛擬方法。在此情況下，方法 Bar 定義為：

virtual void Bar(RpcController* controller, const FooRequest* request,
                 FooResponse* response, Closure* done);

這些參數與 Service::CallMethod() 的參數等效，只是 method 引數是隱含的，而 request 和 response 指定其確切的類型。

這些產生的方法是虛擬的，但不是純虛擬的。預設實作只會使用錯誤訊息呼叫 controller->SetFailed()，指出該方法尚未實作，然後叫用 done 回呼。在實作自己的服務時，您必須子類別化此產生的服務，並適當地實作其方法。

Foo 子類別化 Service 介面。protocol buffer 編譯器會自動產生 Service 方法的實作，如下所示：

  • GetDescriptor：傳回服務的ServiceDescriptor。
  • CallMethod：根據提供的方法描述器判斷正在呼叫哪個方法，並直接呼叫它，將要求和回應訊息物件向下轉換為正確的類型。
  • GetRequestPrototype 和 GetResponsePrototype：傳回給定方法正確類型的要求或回應的預設實例。

還會產生以下靜態方法：

  • static ServiceDescriptor descriptor()：傳回類型的描述器，其中包含有關此服務有哪些方法以及其輸入和輸出類型的資訊。

Stub

protocol buffer 編譯器也會產生每個服務介面的「Stub」實作，由希望將要求傳送至實作服務的伺服器的用戶端使用。對於 Foo 服務（如上所述），將會定義 Stub 實作 Foo_Stub。與巢狀訊息類型一樣，會使用 typedef，以便 Foo_Stub 也可以稱為 Foo::Stub。

Foo_Stub 是 Foo 的子類別，也實作以下方法：

  • Foo_Stub(RpcChannel* channel)：建構一個新的 stub，該 stub 會在給定的通道上傳送要求。
  • Foo_Stub(RpcChannel* channel, ChannelOwnership ownership)：建構一個新的 stub，該 stub 會在給定的通道上傳送要求，並可能擁有該通道。如果 ownership 為 Service::STUB_OWNS_CHANNEL，則在刪除 stub 物件時也會刪除通道。
  • RpcChannel* channel()：傳回此 stub 的通道，如傳遞至建構函式。

此外，存根 (stub) 將每個服務的方法實作為通道 (channel) 的包裝函式。呼叫其中一個方法只會呼叫 channel->CallMethod()。

Protocol Buffer 程式庫不包含 RPC 實作。但是，它包含了將產生的服務類別連接到您選擇的任何任意 RPC 實作所需的所有工具。您只需要提供 RpcChannel 和 RpcController 的實作即可。請參閱 service.h 的文件以取得更多資訊。

外掛程式插入點

想要擴展 C++ 程式碼產生器輸出的程式碼產生器外掛程式可以使用給定的插入點名稱插入以下類型的程式碼。除非另有說明，否則每個插入點都會出現在 .pb.cc 檔案和 .pb.h 檔案中。

  • includes：包含指令。
  • namespace_scope：屬於檔案的套件/命名空間，但不屬於任何特定類別的宣告。出現在所有其他命名空間範圍程式碼之後。
  • global_scope：屬於頂層，在檔案的命名空間之外的宣告。出現在檔案的最後面。
  • class_scope:TYPENAME：屬於訊息類別的成員宣告。TYPENAME 是完整的 proto 名稱，例如 package.MessageType。出現在類別中所有其他 public 宣告之後。此插入點僅出現在 .pb.h 檔案中。

請勿產生依賴標準程式碼產生器宣告的私有類別成員的程式碼，因為這些實作細節可能會在未來版本的 Protocol Buffers 中變更。