tirtc-devtools-cli 0.0.10 → 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,621 +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 observers if the caller needs connection, command, or stream
- *    callbacks.
- * 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
- * ::TirtcConnServiceObserver.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 observer bound when a connection object is created.
- *
- * The implementation copies the observer structure and stores the supplied
- * user_data pointer with the created connection handle.
- */
 typedef struct TirtcConnCreateOptions {
-  /** @brief Optional observer copied into the new connection object. */
-  const struct TirtcConnObserver* observer;
+  const struct TirtcConnCallbacks* callbacks;
 
-  /** @brief Opaque pointer returned to observer 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 observer's
- * ::TirtcConnServiceObserver.on_connected callback.
- */
 typedef struct TirtcConn TirtcConn;
 
-/**
- * @brief High-level connection state reported through ::TirtcConnObserver.
- */
 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 Reason associated with a disconnected connection.
- */
-typedef enum TirtcConnDisconnectReason {
-  /** The implementation could not determine a more specific reason. */
-  TIRTC_CONN_DISCONNECT_REASON_UNKNOWN = 0,
-
-  /** The local side closed the connection intentionally. */
-  TIRTC_CONN_DISCONNECT_REASON_LOCAL_CLOSED = 1,
-
-  /** The remote side closed the connection. */
-  TIRTC_CONN_DISCONNECT_REASON_REMOTE_CLOSED = 2,
-
-  /** Initial connection setup failed. */
-  TIRTC_CONN_DISCONNECT_REASON_CONNECT_FAILED = 3,
-
-  /** Descriptor exchange or validation failed. */
-  TIRTC_CONN_DISCONNECT_REASON_INVALID_DESCRIPTOR = 4,
-
-  /** The underlying transport backend reported an internal failure. */
-  TIRTC_CONN_DISCONNECT_REASON_BACKEND_ERROR = 5,
-} TirtcConnDisconnectReason;
-
-/**
- * @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 Fire-and-forget command payload.
- *
- * Command identifiers are application-defined and must be agreed with the
- * remote peer.
- *
- * The current runtime accepts application command ids in the range
- * `[0x1000, 0x7FFF]`. Values below `0x1000` are reserved for
- * runtime-internal commands and must not be used by consumers.
- */
 typedef struct TirtcConnCommand {
-  /**
-   * @brief Application-defined command identifier agreed with the remote peer.
-   *
-   * A request and its reply typically reuse the same ::command_id, while the
-   * per-request correlation is carried separately by ::remote_request_id.
-   */
-  uint16_t command_id;
-
-  /** @brief Payload bytes, or NULL when ::length is zero. */
-  const void* data;
-
-  /** @brief Payload size in bytes. */
-  size_t length;
-} TirtcConnCommand;
+  uint32_t command;
 
-/**
- * @brief Request payload for an asynchronous command round-trip.
- *
- * Command identifiers are application-defined and must be agreed with the
- * remote peer.
- *
- * The current runtime accepts application command ids in the range
- * `[0x1000, 0x7FFF]`. Values below `0x1000` are reserved for
- * runtime-internal commands and must not be used by consumers.
- */
-typedef struct TirtcConnCommandRequest {
-  /**
-   * @brief Application-defined command identifier agreed with the remote peer.
-   *
-   * In the common request-response pattern, the responder echoes the same
-   * ::command_id back in ::TirtcConnCommandResponse.
-   */
-  uint16_t command_id;
-
-  /** @brief Payload bytes, or NULL when ::length is zero. */
   const void* data;
 
-  /** @brief Payload size in bytes. */
   size_t length;
+} TirtcConnCommand;
 
-  /**
-   * @brief Response timeout in milliseconds.
-   *
-   * A value of zero is currently treated as a minimal non-zero timeout rather
-   * than an infinite wait.
-   */
-  uint32_t timeout_ms;
-} TirtcConnCommandRequest;
-
-/**
- * @brief Response payload returned by a remote peer or local reply logic.
- *
- * Command identifiers are application-defined and must be agreed with the
- * remote peer.
- *
- * The current runtime accepts application command ids in the range
- * `[0x1000, 0x7FFF]`. Values below `0x1000` are reserved for
- * runtime-internal commands and must not be used by consumers.
- */
-typedef struct TirtcConnCommandResponse {
-  /**
-   * @brief Application-defined command identifier agreed with the remote peer.
-   *
-   * This usually matches the original request's ::command_id.
-   */
-  uint16_t command_id;
-
-  /** @brief Payload bytes, or NULL when ::length is zero. */
-  const void* data;
+/** 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;
 
-  /** @brief Payload size in bytes. */
+  /** Number of bytes stored in `data`. */
   size_t length;
-} TirtcConnCommandResponse;
+} TirtcOwnedBytes;
 
