Onboarding

Functions Index

static QarForgetInit	qar_forget_init_default (void)
static QarOnboardCodeExt	qar_onboard_code_ext_default (void)
	Default init for QarOnboardCodeExt. More...
static QarOnboardHostExt	qar_onboard_host_ext_default (void)
	Default init for QarOnboardHostExt. More...
static QarOnboardInit	qar_onboard_init_default (void)
	Default init for QarOnboardInit. More...
static QarOnboardInviteExt	qar_onboard_invite_ext_default (void)
	Default init for QarOnboardInviteExt. More...
static QarOnboardPeerIdExt	qar_onboard_peer_id_ext_default (void)
	Default init for QarOnboardPeerIdExt (zero peer id; set it). More...
static QarOnboardingId	qar_onboarding_id_default (void)
	Zero/invalid onboarding id ("no id"). More...
static bool	qar_onboarding_id_equals (const QarOnboardingId *id1, const QarOnboardingId *id2)
	Compare two onboarding ids for equality. More...
static bool	qar_onboarding_id_is_zero (const QarOnboardingId *id)
	True if the id is the zero/default id. More...
static QarResult	qar_onboarding_invite_deserialize (const uint8_t *wire_data, size_t wire_data_size, QarOnboardingInvite **out_invite)
	Parse an invite from wire bytes (IPC message, QR payload, config field). More...
static QarResult	qar_onboarding_invite_get_code (const QarOnboardingInvite *invite, char *out_buffer, size_t buffer_size, size_t *out_length)
	The code text of a pairing-code invite, to pass as QarOnboardCodeExt.code. More...
static QarResult	qar_onboarding_invite_get_expires_unix (const QarOnboardingInvite *invite, int64_t *out_expires_unix)
	Expiry (unix seconds) so GUIs can warn before handing out a stale blob. More...
static QarResult	qar_onboarding_invite_get_method (const QarOnboardingInvite *invite, QarOnboardingMethod *out_method)
	Which onboarding path the invite carries. More...
static void	qar_onboarding_invite_handle_destroy (QarOnboardingInvite *invite)
	Destroy an onboarding invite handle. More...
static bool	qar_onboarding_invite_handle_is_valid (const QarOnboardingInvite *invite)
	Check if an onboarding invite handle is valid. More...
static QarResult	qar_onboarding_invite_serialize (const QarOnboardingInvite *invite, uint8_t *out_buffer, size_t buffer_size, size_t *out_bytes_written)
	Serialize the invite to wire bytes so the blob can be handed to a sibling instance. More...
static QarResult	qar_onboarding_invite_serialized_size (const QarOnboardingInvite *invite, size_t *out_size)
	Sizing getter — the API's count-then-fetch convention. More...
static QarPeerPresentation	qar_peer_presentation_default (void)
	Default init for QarPeerPresentation (stamps type; NULL fields). More...
static QarRejoinInit	qar_rejoin_init_default (void)
	Default init for QarRejoinInit. More...
static QarRequestInviteInit	qar_request_invite_init_default (void)
	Default init for QarRequestInviteInit. More...
static QarRequestOnboardingCodesInit	qar_request_onboarding_codes_init_default (void)
	Default init for QarRequestOnboardingCodesInit (one code, hub default lifetime, any device). More...
static QarResult	qar_runtime_forget (QarRuntime *runtime, const QarForgetInit *init)
	Erase everything stored for this identity slot (certificate, persisted instance id, session state). More...
static QarResult	qar_runtime_onboard (QarRuntime *runtime, const QarOnboardInit *init, qar_progress_callback_t on_progress, void *progress_state, QarCancelToken *cancel, QarOnboardingId *out_onboarding_id, QarSession **out_session)
	Run full onboarding using exactly one chained mode extension. More...
static QarResult	qar_runtime_onboard_async (QarRuntime *runtime, const QarOnboardInit *init, qar_runtime_onboard_result_callback_t result_callback, qar_progress_callback_t update_callback, void *user_state, QarCancelToken *cancel)
	Async variant of qar_runtime_onboard. The result callback delivers the generated onboarding id — persist it. More...
