result.h file for floating up specific errors provided by the FFI

Author: stephen-derosa

CMakeLists.txt

@@ -324,7 +324,9 @@ add_library(livekit SHARED
   src/audio_processing_module.cpp
   src/audio_source.cpp
   src/audio_stream.cpp
+  src/data_frame.cpp
   src/data_stream.cpp
+  src/data_track_error.cpp
   src/data_track_subscription.cpp
   src/e2ee.cpp
   src/ffi_handle.cpp

examples/hello_livekit/sender.cpp

@@ -95,8 +95,17 @@ int main(int argc, char *argv[]) {
   std::shared_ptr<LocalVideoTrack> video_track = lp->publishVideoTrack(
       kVideoTrackName, video_source, TrackSource::SOURCE_CAMERA);
 
-  std::shared_ptr<LocalDataTrack> data_track =
-      lp->publishDataTrack(kDataTrackName);
+  auto publish_result = lp->publishDataTrack(kDataTrackName);
+  if (!publish_result) {
+    const auto &error = publish_result.error();
+    LK_LOG_ERROR("Failed to publish data track: code={} retryable={} message={}",
+                 static_cast<std::uint32_t>(error.code), error.retryable,
+                 error.message);
+    room.reset();
+    livekit::shutdown();
+    return 1;
+  }
+  std::shared_ptr<LocalDataTrack> data_track = publish_result.value();
 
   const auto t0 = std::chrono::steady_clock::now();
   std::uint64_t count = 0;
@@ -115,7 +124,14 @@ int main(int argc, char *argv[]) {
     std::ostringstream oss;
     oss << std::fixed << std::setprecision(2) << ms << " ms, count: " << count;
     const std::string msg = oss.str();
-    data_track->tryPush(std::vector<std::uint8_t>(msg.begin(), msg.end()));
+    auto push_result =
+        data_track->tryPush(std::vector<std::uint8_t>(msg.begin(), msg.end()));
+    if (!push_result) {
+      const auto &error = push_result.error();
+      LK_LOG_WARN("Failed to push data frame: code={} retryable={} message={}",
+                  static_cast<std::uint32_t>(error.code), error.retryable,
+                  error.message);
+    }
 
     ++count;
     std::this_thread::sleep_for(std::chrono::milliseconds(100));

examples/simple_status/producer.cpp

@@ -94,15 +94,18 @@ int main(int argc, char *argv[]) {
               room->room_info().name);
 
   std::shared_ptr<LocalDataTrack> data_track;
-  try {
-    data_track = lp->publishDataTrack(kTrackName);
-  } catch (const std::exception &e) {
-    LK_LOG_ERROR("Failed to publish data track: {}", e.what());
+  auto publish_result = lp->publishDataTrack(kTrackName);
+  if (!publish_result) {
+    const auto &error = publish_result.error();
+    LK_LOG_ERROR("Failed to publish data track: code={} retryable={} message={}",
+                 static_cast<std::uint32_t>(error.code), error.retryable,
+                 error.message);
     room->setDelegate(nullptr);
     room.reset();
     livekit::shutdown();
     return 1;
   }
+  data_track = publish_result.value();
 
   LK_LOG_INFO("published data track '{}'", kTrackName);
 
@@ -123,8 +126,12 @@ int main(int argc, char *argv[]) {
                              " count: " + std::to_string(count);
 
     std::vector<std::uint8_t> payload(text.begin(), text.end());
-    if (!data_track->tryPush(payload)) {
-      LK_LOG_WARN("Failed to push data frame");
+    auto push_result = data_track->tryPush(payload);
+    if (!push_result) {
+      const auto &error = push_result.error();
+      LK_LOG_WARN("Failed to push data frame: code={} retryable={} message={}",
+                  static_cast<std::uint32_t>(error.code), error.retryable,
+                  error.message);
     }
 
     LK_LOG_DEBUG("sent: {}", text);

include/livekit/data_track_error.h

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2026 LiveKit
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an “AS IS” BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef LIVEKIT_DATA_TRACK_ERROR_H
+#define LIVEKIT_DATA_TRACK_ERROR_H
+
+#include <cstdint>
+#include <string>
+
+namespace livekit {
+
+namespace proto {
+class DataTrackError;
+}
+
+/// Stable error codes for data-track operations.
+enum class DataTrackErrorCode : std::uint32_t {
+  UNKNOWN = 0,
+  INVALID_HANDLE = 1,
+  DUPLICATE_TRACK_NAME = 2,
+  TRACK_UNPUBLISHED = 3,
+  BUFFER_FULL = 4,
+  SUBSCRIPTION_CLOSED = 5,
+  CANCELLED = 6,
+  PROTOCOL_ERROR = 7,
+  INTERNAL = 8,
+};
+
+/// Structured failure returned by non-throwing data-track APIs.
+struct DataTrackError {
+  /// Machine-readable error code.
+  DataTrackErrorCode code{DataTrackErrorCode::UNKNOWN};
+  /// Human-readable description from the backend or SDK.
+  std::string message;
+  /// Whether retrying the operation may succeed.
+  bool retryable{false};
+
+  /// Convert the FFI proto representation into the public SDK type.
+  static DataTrackError fromProto(const proto::DataTrackError &error);
+};
+
+} // namespace livekit
+
+#endif // LIVEKIT_DATA_TRACK_ERROR_H

include/livekit/data_track_subscription.h

@@ -43,10 +43,13 @@ class FfiEvent;
  *
  * Typical usage:
  *
- *   auto sub = remoteDataTrack->subscribe();
- *   DataFrame frame;
- *   while (sub->read(frame)) {
- *     // process frame.payload
+ *   auto sub_result = remoteDataTrack->subscribe();
+ *   if (sub_result) {
+ *     auto sub = sub_result.value();
+ *     DataFrame frame;
+ *     while (sub->read(frame)) {
+ *       // process frame.payload
+ *     }
  *   }
  */
 class DataTrackSubscription {

include/livekit/local_data_track.h

@@ -17,8 +17,10 @@
 #pragma once
 
 #include "livekit/data_frame.h"
+#include "livekit/data_track_error.h"
 #include "livekit/data_track_info.h"
 #include "livekit/ffi_handle.h"
+#include "livekit/result.h"
 
 #include <cstddef>
 #include <memory>
@@ -44,11 +46,14 @@ class OwnedLocalDataTrack;
  * Typical usage:
  *
  *   auto lp = room->localParticipant();
- *   auto dt = lp->publishDataTrack("sensor-data");
- *   DataFrame frame;
- *   frame.payload = {0x01, 0x02, 0x03};
- *   dt->tryPush(frame);
- *   dt->unpublishDataTrack();
+ *   auto result = lp->publishDataTrack("sensor-data");
+ *   if (result) {
+ *     auto dt = result.value();
+ *     DataFrame frame;
+ *     frame.payload = {0x01, 0x02, 0x03};
+ *     (void)dt->tryPush(frame);
+ *     dt->unpublishDataTrack();
+ *   }
  */
 class LocalDataTrack {
 public:
@@ -63,29 +68,32 @@ class LocalDataTrack {
   /**
    * Try to push a frame to all subscribers of this track.
    *
-   * @return true on success, false if the push failed (e.g. back-pressure
-   *         or the track has been unpublished).
+   * @return success on delivery acceptance, or a typed error describing why
+   *         the frame could not be queued.
    */
-  bool tryPush(const DataFrame &frame);
+  Result<void, DataTrackError> tryPush(const DataFrame &frame);
 
   /**
    * Try to push a frame to all subscribers of this track.
    *
-   * @return true on success, false if the push failed (e.g. back-pressure
-   *         or the track has been unpublished).
+   * @return success on delivery acceptance, or a typed error describing why
+   *         the frame could not be queued.
    */
-  bool tryPush(const std::vector<std::uint8_t> &payload,
-               std::optional<std::uint64_t> user_timestamp = std::nullopt);
-  bool tryPush(std::vector<std::uint8_t> &&payload,
-               std::optional<std::uint64_t> user_timestamp = std::nullopt);
+  Result<void, DataTrackError>
+  tryPush(const std::vector<std::uint8_t> &payload,
+          std::optional<std::uint64_t> user_timestamp = std::nullopt);
+  Result<void, DataTrackError>
+  tryPush(std::vector<std::uint8_t> &&payload,
+          std::optional<std::uint64_t> user_timestamp = std::nullopt);
   /**
    * Try to push a frame to all subscribers of this track.
    *
-   * @return true on success, false if the push failed (e.g. back-pressure
-   *         or the track has been unpublished).
+   * @return success on delivery acceptance, or a typed error describing why
+   *         the frame could not be queued.
    */
-  bool tryPush(const std::uint8_t *data, std::size_t size,
-               std::optional<std::uint64_t> user_timestamp = std::nullopt);
+  Result<void, DataTrackError>
+  tryPush(const std::uint8_t *data, std::size_t size,
+          std::optional<std::uint64_t> user_timestamp = std::nullopt);
 
   /// Whether the track is still published in the room.
   bool isPublished() const;

include/livekit/local_participant.h

@@ -181,10 +181,11 @@ class LocalParticipant : public Participant {
    * LocalParticipant::unpublishDataTrack().
    *
    * @param name  Unique track name visible to other participants.
-   * @return Shared pointer to the published data track.
-   * @throws std::runtime_error on FFI or publish failure.
+   * @return The published track on success, or a typed error describing why
+   *         publication failed.
    */
-  std::shared_ptr<LocalDataTrack> publishDataTrack(const std::string &name);
+  Result<std::shared_ptr<LocalDataTrack>, DataTrackError>
+  publishDataTrack(const std::string &name);
 
   /**
    * Unpublish a data track from the room.

include/livekit/remote_data_track.h

@@ -18,7 +18,9 @@
 
 #include "livekit/data_track_info.h"
 #include "livekit/data_track_subscription.h"
+#include "livekit/data_track_error.h"
 #include "livekit/ffi_handle.h"
+#include "livekit/result.h"
 
 #include <memory>
 #include <string>
@@ -39,10 +41,13 @@ class OwnedRemoteDataTrack;
  * Typical usage:
  *
  *   // In RoomDelegate::onDataTrackPublished callback:
- *   auto sub = remoteDataTrack->subscribe();
- *   DataFrame frame;
- *   while (sub->read(frame)) {
- *     // process frame
+ *   auto sub_result = remoteDataTrack->subscribe();
+ *   if (sub_result) {
+ *     auto sub = sub_result.value();
+ *     DataFrame frame;
+ *     while (sub->read(frame)) {
+ *       // process frame
+ *     }
  *   }
  */
 class RemoteDataTrack {
@@ -68,10 +73,8 @@ class RemoteDataTrack {
    *
    * Returns a DataTrackSubscription that delivers frames via blocking
    * read(). Destroy the subscription to unsubscribe.
-   *
-   * @throws std::runtime_error if the FFI subscribe call fails.
    */
-  std::shared_ptr<DataTrackSubscription>
+  Result<std::shared_ptr<DataTrackSubscription>, DataTrackError>
   subscribe(const DataTrackSubscription::Options &options = {});
 
 private: