Protocol Buffers

https://protobuf.dev
Admin
Protocol Buffers are Google's language-neutral, platform-neutral, extensible mechanism for...
Tokens:2,074,138
Snippets:21,995
Trust Score:10
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install Go Protobuf plugin with go install

Source: https://protobuf.dev/getting-started/gotutorial

Run this command to install the protoc-gen-go plugin. It will be installed in $GOBIN (defaulting to $GOPATH/bin) and must be in your $PATH for protoc to find it.

```bash
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
```

--------------------------------

### Package example

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Example of a package declaration.

```protobuf
package foo.bar;
```

--------------------------------

### foo/bar.proto example

Source: https://protobuf.dev/news/2023-04-20

Example proto file defining a simple message Bar.

```protobuf
// foo/bar.proto

syntax = "proto2";

message Bar {}

```

--------------------------------

### Install open2opaque and goimports

Source: https://protobuf.dev/reference/go/opaque-migration

Install the open2opaque migration tool and goimports using go install.

```bash
go install google.golang.org/open2opaque@latest
go install golang.org/x/tools/cmd/goimports@latest
```

--------------------------------

### Option examples

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Examples of option declarations, including a custom option and a feature setting.

```protobuf
option java_package = "com.example.foo";
option features.enum_type = CLOSED;
```

--------------------------------

### Service example

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Example service definition with a single RPC method.

```protobuf
service SearchService {
  rpc Search (SearchRequest) returns (SearchResponse);
}
```

--------------------------------

### foo/baz.proto example

Source: https://protobuf.dev/news/2023-04-20

Example proto file that imports bar.proto and uses the Bar message.

```protobuf
// foo/baz.proto

syntax = "proto2";

import "bar.proto";

message Baz {
  optional Bar bar = 1;
}

```

--------------------------------

### Extend example

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Example of extending a message Foo with a field bar.

```protobuf
extend Foo {
  int32 bar = 126;
}
```

--------------------------------

### Syntax Statement Example

Source: https://protobuf.dev/reference/protobuf/proto3-spec

Example of a syntax statement declaring proto3.

```protobuf
syntax = "proto3";

```

--------------------------------

### Example directory structure for proto files

Source: https://protobuf.dev/programming-guides/proto3

Shows a directory structure example with main.proto and common/timestamp.proto under the protos directory. This is used to illustrate how to set --proto_path.

```text
my_project/
├── protos/
│   ├── main.proto
│   └── common/
│       └── timestamp.proto
```

--------------------------------

### Example .proto file

Source: https://protobuf.dev/reference/protobuf/proto2-spec

Example .proto file showing proto2 syntax, including enums with aliases, nested messages, maps, extensions, and groups.

```protobuf
syntax = "proto2";
import public "other.proto";
option java_package = "com.example.foo";
enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 1;
  EAA_FINISHED = 2 [(custom_option) = "hello world"];
}
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    required int64 ival = 1;
  }
  repeated Inner inner_message = 2;
  optional EnumAllowingAlias enum_field = 3;
  map<int32, string> my_map = 4;
  extensions 20 to 30;
}
message Foo {
  optional group GroupMessage = 1 {
    optional bool a = 1;
  }
}

```

--------------------------------

### Install protoc with apt on Linux

Source: https://protobuf.dev/installation

Installs protoc using apt or apt-get and verifies the version is 33.0 or newer.

```bash
apt install -y protobuf-compiler
protoc --version  # Ensure compiler version is 33.0+
```

--------------------------------

### Example .proto file with extension

Source: https://protobuf.dev/reference/java/api-docs/com/google/protobuf/ExtensionRegistry.html

Shows a .proto file defining a message Foo with an extension range and an extension bar. This is the prerequisite for the Java example that registers and parses the extension.

```proto
 option java_class = "MyProto";

 message Foo {
   extensions 1000 to max;
 }

 extend Foo {
   optional int32 bar;
 }

```

--------------------------------

### Install protoc with Winget on Windows

Source: https://protobuf.dev/installation

Installs protoc using Winget and verifies the version is 33.0 or newer.

```powershell
> winget install protobuf
> protoc --version # Ensure compiler version is 33.0+
```

--------------------------------

### Import statement examples

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Examples of import statements using the public and option modifiers.