static QarResult	qar_runtime_rejoin (QarRuntime *runtime, const QarRejoinInit *init, qar_progress_callback_t on_progress, void *progress_state, QarCancelToken *cancel, QarSession **out_session)
	Restore and validate the last persisted session for init->onboarding_id. Pops no UI. More...
static QarResult	qar_runtime_rejoin_async (QarRuntime *runtime, const QarRejoinInit *init, qar_runtime_onboard_result_callback_t result_callback, qar_progress_callback_t update_callback, void *user_state, QarCancelToken *cancel)
	Async variant of qar_runtime_rejoin. More...
static QarSessionInviteTargetAppInit	qar_session_invite_target_app_init_default (void)
	Default init for QarForgetInit. More...
static QarResult	qar_session_request_onboarding_codes (QarSession *session, const QarRequestOnboardingCodesInit *init, qar_progress_callback_t on_progress, void *progress_state, QarCancelToken *cancel, QarOnboardingInvite **out_invites)
	Ask the hub this session onboarded through for a new set of one-time onboarding codes, for several devices to onboard at once. More...
static QarResult	qar_session_request_onboarding_invite (QarSession *session, const QarRequestInviteInit *init, qar_progress_callback_t on_progress, void *progress_state, QarCancelToken *cancel, QarOnboardingInvite **out_invite)
	Onboard from a complete invite (init->invite) received from a sibling instance. More...
static QarResult	qar_session_request_onboarding_invite_async (QarSession *session, const QarRequestInviteInit *init, qar_session_request_invite_result_callback_t result_callback, qar_progress_callback_t update_callback, void *user_state, QarCancelToken *cancel)
	Async variant of qar_session_request_onboarding_invite. More...

Description

Every session is obtained through onboarding. The canonical app startup is: try qar_runtime_rejoin with the persisted QarOnboardingId; when that fails, show the onboarding GUI and run qar_runtime_onboard. Persist the id the onboard call returns — it is the ticket for every later rejoin / forget. Destroy the session handle to tear the session down while keeping persisted state; use qar_runtime_forget for a full reset.

Functions

qar_forget_init_default()

QarForgetInit qar_forget_init_default (void)

inline static

Definition at line 5774 of file qar_streaming.h.

qar_onboard_code_ext_default()

QarOnboardCodeExt qar_onboard_code_ext_default (void)

inline static

Default init for QarOnboardCodeExt.

Definition at line 5702 of file qar_streaming.h.

qar_onboard_host_ext_default()

QarOnboardHostExt qar_onboard_host_ext_default (void)

inline static

Default init for QarOnboardHostExt.

Definition at line 5712 of file qar_streaming.h.

qar_onboard_init_default()

QarOnboardInit qar_onboard_init_default (void)

inline static

Default init for QarOnboardInit.

Definition at line 5691 of file qar_streaming.h.

qar_onboard_invite_ext_default()

QarOnboardInviteExt qar_onboard_invite_ext_default (void)

inline static

Default init for QarOnboardInviteExt.

Definition at line 5723 of file qar_streaming.h.

qar_onboard_peer_id_ext_default()

QarOnboardPeerIdExt qar_onboard_peer_id_ext_default (void)

inline static

Default init for QarOnboardPeerIdExt (zero peer id; set it).

Definition at line 5733 of file qar_streaming.h.

qar_onboarding_id_default()

QarOnboardingId qar_onboarding_id_default (void)

inline static

Zero/invalid onboarding id ("no id").

Definition at line 5661 of file qar_streaming.h.

qar_onboarding_id_equals()

bool qar_onboarding_id_equals (const QarOnboardingId * id1, const QarOnboardingId * id2)

inline static

Compare two onboarding ids for equality.

Definition at line 6395 of file qar_streaming.h.

qar_onboarding_id_is_zero()

bool qar_onboarding_id_is_zero (const QarOnboardingId * id)

inline static

True if the id is the zero/default id.

Definition at line 6414 of file qar_streaming.h.

qar_onboarding_invite_deserialize()

