tirtc-devtools-cli 0.0.1

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

@@ -0,0 +1,481 @@
+#ifndef TIRTC_TRANSPORT_H_
+#define TIRTC_TRANSPORT_H_
+
+#include <stddef.h>
+#include <stdint.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,
+} TirtcTransportStatus;
+
+/**
+ * @brief Connection state visible to user callbacks.
+ */
+typedef enum TirtcTransportConnState {
+  /** Invalid or unknown state. */
+  TIRTC_TRANSPORT_CONN_STATE_INVALID = 0,
+  /** Connecting is in progress. */
+  TIRTC_TRANSPORT_CONN_STATE_CONNECTING = 1,
+  /** Connection is established and usable. */
+  TIRTC_TRANSPORT_CONN_STATE_CONNECTED = 2,
+  /** Connection is disconnected and no longer usable. */
+  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.
+ */
+typedef enum TirtcTransportSystemEvent {
+  /** Service runtime started. */
+  TIRTC_TRANSPORT_SYSTEM_EVENT_STARTED = 0,
+  /** Service runtime stopped. */
+  TIRTC_TRANSPORT_SYSTEM_EVENT_STOPPED = 1,
+  /** Upstream access endpoint may be hijacked/redirected. */
+  TIRTC_TRANSPORT_SYSTEM_EVENT_ACCESS_HIJACKING = 2,
+} TirtcTransportSystemEvent;
+
+/**
+ * @brief Transport media type mapped from backend media kinds.
+ *
+ * Notes:
+ * - stream_id is global per connection.
+ * - audio and video MUST NOT share the same stream_id on one connection.
+ */
+typedef enum TirtcTransportMediaType {
+  /** PCM audio payload. */
+  TIRTC_TRANSPORT_MEDIA_TYPE_AUDIO_PCM = 1,
+  /** G.711 A-law audio payload. */
+  TIRTC_TRANSPORT_MEDIA_TYPE_AUDIO_ALAW = 2,
+  /** AAC audio payload. */
+  TIRTC_TRANSPORT_MEDIA_TYPE_AUDIO_AAC = 3,
+  /** Opus audio payload. */
+  TIRTC_TRANSPORT_MEDIA_TYPE_AUDIO_OPUS = 4,
+  /** JPEG video payload. */
+  TIRTC_TRANSPORT_MEDIA_TYPE_VIDEO_JPEG = 65,
+  /** H.264 video payload. */
+  TIRTC_TRANSPORT_MEDIA_TYPE_VIDEO_H264 = 66,
+  /** H.265 video payload. */
+  TIRTC_TRANSPORT_MEDIA_TYPE_VIDEO_H265 = 67,
+  /** Stream message payload (media-channel message). */
+  TIRTC_TRANSPORT_MEDIA_TYPE_STREAM_MESSAGE = 128,
+} TirtcTransportMediaType;
+
+/**
+ * @brief Audio sample format value used in frame flags for audio streams.
+ */
+typedef enum TirtcTransportAudioSample {
+  /** 8 kHz, 16-bit, mono. */
+  TIRTC_TRANSPORT_AUDIO_SAMPLE_8K16B1C = 0,
+  /** 16 kHz, 16-bit, mono. */
+  TIRTC_TRANSPORT_AUDIO_SAMPLE_16K16B1C = 1,
+  /** 8 kHz, 16-bit, stereo. */
+  TIRTC_TRANSPORT_AUDIO_SAMPLE_8K16B2C = 2,
+  /** 16 kHz, 16-bit, stereo. */
+  TIRTC_TRANSPORT_AUDIO_SAMPLE_16K16B2C = 3,
+} TirtcTransportAudioSample;
+
+/**
+ * @brief Video key-frame flag for TirtcTransportFrameHeader.flags.
+ */
+#define TIRTC_TRANSPORT_FRAME_FLAG_KEY_FRAME 0x01
+
+/**
+ * @brief Opaque descriptor payload passed to transport backend.
+ */
+typedef struct TirtcTransportDescriptor {
+  /** Pointer to descriptor bytes. */
+  const void* data;
+  /** Descriptor byte length. */
+  size_t length;
+} TirtcTransportDescriptor;
+
+typedef struct TirtcTransportConnService TirtcTransportConnService;
+typedef struct TirtcTransportConn TirtcTransportConn;
+
+/**
+ * @brief Options for starting service runtime.
+ */
+typedef struct TirtcTransportConnServiceOptions {
+  /** Required transport descriptor for service runtime. */
+  const TirtcTransportDescriptor* descriptor;
+
+  /**
+   * @brief Maximum number of concurrently accepted connections for this
+   * service listener.
+   *
+   * This is a service-level capacity contract. It applies to the listener as a
+   * whole, not to any single connection and not to any individual stream.
+   *
+   * The current public contract requires a non-zero value.
+   */
+  uint32_t max_connections;
+} TirtcTransportConnServiceOptions;
+
+/**
+ * @brief Options for creating outgoing connection.
+ */
+typedef struct TirtcTransportConnOptions {
+  /** Target peer identifier. */
+  const char* peer_id;
+  /** Required transport descriptor for client connection. */
+  const TirtcTransportDescriptor* descriptor;
+} TirtcTransportConnOptions;
+
+/**
+ * @brief Command-channel payload.
+ *
+ * Command word semantics:
+ * - sequence_number: high 16 bits
+ * - command_id: low 15 bits
+ * - is_response: request/response bit (bit15)
+ */
+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;
+  /** Command payload pointer, can be NULL when payload_length is 0. */
+  const void* payload;
+  /** Command payload bytes. */
+  size_t payload_length;
+} TirtcTransportCommand;
+
+/**
+ * @brief Unified frame header for audio/video/stream-message.
+ */
+typedef struct TirtcTransportFrameHeader {
+  /** Stream identifier (global unique per connection). */
+  uint8_t stream_id;
+  /** One of TirtcTransportMediaType. */
+  uint8_t media_type;
+  /** Flags; video key-frame uses TIRTC_TRANSPORT_FRAME_FLAG_KEY_FRAME. */
+  uint8_t flags;
+  /** Reserved field (mapped from backend dummy field). */
+  uint8_t reserved0;
+  /** Frame timestamp in milliseconds. */
+  uint32_t timestamp_ms;
+  /** Payload length in bytes. */
+  uint32_t payload_length;
+} TirtcTransportFrameHeader;
+
+/**
+ * @brief Audio frame wrapper.
+ */
+typedef struct TirtcTransportAudioFrame {
+  /** Audio frame header. */
+  TirtcTransportFrameHeader header;
+  /** Audio payload bytes. */
+  const void* payload;
+} TirtcTransportAudioFrame;
+
+/**
+ * @brief Video frame wrapper.
+ */
+typedef struct TirtcTransportVideoFrame {
+  /** Video frame header. */
+  TirtcTransportFrameHeader header;
+  /** Video payload bytes. */
+  const void* payload;
+} TirtcTransportVideoFrame;
+
+/**
+ * @brief Stream-message frame wrapper.
+ */
+typedef struct TirtcTransportStreamMessage {
+  /** Message frame header. */
+  TirtcTransportFrameHeader header;
+  /** Message payload bytes. */
+  const void* payload;
+} TirtcTransportStreamMessage;
+
+/**
+ * @brief Service observer callbacks.
+ */
+typedef struct TirtcTransportConnServiceObserver {
+  /** Called when service runtime is started. */
+  void (*on_started)(TirtcTransportConnService* service, void* user_data);
+  /** Called when service runtime is stopped. */
+  void (*on_stopped)(TirtcTransportConnService* service, void* user_data);
+  /** Called on system-level service event. */
+  void (*on_event)(TirtcTransportConnService* service, TirtcTransportSystemEvent event,
+                   const void* data, size_t length, void* user_data);
+  /** Called when a new incoming connection is accepted by service. */
+  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;
+
+/**
+ * @brief Connection observer callbacks.
+ *
+ * Callback user_data here is observer context, independent from
+ * tirtc_transport_conn_set_user_data()/get_user_data().
+ */
+typedef struct TirtcTransportConnObserver {
+  /** 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);
+  /** 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);
+  /**
+   * @brief Called when remote requests video stream start.
+   * @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);
+  /**
+   * @brief Called when remote requests audio stream start.
+   * @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);
+  /** Called when audio frame is received. */
+  void (*on_audio_frame)(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);
+  /** 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;
+
+/**
+ * @brief Initialize transport runtime.
+ *
+ * This function is idempotent.
+ */
+TirtcTransportStatus tirtc_transport_init(void);
+
+/**
+ * @brief Enable/disable transport debug mode.
+ *
+ * When enabled, transport backend sets verbose vendor SDK log level during runtime init
+ * and applies it immediately if runtime is already initialized.
+ *
+ * @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);
+
+/**
+ * @brief Uninitialize transport runtime.
+ *
+ * This function is idempotent.
+ */
+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);
+
+/**
+ * @brief Stop service runtime.
+ */
+TirtcTransportStatus tirtc_transport_conn_service_stop(TirtcTransportConnService* service);
+
+/**
+ * @brief Create outgoing connection.
+ *
+ * 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);
+
+/**
+ * @brief Set or replace connection observer.
+ *
+ * The implementation may synchronously replay current state/disconnected event
+ * to the new observer according to contract.
+ */
+TirtcTransportStatus tirtc_transport_conn_set_observer(TirtcTransportConn* connection,
+                                                       const TirtcTransportConnObserver* observer,
+                                                       void* user_data);
+
+/**
+ * @brief Attach a connection-level user context pointer.
+ *
+ * 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);
+
+/**
+ * @brief Get connection-level user context pointer set by set_user_data.
+ */
+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);
+
+/**
+ * @brief Request local disconnect.
+ *
+ * Disconnected completion is reported by on_disconnected callback.
+ */
+TirtcTransportStatus tirtc_transport_disconnect(TirtcTransportConn* connection);
+
+/**
+ * @brief Destroy transport connection handle.
+ *
+ * This releases transport-layer resources owned by this handle.
+ */
+void tirtc_transport_conn_destroy(TirtcTransportConn* connection);
+
+/**
+ * @brief Send command payload over command channel.
+ */
+TirtcTransportStatus 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);
+
+/**
+ * @brief Request remote side to start sending a video stream on this
+ * connection.
+ *
+ * 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);
+
+/**
+ * @brief Request remote side to stop sending a video stream on this
+ * connection.
+ *
+ * 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);
+
+/**
+ * @brief Request remote side to start sending an audio stream on this
+ * connection.
+ *
+ * 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);
+
+/**
+ * @brief Request remote side to stop sending an audio stream on this
+ * connection.
+ *
+ * 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);
+
+/**
+ * @brief Send typed audio frame.
+ */
+TirtcTransportStatus 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);
+
+/**
+ * @brief Send stream-message payload in media channel.
+ */
+TirtcTransportStatus tirtc_transport_send_stream_message(
+    TirtcTransportConn* connection, const TirtcTransportStreamMessage* message);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // TIRTC_TRANSPORT_H_