```protobuf
import public "other.proto";
import option "custom_option.proto";
```

--------------------------------

### ZeroCopyInputStream example: read file and print to stdout

Source: https://protobuf.dev/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream

Complete example of reading a file using FileInputStream and ZeroCopyInputStream::Next() to print contents to stdout.

```cpp
// Read in a file and print its contents to stdout.
int fd = open("myfile", O_RDONLY);
ZeroCopyInputStream* input = new FileInputStream(fd);

const void* buffer;
int size;
while (input->Next(&buffer, &size)) {
  cout.write(buffer, size);
}

delete input;
close(fd);

```

--------------------------------

### Import statement example

Source: https://protobuf.dev/reference/protobuf/edition-2023-spec

Example of importing another .proto file with the public modifier.

```protobuf
import public "other.proto";
```

--------------------------------

### Usage Examples for google::protobuf::Map

Source: https://protobuf.dev/reference/cpp/cpp-generated

Examples of adding data to a map field, efficient insertion, and converting between google::protobuf::Map and standard maps.

```APIDOC
## Usage Examples for google::protobuf::Map

### Description
Examples of adding data to a map field, efficient insertion, and converting between google::protobuf::Map and standard maps.

### Adding Data Using Normal Map Syntax
```cpp
std::unique_ptr<ProtoName> my_enclosing_proto(new ProtoName);
(*my_enclosing_proto->mutable_weight())[my_key] = my_value;
```

### Efficient Insertion
`pair<iterator, bool> insert(const value_type& value)` will implicitly cause a deep copy of the `value_type` instance. The most efficient way to insert a new value into a `google::protobuf::Map` is as follows:
```cpp
T& operator[](const Key& key): map[new_key] = new_mapped;
```

### Converting to a Standard Map
```cpp
std::map<int32, int32> standard_map(message.weight().begin(), message.weight().end());
```
Note that this will make a deep copy of the entire map.

### Constructing from a Standard Map
```cpp
google::protobuf::Map<int32, int32> weight(standard_map.begin(), standard_map.end());
```
```

--------------------------------

### Get or create nested Struct and ListValue

Source: https://protobuf.dev/reference/python/python-generated

Use get_or_create_struct() to get or create a nested struct and get_or_create_list() to get or create a list. The example shows setting a subkey and creating a list.

```python
struct.get_or_create_struct("key4")["subkey"] = 11.0
struct.get_or_create_list("key5")

```

--------------------------------

### Chaining get calls without nil checks

Source: https://protobuf.dev/reference/go/go-generated

Example showing how to chain get calls without intermediate nil checks, using the generated accessor methods.

```go
var m *Concert // defaults to nil
log.Infof("GetFoundingYear() = %d (no panic!)", m.GetHeadliner().GetFoundingYear())

```

--------------------------------

### Example .proto file

Source: https://protobuf.dev/reference/protobuf/edition-2023-spec

Complete example of a .proto file using Edition 2023, demonstrating edition declaration, imports, options, enums with aliases, nested messages, maps, extensions, reserved fields, and feature settings.

```protobuf
edition = "2023";
import public "other.proto";
option java_package = "com.example.foo";
enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 1;
  EAA_FINISHED = 2 [(custom_option) = "hello world"];
}
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    int64 ival = 1 [features.field_presence = LEGACY_REQUIRED];
  }
  repeated Inner inner_message = 2;
  EnumAllowingAlias enum_field = 3;
  map<int32, string> my_map = 4;
  extensions 20 to 30;
  reserved reserved_field;
}
message Foo {
  message GroupMessage {
    bool a = 1;
  }
  GroupMessage groupmessage = [features.message_encoding = DELIMITED];
}

```

--------------------------------

### Using generated_factory to get a prototype message

Source: https://protobuf.dev/reference/cpp/api-docs/google.protobuf.message

This example shows how to use MessageFactory::generated_factory() to get the prototype message for a compiled-in type FooMessage. It demonstrates that the factory returns the default instance for the descriptor.

```cpp
MessageFactory::generated_factory()->GetPrototype(
  FooMessage::descriptor()) == FooMessage::default_instance()
```

--------------------------------

### EnumReservedRange.Builder