QarResult qar_onboarding_invite_deserialize (const uint8_t * wire_data, size_t wire_data_size, QarOnboardingInvite ** out_invite)

inline static

Parse an invite from wire bytes (IPC message, QR payload, config field).

Return Values

QAR_STATUS_PAKE_ERROR

the wire bytes are not a valid invite.

Definition at line 2518 of file qar_streaming.h.

qar_onboarding_invite_get_code()

QarResult qar_onboarding_invite_get_code (const QarOnboardingInvite * invite, char * out_buffer, size_t buffer_size, size_t * out_length)

inline static

The code text of a pairing-code invite, to pass as QarOnboardCodeExt.code.

The text names its own invitation, so it works for any invite the hub minted, not only the one its onboarding screen shows. It is a secret: never log it.

Parameters

invite	Required; a PAKE invite (qar_onboarding_invite_get_method).
out_buffer	Receives the NUL-terminated text. May be NULL to query the length only.
buffer_size	Size of out_buffer in bytes.
out_length	Optional; receives the text length without the NUL.

Returns

Success, or the failure.

Return Values

QAR_STATUS_ARGUMENT_NOT_SUPPORTED

the invite is not a pairing-code invite, or out_buffer is too small (out_length still tells the length).

Definition at line 2575 of file qar_streaming.h.

qar_onboarding_invite_get_expires_unix()

QarResult qar_onboarding_invite_get_expires_unix (const QarOnboardingInvite * invite, int64_t * out_expires_unix)

inline static

Expiry (unix seconds) so GUIs can warn before handing out a stale blob.

Definition at line 2550 of file qar_streaming.h.

qar_onboarding_invite_get_method()

QarResult qar_onboarding_invite_get_method (const QarOnboardingInvite * invite, QarOnboardingMethod * out_method)

inline static

Which onboarding path the invite carries.

Definition at line 2544 of file qar_streaming.h.

qar_onboarding_invite_handle_destroy()

void qar_onboarding_invite_handle_destroy (QarOnboardingInvite * invite)

inline static

Destroy an onboarding invite handle.

Definition at line 2583 of file qar_streaming.h.

qar_onboarding_invite_handle_is_valid()

bool qar_onboarding_invite_handle_is_valid (const QarOnboardingInvite * invite)

inline static

Check if an onboarding invite handle is valid.

Definition at line 2556 of file qar_streaming.h.

qar_onboarding_invite_serialize()

QarResult qar_onboarding_invite_serialize (const QarOnboardingInvite * invite, uint8_t * out_buffer, size_t buffer_size, size_t * out_bytes_written)

inline static

Serialize the invite to wire bytes so the blob can be handed to a sibling instance.

Return Values

QAR_STATUS_ARGUMENT_NOT_SUPPORTED

out_buffer is too small — *out_bytes_written is still set to the required size; resize and retry.

Definition at line 2536 of file qar_streaming.h.

qar_onboarding_invite_serialized_size()

QarResult qar_onboarding_invite_serialized_size (const QarOnboardingInvite * invite, size_t * out_size)

inline static

Sizing getter — the API's count-then-fetch convention.

Definition at line 2525 of file qar_streaming.h.

qar_peer_presentation_default()

QarPeerPresentation qar_peer_presentation_default (void)

inline static

Default init for QarPeerPresentation (stamps type; NULL fields).

Definition at line 5668 of file qar_streaming.h.

qar_rejoin_init_default()

QarRejoinInit qar_rejoin_init_default (void)

inline static

Default init for QarRejoinInit.

Definition at line 5680 of file qar_streaming.h.

qar_request_invite_init_default()

QarRequestInviteInit qar_request_invite_init_default (void)

inline static

Default init for QarRequestInviteInit.

Definition at line 5743 of file qar_streaming.h.

qar_request_onboarding_codes_init_default()

QarRequestOnboardingCodesInit qar_request_onboarding_codes_init_default (void)

inline static

Default init for QarRequestOnboardingCodesInit (one code, hub default lifetime, any device).

Definition at line 5752 of file qar_streaming.h.

qar_runtime_forget()

