Skip to main content

moq_session_connect

Function moq_session_connect 

Source
#[unsafe(no_mangle)]
pub unsafe extern "C" fn moq_session_connect( url: *const c_char, url_len: usize, origin_publish: u32, origin_consume: u32, on_status: Option<extern "C" fn(user_data: *mut c_void, code: i32)>, user_data: *mut c_void, ) -> i32
Expand description

Start establishing a connection to a MoQ server.

Takes origin handles, which are used for publishing and consuming broadcasts respectively.

  • Any broadcasts in origin_publish will be announced to the server.
  • Any broadcasts announced by the server will be available in origin_consume.
  • If an origin handle is 0, that functionality is completely disabled.

This may be called multiple times to connect to different servers. Origins can be shared across sessions, useful for fanout or relaying.

Returns a non-zero handle to the session on success, or a negative code on (immediate) failure. You should call moq_session_close, even on error, to free up resources.

The session reconnects automatically with exponential backoff if the connection drops. Published broadcasts are re-announced and consumers re-subscribed on each reconnect, since the origins outlive the underlying connection.

on_status reports the session lifecycle through its status code:

  • > 0 on every (re)connect, carrying the connection epoch (1 = first connect, 2 = first reconnect, and so on), so a reconnect is distinguishable from the initial connect. May fire repeatedly. Transient disconnects are not reported.
  • 0 when the session is closed cleanly via moq_session_close (terminal).
  • a negative error code if reconnection permanently gives up, e.g. the backoff timeout is exceeded (terminal).

After a terminal (<= 0) status, on_status is never called again and user_data is never touched again, so that final callback is the point to release user_data. The terminal 0 fires even after moq_session_close, so do not free user_data on the close call itself.

ยงSafety

  • The caller must ensure that url is a valid pointer to url_len bytes of data.
  • The caller must keep user_data valid until the terminal (<= 0) on_status callback.