Source: https://protobuf.dev/reference/java/api-docs/com/google/protobuf/DescriptorProtos.EnumDescriptorProto.EnumReservedRange.html

Builder class for constructing EnumReservedRange instances. Provides methods to set and get the start and end fields of the reserved range.

```APIDOC
## EnumReservedRange.Builder

### Description
Builder for `EnumReservedRange` protobuf message. Allows setting the inclusive start and end values of the reserved range.

### Methods
- `setStart(int value)` - Sets the start field.
- `setEnd(int value)` - Sets the end field.
- `getStart()` - Returns the start value.
- `getEnd()` - Returns the end value.
- `build()` - Builds the `EnumReservedRange` instance.

### Fields
- `start` (int) - The inclusive start of the range.
- `end` (int) - The inclusive end of the range.
```

--------------------------------

### Convert Duration to timedelta

Source: https://protobuf.dev/reference/python/python-generated

Use FromNanoseconds() to set a Duration and ToTimedelta() to get a Python timedelta. The example asserts the seconds and microseconds components.

```python
duration_message.FromNanoseconds(1999999999)
td = duration_message.ToTimedelta()
assert td.seconds == 1
assert td.microseconds == 999999

```

--------------------------------

### Example .proto file

Source: https://protobuf.dev/reference/protobuf/proto3-spec

Shows a complete proto3 file with syntax declaration, public import, java_package option, an enum with aliases, and a message with nested types, repeated fields, and a map.

```proto
syntax = "proto3";
import public "other.proto";
option java_package = "com.example.foo";
enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 1;
  EAA_FINISHED = 2 [(custom_option) = "hello world"];
}
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    int64 ival = 1;
  }
  repeated Inner inner_message = 2;
  EnumAllowingAlias enum_field = 3;
  map<int32, string> my_map = 4;
}

```

--------------------------------

### EnumReservedRange

Source: https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/EnumDescriptorProto/EnumReservedRange.html

The EnumReservedRange class represents a range of reserved numeric values. It provides methods to get and set the inclusive start and end values.

```APIDOC
## EnumReservedRange

### Description
Represents a range of reserved numeric values in an enum. Reserved values may not be used by entries in the same enum. Reserved ranges may not overlap. This is distinct from DescriptorProto.ReservedRange in that it is inclusive such that it can appropriately represent the entire int32 domain.

### Methods

#### getStart()
- **Return type**: int
- **Description**: Returns the inclusive start value of the reserved range.

#### setStart(int $var)
- **Parameters**:
  - **$var** (int) - The inclusive start value.
- **Return type**: $this
- **Description**: Sets the inclusive start value of the reserved range.

#### getEnd()
- **Return type**: int
- **Description**: Returns the inclusive end value of the reserved range.

#### setEnd(int $var)
- **Parameters**:
  - **$var** (int) - The inclusive end value.
- **Return type**: $this
- **Description**: Sets the inclusive end value of the reserved range.

#### hasStart()
- **Description**: Checks if the start value has been set.

#### clearStart()
- **Description**: Clears the start value.

#### hasEnd()
- **Description**: Checks if the end value has been set.

#### clearEnd()
- **Description**: Clears the end value.

### Properties
- **$start** (int) - Inclusive start value.
- **$end** (int) - Inclusive end value.

```

--------------------------------

### Extension usage example (Rust)

Source: https://protobuf.dev/reference/rust/rust-generated

Rust example showing how to use generated ExtensionId constants to check, set, clear, and mutate extensions on a message. It demonstrates scalar and repeated extension access using methods like has, set, get, clear, and get_mut.

```rust
use protobuf::prelude::*;

let mut foo = xyz::Foo::new();

// Check and set scalar extension
assert!(!xyz::INT32_EXT.has(&foo));
xyz::INT32_EXT.set(&mut foo, 42);
assert!(xyz::INT32_EXT.has(&foo));
assert_eq!(xyz::INT32_EXT.get(&foo), 42);

// Clear scalar extension
xyz::INT32_EXT.clear(&mut foo);
assert!(!xyz::INT32_EXT.has(&foo));

// Working with repeated extensions
{
    let mut rep_mut = xyz::REPEATED_INT32_EXT.get_mut(&mut foo);
    rep_mut.push(1);
    rep_mut.push(2);
}
assert_eq!(xyz::REPEATED_INT32_EXT.get(&foo).len(), 2);
assert_eq!(xyz::REPEATED_INT32_EXT.get(&foo).get(0), Some(1));
```

