tirtc-devtools-cli 0.0.11 → 0.0.12

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

@@ -1,3 +1,7 @@
+/** @file trp.h
+ *  @brief Facade transport-facing public C API.
+ */
+
 #ifndef TIRTC_FACADE_TRP_H_
 #define TIRTC_FACADE_TRP_H_
 
@@ -10,444 +14,162 @@
 extern "C" {
 #endif
 
-/**
- * @file tirtc/trp.h
- * @brief Base transport-facing facade API for TiRTC.
- *
- * This header defines the public control-plane contract that every higher
- * facade layer builds on.
- *
- * Typical usage:
- * 1. Call ::tirtc_init once for the process.
- * 2. Either start a service with ::tirtc_conn_service_start, or create a
- *    standalone connection with ::tirtc_conn_create and then connect it with
- *    ::tirtc_conn_connect.
- * 3. Install callbacks if the caller needs connection, command, or stream
- *    events.
- * 4. Exchange stream messages and commands while the connection is alive.
- * 5. Explicitly close resources with the matching stop, disconnect, destroy,
- *    and uninit calls.
- *
- * Higher-level headers extend this contract rather than replace it:
- * - `tirtc/audio.h` adds audio input and audio output objects.
- * - `tirtc/av.h` adds video input and video output objects.
- *
- * Ownership model:
- * - The caller owns every public handle returned by this facade.
- * - The runtime owns internal transport and media pipelines.
- * - Public handles must be released with their documented matching API.
- */
-
-/**
- * @brief Global runtime options passed to ::tirtc_init.
- *
- * The runtime resolves the effective endpoint during initialization and copies
- * the values it needs. String pointers only need to remain valid for the
- * duration of the ::tirtc_init call.
- */
 typedef struct TirtcOptions {
-  /**
-   * @brief Optional explicit service endpoint.
-   *
-   * When non-NULL and not empty, this value overrides the built-in endpoint
-   * selected by ::environment.
-   */
   const char* endpoint;
 
-  /**
-   * @brief Optional directory used to initialize file logging.
-   *
-   * Pass NULL or an empty string to disable file logging.
-   */
   const char* log_root_dir;
 
-  /**
-   * @brief Non-zero to enable console logging; zero to disable it.
-   */
   int enable_console_log;
 
-  /**
-   * @brief Built-in environment selector used when ::endpoint is not supplied.
-   *
-   * The current implementation recognizes these values:
-   * - `0`: test
-   * - `1`: pre-production
-   * - `2`: production
-   *
-   * Any other value currently falls back to the production endpoint.
-   */
-  int environment;
 } TirtcOptions;
 
-/**
- * @brief Default media send policy applied by the facade.
- *
- * The effective send gate still uses `connection + stream_id + media_kind` as
- * the smallest scope. The policy only decides how those gates become open.
- */
 typedef enum TirtcMediaSendPolicy {
-  /**
-   * @brief Keep send gates closed until the consumer explicitly opens them.
-   */
+
   TIRTC_MEDIA_SEND_POLICY_ON_REQUEST = 0,
 
-  /**
-   * @brief Open send gates automatically once the accepted connection exists.
-   *
-   * When the bound input is ready, the facade may start sending without first
-   * waiting for an explicit remote request.
-   */
   TIRTC_MEDIA_SEND_POLICY_AUTO_ON_CONNECTED = 1,
 } TirtcMediaSendPolicy;
 
-/**
- * @brief Options for starting a service-side connection listener.
- *
- * A service accepts inbound transport connections and exposes them through
- * ::TirtcConnServiceCallbacks.on_connected.
- */
 typedef struct TirtcConnServiceStartOptions {
-  /**
-   * @brief Non-empty service license string.
-   *
-   * This field is required.
-   */
   const char* license;
 
-  /**
-   * @brief Maximum number of concurrently accepted connections.
-   *
-   * 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.
-   *
-   * This field is required and must be non-zero.
-   */
   uint32_t max_connections;
 
-  /**
-   * @brief Service-level media send policy applied to accepted connections.
-   *
-   * This policy controls how the facade opens per-connection send gates after
-   * a connection becomes available. It does not change the underlying
-   * transport request/release primitives.
-   */
   TirtcMediaSendPolicy media_send_policy;
 } TirtcConnServiceStartOptions;
 
-/**
- * @brief Options for connecting an outbound connection object.
- */
 typedef struct TirtcConnConnectOptions {
-  /**
-   * @brief Remote peer identifier.
-   *
-   * This field is required and must be non-empty.
-   */
   const char* peer_id;
 
-  /**
-   * @brief Authentication or session token embedded into the transport
-   * descriptor.
-   *
-   * This field is required and must be non-empty.
-   */
   const char* token;
 } TirtcConnConnectOptions;
 
-/**
- * @brief Optional callbacks bound when a connection object is created.
- *
- * The implementation copies the callback table and stores the supplied
- * user_data pointer with the created connection handle.
- */
 typedef struct TirtcConnCreateOptions {
-  /** @brief Optional callbacks copied into the new connection object. */
   const struct TirtcConnCallbacks* callbacks;
 
-  /** @brief Opaque pointer returned to connection callbacks. */
   void* user_data;
 } TirtcConnCreateOptions;
 
-/** @brief Opaque handle returned by ::tirtc_conn_service_start. */
 typedef struct TirtcConnService TirtcConnService;
 
-/**
- * @brief Opaque connection handle.
- *
- * A handle may come from either ::tirtc_conn_create or a service callback's
- * ::TirtcConnServiceCallbacks.on_connected callback.
- */
 typedef struct TirtcConn TirtcConn;
 
-/**
- * @brief High-level connection state reported through ::TirtcConnCallbacks.
- */
 typedef enum TirtcConnState {
-  /** Connection exists but has not started connecting yet. */
+
   TIRTC_CONN_STATE_IDLE = 0,
 
-  /** Connection establishment is in progress. */
   TIRTC_CONN_STATE_CONNECTING = 1,
 
-  /** Transport is connected and ready for control or media attachment. */
   TIRTC_CONN_STATE_CONNECTED = 2,
 
-  /** Connection has entered its terminal disconnected state. */
   TIRTC_CONN_STATE_DISCONNECTED = 3,
 } TirtcConnState;
 
-/**
- * @brief Binary stream-message payload.
- *
- * Stream messages are intended for lightweight application-defined payloads on
- * stream identifiers that are not currently reserved by attached audio or video
- * routes.
- */
 typedef struct TirtcStreamMessage {
-  /** @brief Sender-defined timestamp in milliseconds. */
   uint32_t timestamp_ms;
 
-  /**
-   * @brief Pointer to payload bytes.
-   *
-   * The pointer may be NULL only when ::length is zero.
-   */
   const void* data;
 
-  /** @brief Payload size in bytes. */
   size_t length;
 } TirtcStreamMessage;
 
-/**
- * @brief Application-defined command payload.
- *
- * command is an opaque raw 32-bit value. The facade forwards it unchanged to
- * and from the underlying transport backend.
- */
 typedef struct TirtcConnCommand {
-  /** @brief Opaque raw 32-bit command word agreed with the remote peer. */
   uint32_t command;
 
-  /** @brief Payload bytes, or NULL when ::length is zero. */
   const void* data;
 
-  /** @brief Payload size in bytes. */
   size_t length;
 } TirtcConnCommand;
 
-/**
- * @brief Optional callbacks for service lifecycle and accepted connections.
- *
- * The implementation copies this structure when the service starts. The
- * structure itself does not need to remain alive after
- * ::tirtc_conn_service_start returns.
- */
+/** 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 {
-  /** @brief Called after the service has started successfully. */
   void (*on_started)(TirtcConnService* service, void* user_data);
 
-  /** @brief Called after the service has stopped successfully. */
   void (*on_stopped)(TirtcConnService* service, void* user_data);
 
-  /**
-   * @brief Called for each inbound connection accepted by the service.
-   *
-   * Ownership of the returned ::TirtcConn handle belongs to the caller. The
-   * caller must eventually disconnect and destroy that connection.
-   *
-   * The runtime will not dispatch other user-facing callbacks for that
-   * accepted connection until this callback returns. Callers that need full
-   * callback coverage should install the connection callbacks synchronously
-   * inside this callback before returning.
-   */
   void (*on_connected)(TirtcConnService* service, TirtcConn* connection, void* user_data);
 
-  /**
-   * @brief Called when the service reports an error or a promoted system event.
-   */
   void (*on_error)(TirtcConnService* service, TirtcError error, const char* message,
                    void* user_data);
 } TirtcConnServiceCallbacks;
 
 /**
- * @brief Optional callbacks for connection lifecycle and control-plane events.
- *
- * The implementation stores a copy of this structure inside the owning
- * connection object.
+ * Connection observer installed through `tirtc_conn_create()` or `tirtc_conn_set_callbacks()`.
  *
- * Callback threading is not restricted to a single caller thread. Some
- * callbacks may be replayed synchronously when a connection object becomes
- * visible to the caller, while others may arrive asynchronously from the
- * internal transport layer.
+ * 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 {
-  /** @brief Called when the connection state changes or is replayed. */
   void (*on_state_changed)(TirtcConn* connection, TirtcConnState state, TirtcError error,
                            void* user_data);
 