-/**
- * @brief Completion callback used by ::tirtc_conn_request_command.
- *
- * The callback may complete because of a successful response, a send failure,
- * a timeout, or a disconnect. The callback is not invoked after the connection
- * has been destroyed.
- *
- * Delivery may be synchronous or asynchronous:
- * - If request submission fails immediately, the callback may run before
- *   ::tirtc_conn_request_command returns.
- * - After request submission succeeds, completion is reported later from the
- *   transport or timeout path.
- *
- * Callers must not assume a fixed callback thread, and must write callback
- * logic so it is safe for reentrant delivery relative to
- * ::tirtc_conn_request_command and other connection callbacks.
- *
- * @param connection Connection that owns the request.
- * @param error Completion status.
- * @param response Non-NULL only when a response payload is available.
- * @param user_data Opaque pointer originally passed to
- * ::tirtc_conn_request_command.
- */
-typedef void (*TirtcConnCommandResponseFn)(TirtcConn* connection, TirtcError error,
-                                           const TirtcConnCommandResponse* response,
-                                           void* user_data);
+/** 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;
 
-/**
- * @brief Optional observer 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.
- */
-typedef struct TirtcConnServiceObserver {
-  /** @brief Called after the service has started successfully. */
+typedef struct TirtcConnServiceCallbacks {
   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 observer 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);
-} TirtcConnServiceObserver;
+} TirtcConnServiceCallbacks;
 
 /**
- * @brief Optional observer 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 TirtcConnObserver {
-  /** @brief Called when the connection state changes or is replayed. */
-  void (*on_state_changed)(TirtcConn* connection, TirtcConnState state, void* user_data);
-
-  /**
-   * @brief Called when the connection enters DISCONNECTED, or when that
-   * terminal state is replayed to a newly installed observer.
-   */
-  void (*on_disconnected)(TirtcConn* connection, TirtcConnDisconnectReason reason, void* user_data);
-
-  /**
-   * @brief Called for an inbound command request that expects a reply.
-   *
-   * The supplied ::remote_request_id remains valid only while the request is
-   * still pending on this connection. In the common case, reply exactly once
-   * with ::tirtc_conn_reply_remote_command.
-   */
-  void (*on_remote_command_request)(TirtcConn* connection, uint64_t remote_request_id,
-                                    const TirtcConnCommand* command, 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);
-
-  /** @brief Called when the transport reports an error for this connection. */
-  void (*on_error)(TirtcConn* connection, TirtcError error, const char* message, void* user_data);
-} TirtcConnObserver;
+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;
 
-/**
- * @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 observer copied by value.
- * @param user_data Opaque pointer returned to observer 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 TirtcConnServiceObserver* observer, void* user_data,
+                                    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 observer, when provided, becomes part of the connection object's stable
- * lifecycle contract. After creation succeeds, reconnects on the same handle
- * keep using that observer.
- *
- * @param options Optional creation options. Pass NULL to create a connection
- * without an observer.
- * @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 observer.
- *
- * This legacy API remains available for accepted service connections and
- * existing consumers that still bind observers after handle creation.
- * New standalone-connection callers should prefer binding the observer through
- * ::TirtcConnCreateOptions.
- *
- * Passing NULL for ::observer clears the current observer and its user data.
- * After a non-NULL observer is installed, the implementation immediately
- * replays the current state and, when applicable, the terminal disconnected
- * callback.
- */
-TirtcError tirtc_conn_set_observer(TirtcConn* connection, const TirtcConnObserver* observer,
-                                   void* user_data);
+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.
- *
- * Choose ::TirtcConnCommand.command_id from the command ids agreed with the
- * remote peer. The current runtime accepts application command ids in
- * `[0x1000, 0x7FFF]`; values below `0x1000` are reserved for
- * runtime-internal commands.
- *
- * @param connection Target connection.
- * @param command Non-NULL command payload.
- * @return ::TIRTC_ERROR_OK on success.
- */
-TirtcError tirtc_conn_send_command(TirtcConn* connection, const TirtcConnCommand* command);
+/** Copies a stream-message payload into a releasable owned buffer. */
+TirtcOwnedBytes* tirtc_stream_message_copy_payload(const TirtcStreamMessage* message);
 
-/**
- * @brief Send an application-defined request command and complete it
- * asynchronously.
- *
- * Choose ::TirtcConnCommandRequest.command_id from the command ids agreed
- * with the remote peer. The current runtime accepts application command
- * ids in `[0x1000, 0x7FFF]`; values below `0x1000` are reserved for
- * runtime-internal commands.
- *
- * Callback delivery is mixed synchronous/asynchronous. If request submission
- * fails immediately after the facade has accepted the request, ::callback may
- * run before this function returns. After request submission succeeds,
- * completion is reported later from the response, timeout, or disconnect path.
- *
- * Once this call returns ::TIRTC_ERROR_OK, expect exactly one completion
- * callback unless the connection is destroyed first.
- *
- * @param connection Target connection.
- * @param request Non-NULL request payload.
- * @param callback Completion callback invoked for response, timeout, send
- * failure, or disconnect.
- * @param user_data Opaque pointer returned to ::callback.
- * @return ::TIRTC_ERROR_OK on success.
- */
-TirtcError tirtc_conn_request_command(TirtcConn* connection, const TirtcConnCommandRequest* request,
-                                      TirtcConnCommandResponseFn callback, void* user_data);
+/** Copies a command payload into a releasable owned buffer. */
+TirtcOwnedBytes* tirtc_conn_command_copy_payload(const TirtcConnCommand* command);
 
-/**
- * @brief Reply to an inbound remote command request.
- *
- * In the common request-response pattern, ::TirtcConnCommandResponse.command_id
- * matches the inbound request's ::command_id. Use the ::remote_request_id delivered by
- * ::TirtcConnObserver.on_remote_command_request on the same connection. If the
- * request is no longer pending, this function returns a not-ready error.
- * In the normal case, reply at most once for each delivered request id.
- *
- * @param connection Target connection.
- * @param remote_request_id Request id supplied by the observer callback.
- * @param response Non-NULL response payload.
- * @return ::TIRTC_ERROR_OK on success.
- */
-TirtcError tirtc_conn_reply_remote_command(TirtcConn* connection, uint64_t remote_request_id,
-                                           const TirtcConnCommandResponse* response);
+/** 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