--------------------------------

### ExtensionRange Class

Source: https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/DescriptorProto/ExtensionRange.html

The ExtensionRange class represents a protobuf message with fields start, end, and options. It provides methods to get and set these fields, as well as inherited methods for serialization and merging.

```APIDOC
## ExtensionRange Class

### Description
The ExtensionRange class is a generated protobuf message for `google.protobuf.DescriptorProto.ExtensionRange`. It contains fields for the start (inclusive), end (exclusive), and options of an extension range.

### Properties
- **$start** (int) - Inclusive start of the range.
- **$end** (int) - Exclusive end of the range.
- **$options** (ExtensionRangeOptions|null) - Optional options for the extension range.

### Methods

#### getStart()
Returns the start value (inclusive).

#### setStart(int $var)
Sets the start value (inclusive). Returns $this.

#### getEnd()
Returns the end value (exclusive).

#### setEnd(int $var)
Sets the end value (exclusive). Returns $this.

#### getOptions()
Returns the options field (ExtensionRangeOptions|null).

#### setOptions(ExtensionRangeOptions $var)
Sets the options field. Returns $this.

#### hasStart()
Checks if the start field is set.

#### clearStart()
Clears the start field.

#### hasEnd()
Checks if the end field is set.

#### clearEnd()
Clears the end field.

#### hasOptions()
Checks if the options field is set.

#### clearOptions()
Clears the options field.

#### __construct($data = NULL)
Constructor. Initializes the message with optional data.

#### serializeToString()
Serializes the message to a binary string.

#### serializeToJsonString($options = 0)
Serializes the message to a JSON string.

#### mergeFrom(object $msg)
Merges the contents of another message into this one.

#### mergeFromString(string $data)
Parses a protocol buffer from a string and merges into this message.

#### mergeFromJsonString(string $data, bool $ignore_unknown = false)
Parses a JSON string to protobuf message and merges.

#### mergeFromArray(array $array)
Populates the message from a user-supplied PHP array.

#### clear()
Clears all fields.

#### discardUnknownFields()
Clears all unknown fields previously parsed.

#### parseFromStream($input)
Parses a message from a stream.

#### serializeToStream($output)
Serializes the message to a stream.

#### parseFromJsonStream($input, $ignore_unknown)
Parses a message from a JSON stream.

#### serializeToJsonStream($output)
Serializes the message to a JSON stream.

#### byteSize()
Returns the size of the serialized message.

#### jsonByteSize($options = 0)
Returns the size of the JSON serialized message.

#### __debugInfo()
Provides debug information.

#### readWrapperValue($member)
Reads a wrapper value (inherited from Message).

#### writeWrapperValue($member, $value)
Writes a wrapper value (inherited from Message).

#### readOneof($number)
Reads a oneof field (inherited from Message).

#### hasOneof($number)
Checks if a oneof field is set (inherited from Message).

#### writeOneof($number, $value)
Writes a oneof field (inherited from Message).

#### whichOneof($oneof_name)
Returns the field number of the set oneof field (inherited from Message).

```

--------------------------------

### Setting and getting singular message fields

Source: https://protobuf.dev/reference/php/php-generated

Demonstrates that message fields default to null and must be explicitly created. The first example creates a sub-message before setting a field; the second fails because the sub-message is not created.

```php
$m = new MyMessage();
$m->setZ(new SubMessage());
$m->getZ()->setFoo(42);

$m2 = new MyMessage();
$m2->getZ()->setFoo(42);  // FAILS with an exception
```

--------------------------------

### CodedOutputStream direct buffer write example

Source: https://protobuf.dev/reference/cpp/api-docs/google.protobuf.io.coded_stream

Shows how to use CodedOutputStream to write a magic number, a varint-encoded string length, and raw text. It first attempts to get a direct buffer for the entire encoded size; if successful, it uses the ToArray methods to write directly to the buffer, otherwise it falls back to bound-checked writes. The example includes the necessary include and namespace declarations.

