Skip to content

Latest commit

 

History

History
106 lines (64 loc) · 5.67 KB

README.adoc

File metadata and controls

106 lines (64 loc) · 5.67 KB
Raw

Cyface Protobuf Messages

This repository defines the Cyface Models as schemas such as Protocol Buffer Schemas. This allows to de-/serialize the Cyface Binary Data from in different programming languages.

For more details on Protocol Buffers (short: Protobuf) check out its documentation.

Message Format Definitions

This is a collection of .proto files describe the data structure of the Cyface Models.

  • This allows Protobuf to automatically de-/encode the data from/to binary files.

  • Supports later extensions of the format with backward-compatibility

  • Following the Style Guide

At the time of writing the latest release is Protocol Buffer Version 3.

Notes

Reminders from the documentation which need to be considered for future updates:

  • optional fields are default in proto3, required fields have been removed.

  • Updating A Message Type

  • Extending a Protocol Buffer

  • Deprecated field annotations

  • Default values

  • Scalar message fields, once parsed, cannot tell if a field was not set or set the default value afterwards.

  • Default values are not serialized on the wire.

  • Keep this in mind when defining e.g. booleans, make sure you want that "default" false behavior on.

Other message types:

Compiling the Message Definitions

Generates serializer, deserializer, etc. in a chosen language, e.g. .java files for Java, or .swift files for Swift.

Java

Java classes can be compiled with protoc (Protocol Buffers, version: see protobufVersion in build.gradle):

protoc --java_out=./src/main/java/ src/main/protos/de/cyface/protos/model/measurement.proto

However, the pre-compiled JARs are also published to the Github Package Registry.

  • how to use with Gradle

  • how to use with Android

    Instead of using the pre-compiled `java` classes (published `JAR`s) it's recommended to use `javalite` for Android. These classes can either be manually generated with:
    protoc --java_out=lite:./src/main/java/ src/main/protos/de/cyface/protos/model/measurement.proto

Or you can download the proto link:protoc --java_out=./src/main/java/ src/main/protos/de/cyface/protos/model/measurement.proto[files] from this repository and then generate the classes using the Gradle Plugin. This is done in the Cyface Android SDK - check it out if you need an example.

The serializers encode the data in an efficient way, the decision process is documented internally.

Swift

Swift classes may be generated using Swift Protobuf from Apple.

You can include the .proto file with your Swift project from the Cyface custom Pod repository: https://github.com/cyface-de/ios-podspecs.git using CocoaPods:

pod 'Protos', '~> 0.0.0'

Using a custom Pods repository is explained on the CocoaPods Website.

Using the generated Code

Protocol Buffers and Object-Oriented Design Protocol buffer classes are basically dumb data holders (like structs in C); they don’t make good first class citizens in an object model. If you want to add richer behavior to a generated class, the best way to do this is to wrap the generated protocol buffer class in an application-specific class.

Licensing

Copyright 2021-2023 Cyface GmbH

This file is part of the Cyface Protobuf Messages.

The Cyface Protobuf Messages is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Cyface Protobuf Messages is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with the Cyface Protobuf Messages. If not, see http://www.gnu.org/licenses/.