-  /** @brief Called when an application-defined command is received. */
-  void (*on_command)(TirtcConn* connection, const TirtcConnCommand* command, void* user_data);
+  void (*on_command)(TirtcConn* connection, uint32_t command, TirtcOwnedBytes* owned_payload,
+                     void* user_data);
 
-  /**
-   * @brief Called when an application-defined stream message is received.
-   */
-  void (*on_stream_message)(TirtcConn* connection, uint8_t stream_id,
-                            const TirtcStreamMessage* message, void* user_data);
+  void (*on_stream_message)(TirtcConn* connection, uint8_t stream_id, uint32_t timestamp_ms,
+                            TirtcOwnedBytes* owned_payload, void* user_data);
 } TirtcConnCallbacks;
 
-/**
- * @brief Initialize the global runtime.
- *
- * Call this exactly once before creating services, connections, audio objects,
- * or video objects.
- *
- * @param options Non-NULL runtime options.
- * @return ::TIRTC_ERROR_OK on success, or an error code when initialization
- * fails or the runtime is already initialized.
- */
 TirtcError tirtc_init(const TirtcOptions* options);
 
-/**
- * @brief Shut down the global runtime.
- *
- * This function is intentionally conservative. If any public handles are still
- * alive, the current implementation leaves the runtime initialized and returns
- * without tearing it down. Destroy every connection, stop every service, and
- * destroy every media object before calling this function.
- */
 void tirtc_uninit(void);
 