```cpp
#include <google/protobuf/io/coded_stream.h>
namespace google::protobuf::io

CodedOutputStream* coded_output = new CodedOutputStream(raw_output);
int magic_number = 1234;
char text[] = "Hello world!";

int coded_size = sizeof(magic_number) +
CodedOutputStream::VarintSize32(strlen(text)) +
strlen(text);


uint8* buffer =
coded_output->GetDirectBufferForNBytesAndAdvance(coded_size);
if (buffer != nullptr) {
// The output stream has enough space in the buffer: write directly to
// the array.
buffer = CodedOutputStream::WriteLittleEndian32ToArray(magic_number,
buffer);
buffer = CodedOutputStream::WriteVarint32ToArray(strlen(text), buffer);
buffer = CodedOutputStream::WriteRawToArray(text, strlen(text), buffer);
} else {
// Make bound-checked writes, which will ask the underlying stream for
// more space as needed.
coded_output->WriteLittleEndian32(magic_number);
coded_output->WriteVarint32(strlen(text));
coded_output->WriteRaw(text, strlen(text));
}


delete coded_output;
```

--------------------------------

### Kotlin getters with and without nullable submessages

Source: https://protobuf.dev/design-decisions/nullable-getters-setters

Shows the difference between non-nullable getters (which return the default value) and nullable getters (which return null) in Kotlin. The third example shows a verbose workaround to get the default value.

```kotlin
// With our API where getters are always non-nullable:
msg.child.grandchild.foo == 72

// With nullable submessages the ?. operator fails to get the default value:
msg?.child?.grandchild?.foo == null

// Or verbosely duplicating the default value at the usage site:
(msg?.child?.grandchild?.foo ?: 72)
```

--------------------------------

### Service Definition Example

Source: https://protobuf.dev/programming-guides/style

Shows the recommended TitleCase naming for service and method names in a .proto file.

```protobuf
service FooService {
  rpc GetSomething(GetSomethingRequest) returns (GetSomethingResponse);
  rpc ListSomething(ListSomethingRequest) returns (ListSomethingResponse);
}
```

--------------------------------

### Example .proto file using edition 2024

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

A complete example .proto file that demonstrates edition 2024 syntax: edition declaration, public and option imports, java_package option, enum with allow_alias and custom options, nested messages, field presence features, extensions, reserved fields, and message encoding feature.

```proto
edition = "2024";
import public "other.proto";
import option "custom_option.proto";
option java_package = "com.example.foo";
enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 1;
  EAA_FINISHED = 2 [(custom_option) = "hello world"];
}
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    int64 ival = 1 [features.field_presence = LEGACY_REQUIRED];
  }
  repeated Inner inner_message = 2;
  EnumAllowingAlias enum_field = 3;
  map<int32, string> my_map = 4;
  extensions 20 to 30;
  reserved reserved_field;
}
message Foo {
  message GroupMessage {
    bool a = 1;
  }
  GroupMessage groupmessage = [features.message_encoding = DELIMITED];
}

```

--------------------------------

### Set up WORKSPACE for protobuf with clang-cl

Source: https://protobuf.dev/support/migration

Bazel workspace setup for protobuf with clang-cl configuration. Add these lines to your WORKSPACE file.

```starlark
load("//:protobuf_deps.bzl", "PROTOBUF_MAVEN_ARTIFACTS", "protobuf_deps")

protobuf_deps()

load("@rules_cc//cc:repositories.bzl", "rules_cc_dependencies", "rules_cc_toolchains")

rules_cc_dependencies()

rules_cc_toolchains()

```

--------------------------------

### Oneof example

Source: https://protobuf.dev/reference/protobuf/proto2-spec

Example of a oneof field with two alternatives.

```proto
oneof foo {
    string name = 4;
    SubMessage sub_message = 9;
}

```

--------------------------------

### Example .proto files for import path issue

Source: https://protobuf.dev/news/v23

Two .proto files that demonstrate a potential import path ambiguity when using the new serialized descriptor.

```proto
// foo/bar.proto

syntax = "proto2";

message Bar {}

```

```proto
// foo/baz.proto

syntax = "proto2";

import "bar.proto";

message Baz {
  optional Bar bar = 1;
}

```

--------------------------------

