Onboarding

Functions Index

static QarForgetInit	qar_forget_init_default (void)
	Default init for QarForgetInit. More...
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 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_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 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 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

Default init for QarForgetInit.

Definition at line 3262 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 3222 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 3232 of file qar_streaming.h.

qar_onboard_init_default()

QarOnboardInit qar_onboard_init_default (void)

inline static

Default init for QarOnboardInit.

Definition at line 3211 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 3243 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 3181 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 3644 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 3663 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 1561 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 1593 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 1587 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 1602 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 1599 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 1579 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 1568 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 3188 of file qar_streaming.h.

qar_rejoin_init_default()

QarRejoinInit qar_rejoin_init_default (void)

inline static

Default init for QarRejoinInit.

Definition at line 3200 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 3253 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 1550 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.

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 1469 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 1481 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.

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 1425 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 1442 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 1517 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 1527 of file qar_streaming.h.

---

Generated via doxygen2docusaurus 2.2.1 by Doxygen 1.9.8.