|
| 1 | +/* |
| 2 | + * Copyright 2026 LiveKit |
| 3 | + * |
| 4 | + * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | + * you may not use this file except in compliance with the License. |
| 6 | + * You may obtain a copy of the License at |
| 7 | + * |
| 8 | + * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | + * |
| 10 | + * Unless required by applicable law or agreed to in writing, software |
| 11 | + * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | + * See the License for the specific language governing permissions and |
| 14 | + * limitations under the License. |
| 15 | + */ |
| 16 | + |
| 17 | +#pragma once |
| 18 | + |
| 19 | +#include <string> |
| 20 | +#include <utility> |
| 21 | + |
| 22 | +namespace livekit { |
| 23 | + |
| 24 | +/// @brief Encoding used to interpret a data track schema definition. |
| 25 | +/// |
| 26 | +/// Identifies the interface definition language the schema is written in (for |
| 27 | +/// example, a `.proto` file for @ref DataTrackSchemaEncoding::Protobuf), which |
| 28 | +/// in turn dictates the wire format of the frames the schema describes. |
| 29 | +/// |
| 30 | +/// Almost all schemas use a well-known encoding, which converts implicitly: |
| 31 | +/// @code |
| 32 | +/// DataTrackSchemaEncoding encoding = DataTrackSchemaEncoding::Protobuf; |
| 33 | +/// @endcode |
| 34 | +/// For the uncommon case of an encoding outside the well-known set, use |
| 35 | +/// @ref DataTrackSchemaEncoding::custom. |
| 36 | +class DataTrackSchemaEncoding { |
| 37 | +public: |
| 38 | + /// Well-known schema encodings. |
| 39 | + enum WellKnown { |
| 40 | + /// Protocol Buffer IDL. |
| 41 | + Protobuf, |
| 42 | + /// FlatBuffer IDL. |
| 43 | + Flatbuffer, |
| 44 | + /// ROS 1 Message. |
| 45 | + Ros1Msg, |
| 46 | + /// ROS 2 Message. |
| 47 | + Ros2Msg, |
| 48 | + /// ROS 2 IDL. |
| 49 | + Ros2Idl, |
| 50 | + /// OMG IDL. |
| 51 | + OmgIdl, |
| 52 | + /// JSON Schema. |
| 53 | + JsonSchema, |
| 54 | + /// Another well-known encoding not known to this client version. |
| 55 | + Other, |
| 56 | + }; |
| 57 | + |
| 58 | + /// Construct a well-known encoding. |
| 59 | + /// |
| 60 | + /// The constructor is intentionally implicit for the common well-known case. |
| 61 | + /// |
| 62 | + /// @param well_known Well-known schema encoding. |
| 63 | + DataTrackSchemaEncoding(WellKnown well_known) : well_known_(well_known) {} |
| 64 | + |
| 65 | + /// Construct a custom, application-defined encoding. |
| 66 | + /// |
| 67 | + /// Prefer a well-known encoding wherever one applies. The identifier must be |
| 68 | + /// non-empty and no longer than 25 characters. |
| 69 | + /// |
| 70 | + /// @param identifier Custom encoding identifier. |
| 71 | + /// @return Custom schema encoding. |
| 72 | + static DataTrackSchemaEncoding custom(std::string identifier) { |
| 73 | + DataTrackSchemaEncoding encoding; |
| 74 | + encoding.custom_ = std::move(identifier); |
| 75 | + return encoding; |
| 76 | + } |
| 77 | + |
| 78 | + /// Check whether this is a custom encoding. |
| 79 | + /// |
| 80 | + /// @return true if this is a custom encoding rather than a well-known one. |
| 81 | + bool isCustom() const { return !custom_.empty(); } |
| 82 | + |
| 83 | + /// Get the well-known encoding. |
| 84 | + /// |
| 85 | + /// @return The well-known encoding. Only meaningful when @ref isCustom is false. |
| 86 | + WellKnown wellKnown() const { return well_known_; } |
| 87 | + |
| 88 | + /// Get the custom identifier. |
| 89 | + /// |
| 90 | + /// @return The custom identifier. Empty when @ref isCustom is false. |
| 91 | + const std::string& customIdentifier() const { return custom_; } |
| 92 | + |
| 93 | +private: |
| 94 | + DataTrackSchemaEncoding() = default; |
| 95 | + |
| 96 | + WellKnown well_known_ = Other; |
| 97 | + std::string custom_; |
| 98 | +}; |
| 99 | + |
| 100 | +inline bool operator==(const DataTrackSchemaEncoding& a, const DataTrackSchemaEncoding& b) { |
| 101 | + if (a.isCustom() || b.isCustom()) { |
| 102 | + return a.customIdentifier() == b.customIdentifier(); |
| 103 | + } |
| 104 | + return a.wellKnown() == b.wellKnown(); |
| 105 | +} |
| 106 | +inline bool operator!=(const DataTrackSchemaEncoding& a, const DataTrackSchemaEncoding& b) { return !(a == b); } |
| 107 | + |
| 108 | +/// @brief Encoding used for frames sent on a data track. |
| 109 | +/// |
| 110 | +/// The serialization format of the frame bytes (for example, |
| 111 | +/// @ref DataTrackFrameEncoding::Protobuf); the structure of those bytes is |
| 112 | +/// described by a schema (see @ref DataTrackSchemaEncoding). |
| 113 | +/// |
| 114 | +/// Almost all tracks use a well-known encoding, which converts implicitly: |
| 115 | +/// @code |
| 116 | +/// options.frame_encoding = DataTrackFrameEncoding::Json; |
| 117 | +/// @endcode |
| 118 | +/// For the uncommon case of an encoding outside the well-known set, use |
| 119 | +/// @ref DataTrackFrameEncoding::custom. |
| 120 | +class DataTrackFrameEncoding { |
| 121 | +public: |
| 122 | + /// Well-known frame encodings. |
| 123 | + enum WellKnown { |
| 124 | + /// ROS 1, described by a Ros1Msg schema. |
| 125 | + Ros1, |
| 126 | + /// CDR, described by a Ros2Msg, Ros2Idl, or OmgIdl schema. |
| 127 | + Cdr, |
| 128 | + /// Protocol Buffer, described by a Protobuf schema. |
| 129 | + Protobuf, |
| 130 | + /// FlatBuffer, described by a Flatbuffer schema. |
| 131 | + Flatbuffer, |
| 132 | + /// CBOR, self-describing. |
| 133 | + Cbor, |
| 134 | + /// MessagePack, self-describing. |
| 135 | + Msgpack, |
| 136 | + /// JSON, self-describing or described by a JsonSchema schema. |
| 137 | + Json, |
| 138 | + /// Another well-known encoding not known to this client version. |
| 139 | + Other, |
| 140 | + }; |
| 141 | + |
| 142 | + /// Construct a well-known encoding. |
| 143 | + /// |
| 144 | + /// The constructor is intentionally implicit for the common well-known case. |
| 145 | + /// |
| 146 | + /// @param well_known Well-known frame encoding. |
| 147 | + DataTrackFrameEncoding(WellKnown well_known) : well_known_(well_known) {} |
| 148 | + |
| 149 | + /// Construct a custom, application-defined encoding. |
| 150 | + /// |
| 151 | + /// Prefer a well-known encoding wherever one applies. The identifier must be |
| 152 | + /// non-empty and no longer than 25 characters. |
| 153 | + /// |
| 154 | + /// @param identifier Custom encoding identifier. |
| 155 | + /// @return Custom frame encoding. |
| 156 | + static DataTrackFrameEncoding custom(std::string identifier) { |
| 157 | + DataTrackFrameEncoding encoding; |
| 158 | + encoding.custom_ = std::move(identifier); |
| 159 | + return encoding; |
| 160 | + } |
| 161 | + |
| 162 | + /// Check whether this is a custom encoding. |
| 163 | + /// |
| 164 | + /// @return true if this is a custom encoding rather than a well-known one. |
| 165 | + bool isCustom() const { return !custom_.empty(); } |
| 166 | + |
| 167 | + /// Get the well-known encoding. |
| 168 | + /// |
| 169 | + /// @return The well-known encoding. Only meaningful when @ref isCustom is false. |
| 170 | + WellKnown wellKnown() const { return well_known_; } |
| 171 | + |
| 172 | + /// Get the custom identifier. |
| 173 | + /// |
| 174 | + /// @return The custom identifier. Empty when @ref isCustom is false. |
| 175 | + const std::string& customIdentifier() const { return custom_; } |
| 176 | + |
| 177 | +private: |
| 178 | + DataTrackFrameEncoding() = default; |
| 179 | + |
| 180 | + WellKnown well_known_ = Other; |
| 181 | + std::string custom_; |
| 182 | +}; |
| 183 | + |
| 184 | +inline bool operator==(const DataTrackFrameEncoding& a, const DataTrackFrameEncoding& b) { |
| 185 | + if (a.isCustom() || b.isCustom()) { |
| 186 | + return a.customIdentifier() == b.customIdentifier(); |
| 187 | + } |
| 188 | + return a.wellKnown() == b.wellKnown(); |
| 189 | +} |
| 190 | +inline bool operator!=(const DataTrackFrameEncoding& a, const DataTrackFrameEncoding& b) { return !(a == b); } |
| 191 | + |
| 192 | +/// @brief Uniquely identifies a data track schema. |
| 193 | +/// |
| 194 | +/// A compound identifier with two components: a name and an encoding. Two IDs |
| 195 | +/// are equal only if both components match; the same name with a different |
| 196 | +/// encoding refers to a distinct schema. |
| 197 | +struct DataTrackSchemaId { |
| 198 | + /// Name component of the schema identifier. |
| 199 | + std::string name; |
| 200 | + |
| 201 | + /// Encoding of the schema definition. |
| 202 | + DataTrackSchemaEncoding encoding = DataTrackSchemaEncoding::Other; |
| 203 | +}; |
| 204 | + |
| 205 | +inline bool operator==(const DataTrackSchemaId& a, const DataTrackSchemaId& b) { |
| 206 | + return a.name == b.name && a.encoding == b.encoding; |
| 207 | +} |
| 208 | +inline bool operator!=(const DataTrackSchemaId& a, const DataTrackSchemaId& b) { return !(a == b); } |
| 209 | + |
| 210 | +} // namespace livekit |
0 commit comments