### Proto file header: syntax, package, and import

Source: https://protobuf.dev/getting-started/csharptutorial

Starts the addressbook.proto file with the proto3 syntax, a package declaration to prevent naming conflicts, and an import for the Timestamp type.

```proto
syntax = "proto3";
package tutorial;

import "google/protobuf/timestamp.proto";

```

--------------------------------

### Group field example

Source: https://protobuf.dev/reference/protobuf/proto2-spec

Example of a repeated group field with nested fields.

```proto
repeated group Result = 1 {
    required string url = 1;
    optional string title = 2;
    repeated string snippets = 3;
}

```

--------------------------------

### Proto3 syntax example

Source: https://protobuf.dev/news/2023-06-29

Original proto3 definition file showing explicit presence, implicit presence, packed repeated field, and open enum.

```protobuf
// proto3 file
syntax = "proto3";

message Player {
  // in proto3, optional fields have explicit presence
  optional string name = 1;
  // in proto3 no specified field rule defaults to implicit presence
  int32 id = 2;
  // in proto3 this is packed by default
  repeated int32 scores = 3;

  enum Handed {
    HANDED_UNSPECIFIED = 0,
    HANDED_LEFT = 1,
    HANDED_RIGHT = 2,
    HANDED_AMBIDEXTROUS = 3,
  }

  // in proto3 enums are open
  optional Handed handed = 4;
}

```

--------------------------------

### Implementing MyService in C++

Source: https://protobuf.dev/reference/cpp/api-docs/google.protobuf.service

Example implementation of the generated abstract interface MyService. The Foo method reads the request, fills the response, and calls done->Run() to signal completion.

```cpp
class MyServiceImpl : public MyService {
 public:
  MyServiceImpl() {}
  ~MyServiceImpl() {}

  // implements MyService ---------------------------------------

  void Foo(google::protobuf::RpcController* controller,
           const MyRequest* request,
           MyResponse* response,
           Closure* done) {
    // ... read request and fill in response ...
    done->Run();
  }
};
```

--------------------------------

### Enum example

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Example enum definition with allow_alias option and a field with a custom option.

```protobuf
enum EnumAllowingAlias {
  option allow_alias = true;
  EAA_UNSPECIFIED = 0;
  EAA_STARTED = 1;
  EAA_RUNNING = 2 [(custom_option) = "hello world"];
}
```

--------------------------------

### Call a service method using GetRequestPrototype and GetResponsePrototype

Source: https://protobuf.dev/reference/cpp/api-docs/google.protobuf.service

Shows how to obtain the default request and response prototypes for a method, create mutable instances with Message::New(), parse input into the request, and invoke the method via CallMethod(). The example uses a stub's GetRequestPrototype() and GetResponsePrototype() methods.

```cpp
const MethodDescriptor* method =
  service->GetDescriptor()->FindMethodByName("Foo");
Message* request  = stub->GetRequestPrototype (method)->New();
Message* response = stub->GetResponsePrototype(method)->New();
request->ParseFromString(input);
service->CallMethod(method, *request, response, callback);
```

--------------------------------

### ZeroCopyOutputStream example: copy file using read() and FileOutputStream

Source: https://protobuf.dev/reference/cpp/api-docs/google.protobuf.io.zero_copy_stream

Complete example of copying a file using plain read() for input and a ZeroCopyOutputStream (FileOutputStream) for output, including handling EOF with BackUp().

```cpp
// Copy the contents of "infile" to "outfile", using plain read() for
// "infile" but a ZeroCopyOutputStream for "outfile".
int infd = open("infile", O_RDONLY);
int outfd = open("outfile", O_WRONLY);
ZeroCopyOutputStream* output = new FileOutputStream(outfd);

void* buffer;
int size;
while (output->Next(&buffer, &size)) {
  int bytes = read(infd, buffer, size);
  if (bytes < size) {
    // Reached EOF.
    output->BackUp(size - bytes);
    break;
  }
}

delete output;
close(infd);
close(outfd);

```

--------------------------------

### Message definition example

Source: https://protobuf.dev/reference/protobuf/proto3-spec

Example message with a custom option, a nested message, and a map field.

```proto
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    int64 ival = 1;
  }
  map<int32, string> my_map = 2;
}

```