-/**
- * @brief Start a service-side listener.
- *
- * Only one live service is supported at a time.
- *
- * @param options Non-NULL start options with a non-empty license and a non-zero
- * max_connections.
- * @param observer Optional callback table copied by value.
- * @param user_data Opaque pointer returned to service callbacks.
- * @param out_service Receives the created service handle on success.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_service_start(const TirtcConnServiceStartOptions* options,
                                     const TirtcConnServiceCallbacks* observer, void* user_data,
                                     TirtcConnService** out_service);
 
-/**
- * @brief Stop a service handle.
- *
- * Accepted connections are separate resources and are not destroyed by stopping
- * the service. Each accepted ::TirtcConn remains the caller's responsibility.
- * On success, the service handle is released and must not be used again.
- *
- * @param service Service handle to stop.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_service_stop(TirtcConnService* service);
 
-/**
- * @brief Allocate a standalone connection handle.
- *
- * The runtime must already be initialized. The returned handle starts in
- * ::TIRTC_CONN_STATE_IDLE and must be released with ::tirtc_conn_destroy.
- *
- * The callbacks, when provided, become part of the connection object's stable
- * lifecycle contract. After creation succeeds, reconnects on the same handle
- * keep using that callback table.
- *
- * @param options Optional creation options. Pass NULL to create a connection
- * without callbacks.
- * @param out_connection Receives the created connection handle on success.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_create(const TirtcConnCreateOptions* options, TirtcConn** out_connection);
 
-/**
- * @brief Install, replace, or clear the connection callbacks.
- *
- * This API remains available for accepted service connections and existing
- * consumers that still bind callbacks after handle creation. New
- * standalone-connection callers should prefer binding callbacks through
- * ::TirtcConnCreateOptions.
- *
- * Passing NULL for ::callbacks clears the current callbacks and their user
- * data. After non-NULL callbacks are installed, the implementation
- * immediately replays the current state through ::on_state_changed. When the
- * current state is ::TIRTC_CONN_STATE_DISCONNECTED, the replayed callback also
- * carries the final disconnect error.
- */
 TirtcError tirtc_conn_set_callbacks(TirtcConn* connection, const TirtcConnCallbacks* callbacks,
                                     void* user_data);
 