QarResult qar_runtime_forget (QarRuntime * runtime, const QarForgetInit * init)

inline static

Erase everything stored for this identity slot (certificate, persisted instance id, session state).

Works with no active session — e.g. a settings screen "forget this hub" while disconnected. After forget the only way back in is a full onboard.

Return Values

QAR_STATUS_ONBOARDING_SESSION_STILL_ACTIVE	the slot still has an active session — destroy the active session handle first.
QAR_STATUS_ARGUMENT_NOT_SUPPORTED	init->onboarding_id is zero.
QAR_STATUS_ONBOARDING_SESSION_NOT_FOUND	no persisted slot for the id.

Definition at line 2507 of file qar_streaming.h.

qar_runtime_onboard()

QarResult qar_runtime_onboard (QarRuntime * runtime, const QarOnboardInit * init, qar_progress_callback_t on_progress, void * progress_state, QarCancelToken * cancel, QarOnboardingId * out_onboarding_id, QarSession ** out_session)

inline static

Run full onboarding using exactly one chained mode extension.

Chain one of:

• QarOnboardCodeExt: PAKE code shown on the hub onboarding screen
• QarOnboardInviteExt: full invite blob from a sibling instance

QarOnboardHostExt is optional and only applies when QarOnboardCodeExt is chained.

Optional, alongside the mode extension:

• QarOnboardPeerIdExt: join under a caller-chosen peer id instead of a fresh one; the id is persisted with the slot and kept by every later rejoin.
• QarGraphicsDeviceId: create the session's GPU devices on this adapter. Without it, the session uses the GPU QAROS selected for an application it launched (carried in the launch invite), else one the library picks. Read the adapter in use with qar_session_get_graphics_device_id().

Return Values

QAR_STATUS_ARGUMENT_NOT_SUPPORTED