--------------------------------

### Example proto file (edition 2023)

Source: https://protobuf.dev/reference/php/php-generated

Proto file defining a message in package foo.bar. Used with the compiler invocation to produce build/gen/Foo/Bar/MyMessage.php.

```proto
edition = "2023";
package foo.bar;
message MyMessage {}
```

--------------------------------

### Compile .proto to C# with protoc --csharp_out

Source: https://protobuf.dev/getting-started/csharptutorial

Run the protoc compiler to generate C# classes from addressbook.proto. Use -I for source directory and --csharp_out for destination. Generates Addressbook.cs.

```bash
protoc -I=$SRC_DIR --csharp_out=$DST_DIR $SRC_DIR/addressbook.proto

```

--------------------------------

### Message example

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Example message definition with nested message, map field, and extensions range.

```protobuf
message Outer {
  option (my_option).a = true;
  message Inner {   // Level 2
    required int64 ival = 1;
  }
  map<int32, string> my_map = 2;
  extensions 20 to 30;
}
```

--------------------------------

### Reserved examples

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Examples of reserved statements: a range of field numbers and a list of field names.

```protobuf
reserved 2, 15, 9 to 11;
reserved foo, bar;
```

--------------------------------

### Define a protobuf extension with declaration in container message

Source: https://protobuf.dev/programming-guides/proto2

Shows the three proto files for defining an extension: the extension definition in kittens/video_ext.proto, the container message with a reserved range and verification=DECLARATION in media/user_content.proto, and the updated container message with an explicit declaration for the extension. The extension file imports the container's file, but the container does not import the extension file. The declaration specifies field number 126, fully-qualified name .kittens.kitten_videos, type .kittens.Video, and repeated cardinality.

```proto
// file kittens/video_ext.proto

import "kittens/video.proto";
import "media/user_content.proto";

package kittens;

// This extension allows kitten videos in a media.UserContent message.
extend media.UserContent {
  // Video is a message imported from kittens/video.proto
  repeated Video kitten_videos = 126;
}

```

```proto
// file media/user_content.proto

package media;

// A container message to hold stuff that a user has created.
message UserContent {
  // Set verification to `DECLARATION` to enforce extension declarations for all
  // extensions in this range.
  extensions 100 to 199 [verification = DECLARATION];
}

```

```proto
// A container message to hold stuff that a user has created.
message UserContent {
  extensions 100 to 199 [
    declaration = {
      number: 126,
      full_name: ".kittens.kitten_videos",
      type: ".kittens.Video",
      repeated: true
    }
  ];
}

```

--------------------------------

### Normal field examples

Source: https://protobuf.dev/reference/protobuf/edition-2024-spec

Examples of normal field declarations, including a repeated field with an option.

```protobuf
foo.bar nested_message = 2;
repeated int32 samples = 4 [packed=true];
```

--------------------------------

### Pack and unpack Any values in C++

Source: https://protobuf.dev/programming-guides/editions

Demonstrates how to store an arbitrary message type in an Any field using PackFrom() and how to read it back with Is() and UnpackTo(). The example uses NetworkErrorDetails and ErrorStatus.

```cpp
// Storing an arbitrary message type in Any.
NetworkErrorDetails details = ...;
ErrorStatus status;
status.add_details()->PackFrom(details);

// Reading an arbitrary message from Any.
ErrorStatus status = ...;
for (const google::protobuf::Any& detail : status.details()) {
  if (detail.Is<NetworkErrorDetails>()) {
    NetworkErrorDetails network_error;
    detail.UnpackTo(&network_error);
    ... processing network_error ...
  }
}

```

--------------------------------

### Sample .proto file

Source: https://protobuf.dev/news/2023-04-20

A minimal proto3 file defining a TestMessage with an optional int32 and an optional nested message.

```proto
syntax = "proto3";

package pkg;

message TestMessage {
  optional int32 i32 = 1;
  optional TestMessage msg = 2;
}

```

--------------------------------

### setStart(int $var)

Source: https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/EnumDescriptorProto/EnumReservedRange.html

Sets the start value of the enum reserved range. The start is inclusive.