-/**
- * @brief Connect a standalone connection handle to a remote peer.
- *
- * This function is valid only for handles created by ::tirtc_conn_create.
- * Connections accepted from a service are already transport-owned and cannot be
- * manually connected again.
- *
- * After a disconnect, the same handle may be connected again.
- *
- * @param connection Target connection created by ::tirtc_conn_create.
- * @param options Non-NULL connect options with non-empty peer and token values.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_connect(TirtcConn* connection, const TirtcConnConnectOptions* options);
 
-/**
- * @brief Disconnect a connection.
- *
- * This call is idempotent once the connection is already idle or disconnected.
- * Disconnecting does not destroy the handle.
- *
- * @param connection Target connection.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_disconnect(TirtcConn* connection);
 
-/**
- * @brief Destroy a connection handle and release its internal transport state.
- *
- * Destroying a connection also detaches any currently attached audio or video
- * objects. Those media objects are not destroyed; they return to an unbound
- * state and remain owned by the caller.
- *
- * After this call returns, the connection handle is invalid and must not be
- * reused.
- *
- * @param connection Connection handle to destroy.
- */
 void tirtc_conn_destroy(TirtcConn* connection);
 
-/**
- * @brief Send an application-defined stream message.
- *
- * Use a stream identifier that is not currently occupied by an attached audio
- * input, video input, or video output on the same connection.
- *
- * @param connection Target connection.
- * @param stream_id Application-defined stream identifier for this message.
- * @param message Non-NULL payload descriptor.
- * @return ::TIRTC_ERROR_OK on success.
- */
 TirtcError tirtc_conn_send_stream_message(TirtcConn* connection, uint8_t stream_id,
                                           const TirtcStreamMessage* message);
 