QarOnboardPeerIdExt carries a zero peer id, or QarGraphicsDeviceId (or the launch invite's GPU) names an adapter the session cannot create its GPU devices on.

Parameters

out_onboarding_id	Required; receives the generated (or re-enrolled) id. Persist it — it is the ticket for every later rejoin / forget.
out_session	Receives the onboarded session handle on success.

Return Values

QAR_STATUS_ONBOARDING_HUB_UNREACHABLE	discovery could not reach a hub — verify host/port and retry.
QAR_STATUS_PAKE_ERROR	the handshake was rejected, the invite expired, out — re-prompt the user for the code.

Definition at line 2394 of file qar_streaming.h.

qar_runtime_onboard_async()

QarResult qar_runtime_onboard_async (QarRuntime * runtime, const QarOnboardInit * init, qar_runtime_onboard_result_callback_t result_callback, qar_progress_callback_t update_callback, void * user_state, QarCancelToken * cancel)

inline static

Async variant of qar_runtime_onboard. The result callback delivers the generated onboarding id — persist it.

Definition at line 2406 of file qar_streaming.h.

qar_runtime_rejoin()

QarResult qar_runtime_rejoin (QarRuntime * runtime, const QarRejoinInit * init, qar_progress_callback_t on_progress, void * progress_state, QarCancelToken * cancel, QarSession ** out_session)

inline static

Restore and validate the last persisted session for init->onboarding_id. Pops no UI.

Blocks until the restore validated or failed. Progress callbacks fire from an internal thread while the caller is blocked; the last progress callback returns before the call does.

Chain QarGraphicsDeviceId on init->header.next to create the session's GPU devices on that adapter. The peer id is the one persisted by the onboard.

Parameters

runtime	Runtime the identity slot belongs to.
init	Rejoin parameters (fully copied before the call returns).
on_progress	Optional progress callback (can be NULL).
progress_state	User pointer passed to on_progress unchanged.
cancel	Optional cancellation token (can be NULL). Must stay alive until the call returned.
out_session	Receives the restored session handle on success.

Return Values

QAR_STATUS_ARGUMENT_NOT_SUPPORTED	init->onboarding_id is zero.
QAR_STATUS_ONBOARDING_SESSION_NOT_FOUND	no persisted slot for the id — fall back to qar_runtime_onboard.

Definition at line 2339 of file qar_streaming.h.

qar_runtime_rejoin_async()

QarResult qar_runtime_rejoin_async (QarRuntime * runtime, const QarRejoinInit * init, qar_runtime_onboard_result_callback_t result_callback, qar_progress_callback_t update_callback, void * user_state, QarCancelToken * cancel)

inline static

Async variant of qar_runtime_rejoin.

Returns immediately after starting the restore; result_callback fires exactly once on a background thread (also on cancellation).

Return Values

QAR_STATUS_ARGUMENT_NOT_SUPPORTED

init->onboarding_id is zero (the callback does not fire in this case).

Definition at line 2356 of file qar_streaming.h.

qar_session_invite_target_app_init_default()

QarSessionInviteTargetAppInit qar_session_invite_target_app_init_default (void)

inline static

Default init for QarForgetInit.

Default init for QarSessionInviteTargetAppInit.

Definition at line 5764 of file qar_streaming.h.

qar_session_request_onboarding_codes()

QarResult qar_session_request_onboarding_codes (QarSession * session, const QarRequestOnboardingCodesInit * init, qar_progress_callback_t on_progress, void * progress_state, QarCancelToken * cancel, QarOnboardingInvite ** out_invites)

inline static

Ask the hub this session onboarded through for a new set of one-time onboarding codes, for several devices to onboard at once.

Every call mints codes of its own. Codes other callers hold and the code on the hub's onboarding screen stay valid, and none of the new codes is announced or displayed. Each works once, for init->lifetime_seconds. Hand a device either the invite itself (qar_onboarding_invite_serialize, then QarOnboardInviteExt) or its code text (qar_onboarding_invite_get_code, then QarOnboardCodeExt). Blocks until the hub answers.

Parameters

init	Required; count, lifetime and optional planned peer id.
on_progress	Optional progress callback.
progress_state	Passed to on_progress.
cancel	Optional cancel token.
out_invites	Required; an array of init->count handles, filled on success. Each is owned by the caller (release with qar_onboarding_invite_handle_destroy). Untouched entries are NULL on failure.

Returns

Success, or the failure.

Return Values

QAR_STATUS_ARGUMENT_NOT_SUPPORTED

count is 0 or above 64, the lifetime is above 600 s, or the hub peer could not be resolved.

Definition at line 2484 of file qar_streaming.h.

qar_session_request_onboarding_invite()

QarResult qar_session_request_onboarding_invite (QarSession * session, const QarRequestInviteInit * init, qar_progress_callback_t on_progress, void * progress_state, QarCancelToken * cancel, QarOnboardingInvite ** out_invite)

inline static

Onboard from a complete invite (init->invite) received from a sibling instance.

The method (PAKE or password) is auto-detected from the invite. No discovery, no GUI.

Parameters

out_onboarding_id

Required; receives the generated (or re-enrolled) id. Persist it.

Return Values

QAR_STATUS_PAKE_ERROR

the invite handshake was rejected or the invite expired — mint a fresh invite on the sibling and retry.

Ask the hub this session onboarded through for a fresh onboarding invite to hand to another instance.

The hub peer is resolved internally from the session — nothing to configure. Serialize the delivered invite with qar_onboarding_invite_serialize and send the bytes to the sibling over IPC / shared memory / a pipe.

Parameters

out_invite

Receives the minted invite handle; owned by the caller (release with qar_onboarding_invite_handle_destroy).

Return Values

QAR_STATUS_ARGUMENT_NOT_SUPPORTED

the hub peer could not be resolved from this session (e.g. the hub is not connected right now).

Definition at line 2442 of file qar_streaming.h.

qar_session_request_onboarding_invite_async()

QarResult qar_session_request_onboarding_invite_async (QarSession * session, const QarRequestInviteInit * init, qar_session_request_invite_result_callback_t result_callback, qar_progress_callback_t update_callback, void * user_state, QarCancelToken * cancel)

inline static

Async variant of qar_session_request_onboarding_invite.

Definition at line 2452 of file qar_streaming.h.

---

Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.9.8.