tirtc-devtools-cli 0.0.15 → 0.1.1

package/vendor/runtime/linux-x64/include/tirtc/transport.h

@@ -0,0 +1,445 @@
+#ifndef TIRTC_TRANSPORT_H_
+#define TIRTC_TRANSPORT_H_
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include "tirtc/error.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @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 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 Network type hint passed to the transport backend.
+ */
+typedef enum TirtcTransportNetworkType {
+  /** Use the backend default network behavior. */
+  TIRTC_TRANSPORT_NETWORK_TYPE_DEFAULT = 0,
+  /** Wi-Fi network path. */
+  TIRTC_TRANSPORT_NETWORK_TYPE_WIFI = 1,
+  /** 4G cellular network path. */
+  TIRTC_TRANSPORT_NETWORK_TYPE_4G = 2,
+} TirtcTransportNetworkType;
+
+/**
+ * @brief Transport runtime options shared by service and outgoing connection paths.
+ */
+typedef struct TirtcTransportRuntimeOptions {
+  /** Required service endpoint URL. */
+  const char* endpoint;
+  /** Optional network type hint. Zero-initialized options use the backend default. */
+  TirtcTransportNetworkType network_type;
+  /** Non-zero enables backend wakeup support. */
+  uint8_t wakeup_enabled;
+  /** Non-zero enables restricted-network mode. */
+  uint8_t restricted_network;
+} TirtcTransportRuntimeOptions;
+
+/**
+ * @brief Connect-parameter cache policy for outgoing connections.
+ */
+typedef enum TirtcTransportConnectCacheMode {
+  /** Use backend default cache policy. */
+  TIRTC_TRANSPORT_CONNECT_CACHE_DEFAULT = 0,
+  /** Disable backend connection-parameter cache. */
+  TIRTC_TRANSPORT_CONNECT_CACHE_DISABLED = 1,
+  /** Enable backend connection-parameter cache. */
+  TIRTC_TRANSPORT_CONNECT_CACHE_ENABLED = 2,
+} TirtcTransportConnectCacheMode;
+
+typedef struct TirtcTransportConnService TirtcTransportConnService;
+typedef struct TirtcTransportConn TirtcTransportConn;
+
+/**
+ * @brief Options for starting service runtime.
+ */
+typedef struct TirtcTransportConnServiceOptions {
+  /** Required service license. */
+  const char* license;
+
+  /** Required runtime options. */
+  TirtcTransportRuntimeOptions runtime_options;
+
+  /**
+   * @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 remote identifier. */
+  const char* remote_id;
+  /** Required one-shot bootstrap token. */
+  const char* token;
+  /** Required runtime options. */
+  TirtcTransportRuntimeOptions runtime_options;
+  /** Backend connection-parameter cache policy. */
+  TirtcTransportConnectCacheMode connect_cache_mode;
+  /** Non-zero asks backend to try cached connect parameters before the explicit token. */
+  uint8_t prefer_cached_connect_params;
+} TirtcTransportConnOptions;
+
+/**
+ * @brief Command-channel payload.
+ *
+ * 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 {
+  /** 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. */
+  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 TirtcTransportConnServiceCallbacks {
+  /** 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, TirtcError error, const char* message,
+                   void* user_data);
+} TirtcTransportConnServiceCallbacks;
+
+/**
+ * @brief Connection observer callbacks.
+ *
+ * Callback user_data here is observer context, independent from
+ * tirtc_transport_conn_set_user_data()/get_user_data().
+ */
+typedef struct TirtcTransportConnCallbacks {
+  /** Called when connection state changes. */
+  void (*on_state_changed)(TirtcTransportConn* connection, TirtcTransportConnState state,
+                           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_key_frame)(TirtcTransportConn* connection, uint8_t stream_id, void* user_data);
+  /**
+   * @brief Called when remote subscribes to video stream.
+   * @return 0 to accept, non-zero to reject.
+   */
+  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 subscribes to audio stream.
+   * @return 0 to accept, non-zero to reject.
+   */
+  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_stream_audio)(TirtcTransportConn* connection, const TirtcTransportAudioFrame* frame,
+                          void* user_data);
+  /** Called when video frame is received. */
+  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);
+} TirtcTransportConnCallbacks;
+
+/**
+ * @brief Initialize transport runtime.
+ *
+ * This function is idempotent.
+ */
+TirtcError 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.
+ */
+TirtcError tirtc_transport_enable_debug(uint8_t enabled);
+
+/**
+ * @brief Uninitialize transport runtime.
+ *
+ * This function is idempotent.
+ */
+void tirtc_transport_uninit(void);
+
+/**
+ * @brief Start service runtime with typed options and service observer.
+ */
+TirtcError tirtc_transport_conn_service_start(const TirtcTransportConnServiceOptions* options,
+                                              const TirtcTransportConnServiceCallbacks* callbacks,
+                                              void* user_data,
+                                              TirtcTransportConnService** out_service);
+
+/**
+ * @brief Stop service runtime.
+ */
+TirtcError 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.
+ */
+TirtcError tirtc_transport_connect(const TirtcTransportConnOptions* options,
+                                   TirtcTransportConn** out_connection);
+
+/**
+ * @brief Set or replace connection observer.
+ *
+ * The implementation may synchronously replay the current state according to
+ * contract.
+ */
+TirtcError tirtc_transport_conn_set_callbacks(TirtcTransportConn* connection,
+                                              const TirtcTransportConnCallbacks* callbacks,
+                                              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.
+ */
+TirtcError 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.
+ */
+TirtcError tirtc_transport_conn_get_send_buffer_used(TirtcTransportConn* connection,
+                                                     size_t* out_bytes);
+
+/**
+ * @brief Request local disconnect.
+ *
+ * Disconnected completion is reported by on_state_changed callback.
+ */
+TirtcError 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.
+ */
+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.
+ */
+TirtcError tirtc_transport_request_key_frame(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.
+ */
+TirtcError tirtc_transport_subscribe_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.
+ */
+TirtcError tirtc_transport_unsubscribe_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.
+ */
+TirtcError tirtc_transport_subscribe_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.
+ */
+TirtcError tirtc_transport_unsubscribe_audio(TirtcTransportConn* connection, uint8_t stream_id);
+
+/**
+ * @brief Send typed audio frame.
+ */
+TirtcError tirtc_transport_send_audio_frame(TirtcTransportConn* connection,
+                                            const TirtcTransportAudioFrame* frame);
+
+/**
+ * @brief Send typed video frame.
+ */
+TirtcError tirtc_transport_send_video_frame(TirtcTransportConn* connection,
+                                            const TirtcTransportVideoFrame* frame);
+
+/**
+ * @brief Send stream-message payload in media channel.
+ */
+TirtcError tirtc_transport_send_stream_message(TirtcTransportConn* connection,
+                                               const TirtcTransportStreamMessage* message);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif  // TIRTC_TRANSPORT_H_

package/vendor/runtime/linux-x64/include/tirtc/trp.h

@@ -0,0 +1,187 @@
+/** @file trp.h
+ *  @brief Facade transport-facing public C API.
+ */
+
+#ifndef TIRTC_FACADE_TRP_H_
+#define TIRTC_FACADE_TRP_H_
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include "tirtc/error.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef struct TirtcInitOptions {
+  const char* app_id;
+
+  const char* endpoint;
+
+  const char* log_root_dir;
+
+  int console_log_enabled;
+
+} TirtcInitOptions;
+
+typedef enum TirtcMediaSendPolicy {
+
+  TIRTC_MEDIA_SEND_POLICY_ON_REQUEST = 0,
+
+  TIRTC_MEDIA_SEND_POLICY_AUTO_ON_CONNECTED = 1,
+} TirtcMediaSendPolicy;
+
+typedef struct TirtcConnServiceStartOptions {
+  const char* license;
+
+  uint32_t max_connections;
+
+  TirtcMediaSendPolicy media_send_policy;
+} TirtcConnServiceStartOptions;
+
+typedef struct TirtcConnConnectOptions {
+  const char* remote_id;
+
+  const char* token;
+} TirtcConnConnectOptions;
+
+typedef struct TirtcConnCreateOptions {
+  const struct TirtcConnCallbacks* callbacks;
+
+  void* user_data;
+} TirtcConnCreateOptions;
+
+typedef struct TirtcConnService TirtcConnService;
+
+typedef struct TirtcConn TirtcConn;
+
+typedef enum TirtcConnState {
+
+  TIRTC_CONN_STATE_IDLE = 0,
+
+  TIRTC_CONN_STATE_CONNECTING = 1,
+
+  TIRTC_CONN_STATE_CONNECTED = 2,
+
+  TIRTC_CONN_STATE_DISCONNECTED = 3,
+} TirtcConnState;
+
+typedef struct TirtcStreamMessage {
+  uint32_t timestamp_ms;
+
+  const void* data;
+
+  size_t length;
+} TirtcStreamMessage;
+
+typedef struct TirtcConnCommand {
+  uint32_t command;
+
+  const void* data;
+
+  size_t length;
+} TirtcConnCommand;
+
+typedef struct TirtcConnMetricsSnapshot {
+  int has_connect_start;
+  int has_connected;
+  uint64_t connect_start_monotonic_ms;
+  uint64_t connected_monotonic_ms;
+} TirtcConnMetricsSnapshot;
+
+/** Heap-owned byte payload allocated by facade callback dispatch. */
+typedef struct TirtcOwnedBytes {
+  /** Payload buffer allocated by facade, or `NULL` for zero-length payloads. */
+  void* data;
+
+  /** Number of bytes stored in `data`. */
+  size_t length;
+} TirtcOwnedBytes;
+
+/** Heap-owned UTF-8 string allocated by facade callback dispatch. */
+typedef struct TirtcOwnedString {
+  /** Null-terminated UTF-8 buffer allocated by facade, or `NULL` when no message is available. */
+  char* data;
+} TirtcOwnedString;
+
+typedef struct TirtcConnServiceCallbacks {
+  void (*on_started)(TirtcConnService* service, void* user_data);
+
+  void (*on_stopped)(TirtcConnService* service, void* user_data);
+
+  void (*on_connected)(TirtcConnService* service, TirtcConn* connection, void* user_data);
+
+  void (*on_error)(TirtcConnService* service, TirtcError error, const char* message,
+                   void* user_data);
+} TirtcConnServiceCallbacks;
+
+/**
+ * Connection observer installed through `tirtc_conn_create()` or `tirtc_conn_set_callbacks()`.
+ *
+ * For `on_command()` and `on_stream_message()`, facade copies the variable-length payload to heap
+ * memory before dispatch. The callback receives ownership of that payload and must release it with
+ * `tirtc_owned_bytes_release()` after converting or copying the bytes it needs. The release API is
+ * NULL-safe. If facade cannot allocate an owned copy for a non-empty payload, it drops that
+ * callback delivery rather than dispatching a borrowed pointer.
+ */
+typedef struct TirtcConnCallbacks {
+  void (*on_state_changed)(TirtcConn* connection, TirtcConnState state, TirtcError error,
+                           void* user_data);
+
+  void (*on_command)(TirtcConn* connection, uint32_t command, TirtcOwnedBytes* owned_payload,
+                     void* user_data);
+
+  void (*on_stream_message)(TirtcConn* connection, uint8_t stream_id, uint32_t timestamp_ms,
+                            TirtcOwnedBytes* owned_payload, void* user_data);
+} TirtcConnCallbacks;
+
+TirtcError tirtc_init(const TirtcInitOptions* options);
+
+void tirtc_uninit(void);
+
+TirtcError tirtc_conn_service_start(const TirtcConnServiceStartOptions* options,
+                                    const TirtcConnServiceCallbacks* observer, void* user_data,
+                                    TirtcConnService** out_service);
+
+TirtcError tirtc_conn_service_stop(TirtcConnService* service);
+
+TirtcError tirtc_conn_create(const TirtcConnCreateOptions* options, TirtcConn** out_connection);
+
+TirtcError tirtc_conn_set_callbacks(TirtcConn* connection, const TirtcConnCallbacks* callbacks,
+                                    void* user_data);
+
+TirtcError tirtc_conn_connect(TirtcConn* connection, const TirtcConnConnectOptions* options);
+
+TirtcError tirtc_conn_disconnect(TirtcConn* connection);
+
+void tirtc_conn_destroy(TirtcConn* connection);
+
+TirtcError tirtc_conn_send_stream_message(TirtcConn* connection, uint8_t stream_id,
+                                          const TirtcStreamMessage* message);
+
+/** Copies a stream-message payload into a releasable owned buffer. */
+TirtcOwnedBytes* tirtc_stream_message_copy_payload(const TirtcStreamMessage* message);
+
+/** Copies a command payload into a releasable owned buffer. */
+TirtcOwnedBytes* tirtc_conn_command_copy_payload(const TirtcConnCommand* command);
+
+/** Copies a UTF-8 string into a releasable owned buffer. */
+TirtcOwnedString* tirtc_string_copy_owned(const char* message);
+
+/** Releases a payload received from facade owned-memory callback APIs. Safe to call with `NULL`. */
+void tirtc_owned_bytes_release(TirtcOwnedBytes* owned);
+
+/** Releases a string received from facade owned-memory callback APIs. Safe to call with `NULL`. */
+void tirtc_owned_string_release(TirtcOwnedString* owned);
+
+TirtcError tirtc_conn_send_command(TirtcConn* connection, const TirtcConnCommand* command);
+
+TirtcError tirtc_metrics_conn_get_snapshot(TirtcConn* connection,
+                                           TirtcConnMetricsSnapshot* out_snapshot);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif