tirtc-devtools-cli 0.0.9 → 0.0.11

package/vendor/app-server/bin/runtime/macos-arm64/include/tirtc/transport.h

@@ -4,42 +4,12 @@
 #include <stddef.h>
 #include <stdint.h>
 
+#include "tirtc/error.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/**
- * @brief Transport API status code.
- */
-typedef enum TirtcTransportStatus {
-  /** Operation succeeded. */
-  TIRTC_TRANSPORT_STATUS_OK = 0,
-  /** Input argument is invalid. */
-  TIRTC_TRANSPORT_STATUS_INVALID_ARGUMENT = 1,
-  /** Transport runtime has not been initialized. */
-  TIRTC_TRANSPORT_STATUS_NOT_INITIALIZED = 2,
-  /** Connection is not established or already closed. */
-  TIRTC_TRANSPORT_STATUS_NOT_CONNECTED = 3,
-  /** Requested operation is not supported by current backend. */
-  TIRTC_TRANSPORT_STATUS_UNSUPPORTED = 4,
-  /** Backend returned an internal error. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_ERROR = 5,
-  /** Backend reported invalid license. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_INVALID_LICENSE = 6,
-  /** Backend reported operation timeout. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_TIMEOUT = 7,
-  /** Backend reported busy/send-buffer-full. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_BUSY = 8,
-  /** Backend reported connection timeout close. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_CONNECTION_TIMEOUT_CLOSED = 9,
-  /** Backend reported remote close. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_REMOTE_CLOSED = 10,
-  /** Backend reported other connection error. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_CONNECTION_OTHER_ERROR = 11,
-  /** Backend reported token expired. */
-  TIRTC_TRANSPORT_STATUS_BACKEND_TOKEN_EXPIRED = 12,
-} TirtcTransportStatus;
-
 /**
  * @brief Connection state visible to user callbacks.
  */
@@ -54,24 +24,6 @@ typedef enum TirtcTransportConnState {
   TIRTC_TRANSPORT_CONN_STATE_DISCONNECTED = 3,
 } TirtcTransportConnState;
 
-/**
- * @brief Reason for disconnected state.
- */
-typedef enum TirtcTransportDisconnectReason {
-  /** Unknown reason. */
-  TIRTC_TRANSPORT_DISCONNECT_REASON_UNKNOWN = 0,
-  /** Disconnected by local side. */
-  TIRTC_TRANSPORT_DISCONNECT_REASON_LOCAL_CLOSED = 1,
-  /** Disconnected by remote side. */
-  TIRTC_TRANSPORT_DISCONNECT_REASON_REMOTE_CLOSED = 2,
-  /** Connection establishment failed. */
-  TIRTC_TRANSPORT_DISCONNECT_REASON_CONNECT_FAILED = 3,
-  /** Descriptor validation failed. */
-  TIRTC_TRANSPORT_DISCONNECT_REASON_INVALID_DESCRIPTOR = 4,
-  /** Backend reported fatal error. */
-  TIRTC_TRANSPORT_DISCONNECT_REASON_BACKEND_ERROR = 5,
-} TirtcTransportDisconnectReason;
-
 /**
  * @brief Service-level runtime event.
  */
