Group PJSIP_AUTH_ASYNC

group PJSIP_AUTH_ASYNC

Non-blocking SIP authentication challenge handling.

This API allows applications to handle 401/407 authentication challenges asynchronously rather than providing credentials synchronously.

Typical workflow:

  1. Call pjsip_auth_clt_async_configure() to enable async mode.

  2. When a 401/407 response arrives, the application callback is invoked.

  3. Return PJ_TRUE from the callback to take ownership of the challenge.

  4. Later (or immediately), call pjsip_auth_clt_async_send_req() to resend with credentials, or pjsip_auth_clt_async_abandon() to give up.

  5. Returning PJ_FALSE from the callback falls back to the synchronous pjsip_auth_clt_reinit_req() path.

Thread safety: the token may be consumed (send/abandon) from any thread, provided the authentication session and its owner remain valid. When a parent session is configured, the parent’s lock serializes access.

Typedefs

typedef pj_bool_t pjsip_auth_clt_async_on_challenge(pjsip_auth_clt_sess *sess, void *token, const pjsip_auth_clt_async_on_chal_param *param)

Callback to notify application when a challenge is received.

Param sess:

The client authentication session.

Param token:

The token associated with the asynchronous request to be passed to pjsip_auth_clt_async_send_req().

Param param:

The callback parameter containing the original request and the response with the challenge.

Return:

PJ_TRUE if the application handles the challenge. The application MUST then eventually call pjsip_auth_clt_async_send_req() or pjsip_auth_clt_async_abandon(); failure to do so will leak the token’s group lock reference. It is safe to call either function synchronously from within the callback itself. PJ_FALSE to let the library handle authentication via the synchronous path.

Functions

pj_status_t pjsip_auth_clt_async_configure(pjsip_auth_clt_sess *sess, const pjsip_auth_clt_async_setting *opt)

Configure the authentication client to handle the authentication manually.

When the client receives a challenge, the library normally will automatically calculate the authentication response using the specified credential info and resend the request.

However, application can choose to handle the authentication manually using this function. When a challenge is received, the application will be notified. Then when the new request with the authentication response is ready, the application can send it using pjsip_auth_clt_async_send_req().

Parameters:

  • sess – The client authentication session.

  • opt – The asynchronous client authentication settings.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_auth_clt_async_send_req(pjsip_auth_clt_sess *sess, void *token, pjsip_tx_data *new_request)

Send the new request with the authentication response. This function is only used when the application has configured the authentication client to handle authentication manually.

The token is single-use: after this call (regardless of success or failure), the token is invalidated and any subsequent call with the same token will return PJ_EINVAL.

If application sends the new request with authentication response from outside the callback, application must maintain the validity of the owner of the authentication session. For example, if the authentication session is owned by a SIP registration client, the application must ensure that the registration client instance is still valid when calling this function.

Parameters:

  • sess – The client authentication session.

  • token – The token associated with the asynchronous request.

  • new_request – The new request to be sent.

Returns:

PJ_SUCCESS on success, or PJ_EINVAL if the token has already been consumed or is invalid.

pj_status_t pjsip_auth_clt_async_abandon(pjsip_auth_clt_sess *sess, void *token)

Inform the authentication session that the application has chosen to abandon the pending authentication challenge. The token is invalidated before abandon_impl is called, so any subsequent call to pjsip_auth_clt_async_send_req() with the same token will return PJ_EINVAL.

If the token’s abandon_impl field is non-NULL it will be invoked so that the SIP module can perform cleanup (e.g. terminate the SIP session or invoke its own completion callback with an error code).

Parameters:

  • sess – The client authentication session.

  • token – The token that was passed to the application’s challenge callback.

Returns:

PJ_SUCCESS, or PJ_EINVAL if the token is no longer valid (already used or already abandoned).

struct pjsip_auth_clt_async_on_chal_param
#include <sip_auth.h>

This structure describes the parameter passed to the callback when a challenge is received.

Public Members

pjsip_tx_data *tdata

The original request message which is challenged by the server.

If the application needs to use the request beyond the callback, it must maintain the request’s lifetime, e.g: using pjsip_tx_data_add_ref() and pjsip_tx_data_dec_ref().

const pjsip_rx_data *rdata

The 401/407 response containing the challenge from the server.

Note that the response is only valid during the callback. The application can make a copy of the response if it needs to use the response beyond the callback, e.g: using pjsip_rx_data_clone().

void *user_data

Application-specific data set via the pjsip_auth_clt_async_setting user_data field.

struct pjsip_auth_clt_async_setting
#include <sip_auth.h>

Asynchronous client authentication settings.

Forward declaration of asynchronous client authentication settings.

Public Members

pjsip_auth_clt_async_on_challenge *cb

Callback to notify the application when a challenge is received.

void *user_data

Optional application-specific data passed to the callback via pjsip_auth_clt_async_on_chal_param::user_data.