```APIDOC
## setStart(int $var)

### Description
Inclusive. Generated from protobuf field `optional int32 start = 1;`

### Method
setStart

### Parameters
- **$var** (int) - The start value.

### Return Value
- **$this** - Returns the current instance for chaining.

```

--------------------------------

### Install protoc with Homebrew on macOS

Source: https://protobuf.dev/installation

Installs protoc using Homebrew and verifies the version is 33.0 or newer.

```bash
brew install protobuf
protoc --version  # Ensure compiler version is 33.0+
```

--------------------------------

### Define and Implement SearchService RPC with Stub and Server

Source: https://protobuf.dev/programming-guides/proto?csw=1

Defines the SearchService RPC interface. The generated stub forwards calls to your custom RpcChannel and RpcController implementations; the client example shows how to set up the channel, controller, and stub to execute the Search RPC. The server example implements SearchService to handle requests and must provide its own RpcServer class.

```protobuf
service SearchService {
  rpc Search(SearchRequest) returns (SearchResponse);
}
```

```cpp
using google::protobuf;

protobuf::RpcChannel* channel;
protobuf::RpcController* controller;
SearchService* service;
SearchRequest request;
SearchResponse response;

void DoSearch() {
  // You provide classes MyRpcChannel and MyRpcController, which implement
  // the abstract interfaces protobuf::RpcChannel and protobuf::RpcController.
  channel = new MyRpcChannel("somehost.example.com:1234");
  controller = new MyRpcController;

  // The protocol compiler generates the SearchService class based on the
  // definition given earlier.
  service = new SearchService::Stub(channel);

  // Set up the request.
  request.set_query("protocol buffers");

  // Execute the RPC.
  service->Search(controller, &request, &response,
                  protobuf::NewCallback(&Done));
}

void Done() {
  delete service;
  delete channel;
  delete controller;
}
```

```cpp
using google::protobuf;

class ExampleSearchService : public SearchService {
 public:
  void Search(protobuf::RpcController* controller,
              const SearchRequest* request,
              SearchResponse* response,
              protobuf::Closure* done) {
    if (request->query() == "google") {
      response->add_result()->set_url("http://www.google.com");
    } else if (request->query() == "protocol buffers") {
      response->add_result()->set_url("http://protobuf.googlecode.com");
    }
    done->Run();
  }
};

int main() {
  // You provide class MyRpcServer.  It does not have to implement any
  // particular interface; this is just an example.
  MyRpcServer server;

  protobuf::Service* service = new ExampleSearchService;
  server.ExportOnPort(1234, service);
  server.Run();

  delete service;
  return 0;
}
```

--------------------------------

### Fluent construction with proto! macro

Source: https://protobuf.dev/reference/rust/rust-generated

Example of constructing a message using the proto! macro, which is more succinct and fluent.

```rust
let msg = proto!(SomeMsg {
  x: 1,
  y: "hello",
  some_submsg: SomeSubmsg {
    z: 42
  }
});
```

--------------------------------

### Normal Field Examples

Source: https://protobuf.dev/reference/protobuf/proto3-spec

Examples of normal field declarations, including a repeated field with packed option.

```protobuf
foo.Bar nested_message = 2;
repeated int32 samples = 4 [packed=true];

```

--------------------------------

### MapPath example: mapping virtual paths to disk paths

Source: https://protobuf.dev/reference/cpp/api-docs/google.protobuf.compiler.importer

Shows how to map virtual paths to disk paths using MapPath. The first mapping has higher precedence; when opening a file, mappings are searched in order.

```cpp
MapPath("bar", "foo/bar");
MapPath("", "baz");
```

```cpp
Open("bar/qux");
```

--------------------------------

### protoc with multiple C# options

Source: https://protobuf.dev/reference/csharp/csharp-generated

Invokes the Protobuf compiler with multiple C# options separated by commas: file_extension=.g.cs, base_namespace=Example, and internal_access.

```bash
protoc --proto_path=src --csharp_out=build/gen --csharp_opt=file_extension=.g.cs,base_namespace=Example,internal_access src/foo.proto
```

--------------------------------

### Message Name Example (TitleCase)

Source: https://protobuf.dev/programming-guides/style

Message names should use TitleCase. This example shows a message named SongRequest.

```protobuf
message SongRequest {
}

```
Tokens:
Raw