-/**
- * @brief Send an application-defined command without waiting for a response.
- *
- * The facade treats ::TirtcConnCommand.command as an opaque raw 32-bit value.
- * Any request/reply correlation is owned by the caller's higher-level
- * protocol, not by the standard facade contract.
- *
- * @param connection Target connection.
- * @param command Non-NULL command payload.
- * @return ::TIRTC_ERROR_OK on success.
- */
+/** 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);
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif  // TIRTC_FACADE_TRP_H_
+#endif

package/vendor/app-server/bin/runtime/macos-arm64/manifest.txt

@@ -1,9 +1,9 @@
 platform=macos-arm64
 profile=credential
-staged_at_utc=2026-04-21T05:02:19Z
+staged_at_utc=2026-04-21T13:44:23Z
 source_sdk=/Users/allenfeng/Development/Repositories/tirtc-nexus/tirtc-matrix/.build/sdk/macos-arm64
 
-907ec636c86ec9737ee4da0ae4c26e8435104effbaa96e731b1bece9c44f6837  include/tirtc/audio.h
+bfea7c19fdc3f25680946a575db9b3e60e8cd2b3fe1ddde8c7c93b57a6a3902c  include/tirtc/audio.h
 6d972ccfe150a3b4f2d7f18fa92b3ade9210c1c8bb754d061ac6b7997b59e2cb  include/tirtc/audio_codec.h
 7bacbdb2d8bb10d6444036a8fef42f2a8e3ea34dfc38e165ee678d61f189db41  include/tirtc/audio_frame.h
 84f1bbe67efa15ab3b2d995d661025aac43e2fe547a14a012a24d89cfe3cb859  include/tirtc/audio_io.h
@@ -13,7 +13,7 @@ c2e1f31dcc75be461c577d18b1cebe32774f212d51cb4dd2a5b5a9bfe62b693e  include/tirtc/
 51cbc911fe9f9834046f0e0a1a7cdd814a8e194a615894a8b4d11f9e5f095610  include/tirtc/audio_io_windows.h
 21f60729117260a44af22c1af986ef17d22673b102b7b7a035f492d0665cce16  include/tirtc/audio_processing.h
 0ca7c3c630b1242f51a0fd8154097c0a332b4c816a5707090e4381719852998c  include/tirtc/audio_sample_rate.h
-2924a8466027b05cf148a1ec173a199d09719ae0ad6c6393521eeb6e594d31fa  include/tirtc/av.h
+339508d784d3114dd3cbf14ad90dd6345d633ec647ca0f9bb8942eb1b83533b2  include/tirtc/av.h
 4198c95c48ae579d1c782635b00fa5c9009d0c56ba466e6e3873e8298faae029  include/tirtc/credential.h
 d29f24fc665d01ab45f993c06c09fccca2bd5c844250ddbdc3c9d8d0c8548803  include/tirtc/error.h
 ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/foundation/build_info.h
@@ -26,7 +26,7 @@ ae805545a9515edc9b94262e72ad2c7b7d649288166f4daeb450d8a55e82ae0b  include/tirtc/
 a4f8ab44c1a20ad37f250363a403a9d4d007e61ddb2426c7966dbc05f6a04b4f  include/tirtc/media_live_source.h
 1b3be6954e547f91a047866438bff1820c8406afaf91cef68ddee29a6ac70234  include/tirtc/media_uplink.h
 26b831c7b8bd69b7699017427f3243cd22393c90c9518a820f5eb87eb3792483  include/tirtc/transport.h
-7942e62271793acd78b51a2431f25e4ccba5759eb229d06e3f582ba7f1b83401  include/tirtc/trp.h
+185183a736774cdf737504c091e4648d7f476c16abf18ee8c8ac0da2eb9a5c79  include/tirtc/trp.h
 dff5b0a0ac4a40ad17c93e1e56b3c416371c81ab365e287ea8cd6ce37ccbed3b  include/tirtc/video_codec.h
 e51379666c199588cc33279ccf52248035d1cae3d1d468b1615ebf29f0b39c9c  include/tirtc/video_frame.h
 d920afad955b9f206b02b19ca152315190fa84ab6f24e895a5b24c3ab9ffd701  include/tirtc/video_io.h
@@ -39,14 +39,14 @@ cae0bbeb884e5466a56da15182c78cc22baab6c743f349a58d3595f623333585  include/tirtc/
 8db86d6714264047e8fd4086ddd7315722d675749719e6175f89eb5a636b48a1  lib/libTiRTC.a
 b39daee6a3d39bf0ca20c45084601133c4198de8dca848dcff6dd9c70ae99016  lib/libcrypto.a
 c052857ef315e3d61db9c862cad10709a3a6b2487dc41799cbe4d74a805de875  lib/libcrypto.dylib
-f164a59d6b1143f731fa8321cfa722921fa519a32403a064cb81bf524db2b50e  lib/libmatrix_runtime_audio.a
-fc7a666614a15cb5fdd1a770f41a0609768b4794ff7d077dd9a9747e139df784  lib/libmatrix_runtime_credential.a
-98231e83ddf8779346f48125d900f130c130b4809e69cbca4c3d72f4d3c27819  lib/libmatrix_runtime_facade.a
-4c20a760f2ca92c23bd660f0ba598e23d1222be5b347111314df391c7398cf60  lib/libmatrix_runtime_foundation_http.a
-7838ab65c09fcf5bfe85dc4d66211d890b0723ef34f222f33b758d7a70dcece5  lib/libmatrix_runtime_foundation_logging.a
-e02de795cbb7298877e7b13c082523c9565a3369dd2fef37487ed55d3851a32b  lib/libmatrix_runtime_media.a
-44fbcb9fb34f7866a45b685d0fa0d056ab5bc9e2034c7fd5e83edc486336c939  lib/libmatrix_runtime_transport.a
-e4970a72017482cec4a3eb3dff6ca404af34348df0426731e431a3d7e4739a42  lib/libmatrix_runtime_video.a
+a3cbd2372889b96346fb211846de94edb5ec7f5d15af02a150c3c24efb999187  lib/libmatrix_runtime_audio.a
+012cf0bd9aaa49fe42a43de19edddb01b654df741a0f5782568c52f0d3c8dfbb  lib/libmatrix_runtime_credential.a
+75554a31b1c99be83d22f168de91584f19dc9ee69a13fe8b62d5dfdab6baf016  lib/libmatrix_runtime_facade.a
+a5235f14059d7807968353b32cefcddbebec2cc5808912898078a6c6cf9bdd50  lib/libmatrix_runtime_foundation_http.a
+dcb14497951c566352cf4b14a7b870872069824d6a2a067bfe5b421fc6500216  lib/libmatrix_runtime_foundation_logging.a
+1b1b7980f498b603132bf11dce7d24f60bdc8a11d6a0ac916c4454dde4ebbc3f  lib/libmatrix_runtime_media.a
+6d6bf7d07cc35df568582218193487235452ef47dd736f36d7de3c95ac1bde18  lib/libmatrix_runtime_transport.a
+0abee197077a906f6af3f5e05c72bcfe5b874478b65ad454b3013ab9df398af1  lib/libmatrix_runtime_video.a
 c11c65d373a127028350c41fa58cd2d1223f2b5d70a84e13b115d90daaba25ca  lib/libssl.a
 ef1c1104bbdd2528ed7b958fb7252bd6249875f92300b0c9577d6c4bd6c0d88a  lib/libssl.dylib
 e14e846e43d64e240fa0e5745bf4e702b79d0f2442e7f768beb990610735c71b  lib/libtgrtc.dylib