@@ -174,22 +126,12 @@ typedef struct TirtcTransportConnOptions {
 /**
  * @brief Command-channel payload.
  *
- * Command word semantics:
- * - sequence_number: high 16 bits
- * - command_id: low 15 bits
- * - is_response: request/response bit (bit15)
+ * command is an opaque backend-defined 32-bit value. The transport public
+ * contract forwards it without splitting sequence or request/response bits.
  */
 typedef struct TirtcTransportCommand {
-  /** 16-bit command sequence number. */
-  uint16_t sequence_number;
-  /** 15-bit command identifier. */
-  uint16_t command_id;
-  /** Non-zero for response, zero for request. */
-  uint8_t is_response;
-  /** Reserved, set to zero. */
-  uint8_t reserved0;
-  /** Reserved, set to zero. */
-  uint16_t reserved1;
+  /** Opaque raw 32-bit command word. */
+  uint32_t command;
   /** Command payload pointer, can be NULL when payload_length is 0. */
   const void* payload;
   /** Command payload bytes. */
@@ -247,7 +189,7 @@ typedef struct TirtcTransportStreamMessage {
 /**
  * @brief Service observer callbacks.
  */
-typedef struct TirtcTransportConnServiceObserver {
+typedef struct TirtcTransportConnServiceCallbacks {
   /** Called when service runtime is started. */
   void (*on_started)(TirtcTransportConnService* service, void* user_data);
   /** Called when service runtime is stopped. */
@@ -259,9 +201,9 @@ typedef struct TirtcTransportConnServiceObserver {
   void (*on_connected)(TirtcTransportConnService* service, TirtcTransportConn* connection,
                        void* user_data);
   /** Called when service-level error happens. */
-  void (*on_error)(TirtcTransportConnService* service, TirtcTransportStatus code,
-                   const char* message, void* user_data);
-} TirtcTransportConnServiceObserver;
+  void (*on_error)(TirtcTransportConnService* service, TirtcError error, const char* message,
+                   void* user_data);
+} TirtcTransportConnServiceCallbacks;
 
 /**
  * @brief Connection observer callbacks.
@@ -269,52 +211,46 @@ typedef struct TirtcTransportConnServiceObserver {
  * Callback user_data here is observer context, independent from
  * tirtc_transport_conn_set_user_data()/get_user_data().
  */
-typedef struct TirtcTransportConnObserver {
+typedef struct TirtcTransportConnCallbacks {
   /** Called when connection state changes. */
   void (*on_state_changed)(TirtcTransportConn* connection, TirtcTransportConnState state,
-                           void* user_data);
-  /** Called once connection is disconnected. */
-  void (*on_disconnected)(TirtcTransportConn* connection, TirtcTransportDisconnectReason reason,
-                          void* user_data);
+                           TirtcError error, void* user_data);
   /** Called when command payload is received. */
   void (*on_command)(TirtcTransportConn* connection, const TirtcTransportCommand* command,
                      void* user_data);
   /** Called when remote requests a key frame. */
-  void (*on_request_iframe)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
+  void (*on_request_key_frame)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
   /**
-   * @brief Called when remote requests video stream start.
+   * @brief Called when remote subscribes to video stream.
    * @return 0 to accept, non-zero to reject.
    */
-  int (*on_request_video)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
-  /** Called when remote requests video stream stop. */
-  void (*on_release_video)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
+  int (*on_subscribe_video)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
+  /** Called when remote unsubscribes from video stream. */
+  void (*on_unsubscribe_video)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
   /**
-   * @brief Called when remote requests audio stream start.
+   * @brief Called when remote subscribes to audio stream.
    * @return 0 to accept, non-zero to reject.
    */
-  int (*on_request_audio)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
-  /** Called when remote requests audio stream stop. */
-  void (*on_release_audio)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
+  int (*on_subscribe_audio)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
+  /** Called when remote unsubscribes from audio stream. */
+  void (*on_unsubscribe_audio)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
   /** Called when audio frame is received. */
-  void (*on_audio_frame)(TirtcTransportConn* connection, const TirtcTransportAudioFrame* frame,
-                         void* user_data);
+  void (*on_stream_audio)(TirtcTransportConn* connection, const TirtcTransportAudioFrame* frame,
+                          void* user_data);
   /** Called when video frame is received. */
-  void (*on_video_frame)(TirtcTransportConn* connection, const TirtcTransportVideoFrame* frame,
-                         void* user_data);
+  void (*on_stream_video)(TirtcTransportConn* connection, const TirtcTransportVideoFrame* frame,
+                          void* user_data);
   /** Called when stream message is received. */
   void (*on_stream_message)(TirtcTransportConn* connection,
                             const TirtcTransportStreamMessage* message, void* user_data);
-  /** Called on connection-level error. */
-  void (*on_error)(TirtcTransportConn* connection, TirtcTransportStatus code, const char* message,
-                   void* user_data);
-} TirtcTransportConnObserver;
+} TirtcTransportConnCallbacks;
 
 /**
  * @brief Initialize transport runtime.
  *
  * This function is idempotent.
  */
-TirtcTransportStatus tirtc_transport_init(void);
+TirtcError tirtc_transport_init(void);
 
 /**
  * @brief Enable/disable transport debug mode.
@@ -325,12 +261,7 @@ TirtcTransportStatus tirtc_transport_init(void);
  * @param enabled Non-zero to enable debug mode, zero to disable.
  * @return Operation status.
  */
-TirtcTransportStatus tirtc_transport_enable_debug(uint8_t enabled);
-
-/**
- * @brief Allocate next 16-bit command sequence number.
- */
-uint16_t tirtc_transport_command_next_sequence(void);
+TirtcError tirtc_transport_enable_debug(uint8_t enabled);
 
 /**
  * @brief Uninitialize transport runtime.
@@ -342,15 +273,15 @@ void tirtc_transport_uninit(void);
 /**
  * @brief Start service runtime with descriptor and service observer.
  */
-TirtcTransportStatus tirtc_transport_conn_service_start(
-    const TirtcTransportConnServiceOptions* options,
-    const TirtcTransportConnServiceObserver* observer, void* user_data,
-    TirtcTransportConnService** out_service);
+TirtcError tirtc_transport_conn_service_start(const TirtcTransportConnServiceOptions* options,
+                                              const TirtcTransportConnServiceCallbacks* callbacks,
+                                              void* user_data,
+                                              TirtcTransportConnService** out_service);
 
 /**
  * @brief Stop service runtime.
  */
-TirtcTransportStatus tirtc_transport_conn_service_stop(TirtcTransportConnService* service);
+TirtcError tirtc_transport_conn_service_stop(TirtcTransportConnService* service);
 
 /**
  * @brief Create outgoing connection.
@@ -358,18 +289,18 @@ TirtcTransportStatus tirtc_transport_conn_service_stop(TirtcTransportConnService
  * On success, returned handle enters CONNECTING first; actual connected/disconnected
  * transition is delivered by observer callbacks.
  */
-TirtcTransportStatus tirtc_transport_connect(const TirtcTransportConnOptions* options,
-                                             TirtcTransportConn** out_connection);
+TirtcError tirtc_transport_connect(const TirtcTransportConnOptions* options,
+                                   TirtcTransportConn** out_connection);
 
 /**
  * @brief Set or replace connection observer.
  *
- * The implementation may synchronously replay current state/disconnected event
- * to the new observer according to contract.
+ * The implementation may synchronously replay the current state according to
+ * contract.
  */
-TirtcTransportStatus tirtc_transport_conn_set_observer(TirtcTransportConn* connection,
-                                                       const TirtcTransportConnObserver* observer,
-                                                       void* user_data);
+TirtcError tirtc_transport_conn_set_callbacks(TirtcTransportConn* connection,
+                                              const TirtcTransportConnCallbacks* callbacks,
+                                              void* user_data);
 
 /**
  * @brief Attach a connection-level user context pointer.
@@ -377,8 +308,7 @@ TirtcTransportStatus tirtc_transport_conn_set_observer(TirtcTransportConn* conne
  * This is equivalent to backend connection user data mapping and is independent
  * from observer callback user_data.
  */
-TirtcTransportStatus tirtc_transport_conn_set_user_data(TirtcTransportConn* connection,
-                                                        void* user_data);
+TirtcError tirtc_transport_conn_set_user_data(TirtcTransportConn* connection, void* user_data);
 
 /**
  * @brief Get connection-level user context pointer set by set_user_data.
@@ -388,15 +318,15 @@ void* tirtc_transport_conn_get_user_data(TirtcTransportConn* connection);
 /**
  * @brief Get current send-buffer used bytes for this connection.
  */
-TirtcTransportStatus tirtc_transport_conn_get_send_buffer_used(TirtcTransportConn* connection,
-                                                               size_t* out_bytes);
+TirtcError tirtc_transport_conn_get_send_buffer_used(TirtcTransportConn* connection,
+                                                     size_t* out_bytes);
 
 /**
  * @brief Request local disconnect.
  *
- * Disconnected completion is reported by on_disconnected callback.
+ * Disconnected completion is reported by on_state_changed callback.
  */
-TirtcTransportStatus tirtc_transport_disconnect(TirtcTransportConn* connection);
+TirtcError tirtc_transport_disconnect(TirtcTransportConn* connection);
 
 /**
  * @brief Destroy transport connection handle.
@@ -408,15 +338,14 @@ void tirtc_transport_conn_destroy(TirtcTransportConn* connection);
 /**
  * @brief Send command payload over command channel.
  */
-TirtcTransportStatus tirtc_transport_send_command(TirtcTransportConn* connection,
-                                                  const TirtcTransportCommand* command);
+TirtcError tirtc_transport_send_command(TirtcTransportConn* connection,
+                                        const TirtcTransportCommand* command);
 
 /**
  * @brief Request remote side to send a key frame for a video stream on this
  * connection.
  */
-TirtcTransportStatus tirtc_transport_request_iframe(TirtcTransportConn* connection,
-                                                    uint8_t stream_id);
+TirtcError tirtc_transport_request_key_frame(TirtcTransportConn* connection, uint8_t stream_id);
 
 /**
  * @brief Request remote side to start sending a video stream on this
@@ -425,8 +354,7 @@ TirtcTransportStatus tirtc_transport_request_iframe(TirtcTransportConn* connecti
  * The request scope is limited to the supplied ::connection and ::stream_id.
  * It must not affect any other connection.
  */
-TirtcTransportStatus tirtc_transport_request_video(TirtcTransportConn* connection,
-                                                   uint8_t stream_id);
+TirtcError tirtc_transport_subscribe_video(TirtcTransportConn* connection, uint8_t stream_id);
 
 /**
  * @brief Request remote side to stop sending a video stream on this
@@ -435,8 +363,7 @@ TirtcTransportStatus tirtc_transport_request_video(TirtcTransportConn* connectio
  * The release scope is limited to the supplied ::connection and ::stream_id.
  * It must not affect any other connection.
  */
-TirtcTransportStatus tirtc_transport_release_video(TirtcTransportConn* connection,
-                                                   uint8_t stream_id);
+TirtcError tirtc_transport_unsubscribe_video(TirtcTransportConn* connection, uint8_t stream_id);
 
 /**
  * @brief Request remote side to start sending an audio stream on this
@@ -445,8 +372,7 @@ TirtcTransportStatus tirtc_transport_release_video(TirtcTransportConn* connectio
  * The request scope is limited to the supplied ::connection and ::stream_id.
  * It must not affect any other connection.
  */
-TirtcTransportStatus tirtc_transport_request_audio(TirtcTransportConn* connection,
-                                                   uint8_t stream_id);
+TirtcError tirtc_transport_subscribe_audio(TirtcTransportConn* connection, uint8_t stream_id);
 
 /**
  * @brief Request remote side to stop sending an audio stream on this
@@ -455,26 +381,25 @@ TirtcTransportStatus tirtc_transport_request_audio(TirtcTransportConn* connectio
  * The release scope is limited to the supplied ::connection and ::stream_id.
  * It must not affect any other connection.
  */
-TirtcTransportStatus tirtc_transport_release_audio(TirtcTransportConn* connection,
-                                                   uint8_t stream_id);
+TirtcError tirtc_transport_unsubscribe_audio(TirtcTransportConn* connection, uint8_t stream_id);
 
 /**
  * @brief Send typed audio frame.
  */
-TirtcTransportStatus tirtc_transport_send_audio_frame(TirtcTransportConn* connection,
-                                                      const TirtcTransportAudioFrame* frame);
+TirtcError tirtc_transport_send_audio_frame(TirtcTransportConn* connection,
+                                            const TirtcTransportAudioFrame* frame);
 
 /**
  * @brief Send typed video frame.
  */
-TirtcTransportStatus tirtc_transport_send_video_frame(TirtcTransportConn* connection,
-                                                      const TirtcTransportVideoFrame* frame);
+TirtcError tirtc_transport_send_video_frame(TirtcTransportConn* connection,
+                                            const TirtcTransportVideoFrame* frame);
 
 /**
  * @brief Send stream-message payload in media channel.
  */
-TirtcTransportStatus tirtc_transport_send_stream_message(
-    TirtcTransportConn* connection, const TirtcTransportStreamMessage* message);
+TirtcError tirtc_transport_send_stream_message(TirtcTransportConn* connection,
+                                               const TirtcTransportStreamMessage* message);
 
 #ifdef __cplusplus
 }