Group PJSUA_REGC

group PJSUA_REGC

High Layer API for performing client registration.

This provides API for performing client registration. Application must link with pjsip-ua static library to use this API.

Defines

PJSIP_REGC_MAX_CONTACT: Maximum contacts in registration.

PJSIP_REGC_EXPIRATION_NOT_SPECIFIED: Expiration not specified.

PJSIP_REGC_CONTACT_BUF_SIZE: Buffer to hold all contacts.

Typedefs

typedef struct pjsip_regc pjsip_regc: Typedef for client registration data.

typedef void pjsip_regc_cb(struct pjsip_regc_cbparam *param): Type declaration for callback to receive registration result.

typedef void pjsip_regc_tsx_cb(struct pjsip_regc_tsx_cb_param *param): Type declaration for callback set in pjsip_regc_set_reg_tsx_cb().

Functions

pjsip_module *pjsip_regc_get_module(void)

Get the module instance for client registration module.

Returns:: client registration module.

pj_status_t pjsip_regc_create(pjsip_endpoint *endpt, void *token, pjsip_regc_cb *cb, pjsip_regc **p_regc)

Create client registration structure.

Parameters:

endpt – Endpoint, used to allocate pool from.
token – A data to be associated with the client registration struct.
cb – Pointer to callback function to receive registration status.
p_regc – Pointer to receive client registration structure.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_destroy(pjsip_regc *regc)

Destroy client registration structure. If a registration transaction is in progress, then the structure will be deleted only after a final response has been received, and in this case, the callback won’t be called.

Parameters:: regc – The client registration structure.
Returns:: PJ_SUCCESS on success.

pj_status_t pjsip_regc_destroy2(pjsip_regc *regc, pj_bool_t force)

Destroy client registration structure. If a registration transaction is in progress:

if force is PJ_TRUE, then the structure will be deleted only after a final response has been received, and in this case, the callback won’t be called (this behavior is the same as calling pjsip_regc_destroye()).
if force is PJ_FALSE, the function will return PJ_EBUSY

Parameters:

regc – The client registration structure.
force – Specify if the function must destroy the structure.

Returns:

PJ_SUCCESS on success, or PJ_EBUSY.

pj_status_t pjsip_regc_get_info(pjsip_regc *regc, pjsip_regc_info *info)

Get registration info.

Parameters:

regc – The client registration structure.
info – Client registration info.

Returns:

PJ_SUCCESS on success.

pj_pool_t *pjsip_regc_get_pool(pjsip_regc *regc)

Get the memory pool associated with a registration client handle.

Parameters:: regc – The client registration structure.
Returns:: pool handle.

pj_status_t pjsip_regc_init(pjsip_regc *regc, const pj_str_t *srv_url, const pj_str_t *from_url, const pj_str_t *to_url, int ccnt, const pj_str_t contact[], pj_uint32_t expires)

Initialize client registration structure with various information needed to perform the registration.

Parameters:

regc – The client registration structure.
srv_url – Server URL.
from_url – The person performing the registration, must be a SIP URL type.
to_url – The address of record for which the registration is targetd, must be a SIP/SIPS URL.
ccnt – Number of contacts in the array.
contact – Array of contacts, each contact item must be formatted as described in RFC 3261 Section 20.10: When the header field value contains a display name, the URI including all URI parameters is enclosed in “<” and “>”. If no “<” and “>” are present, all parameters after the URI are header parameters, not URI parameters. The display name can be tokens, or a quoted string, if a larger character set is desired.
expires – Default expiration interval (in seconds) to be applied for contact URL that doesn’t have expiration settings. If the value PJSIP_REGC_EXPIRATION_NOT_SPECIFIED is given, then no default expiration will be applied.

Returns:

zero on success.

void pjsip_regc_add_ref(pjsip_regc *regc)

Increment busy counter temporarily, to prevent client registration structure from being destroyed.

Parameters:: regc – The client registration structure.

pj_status_t pjsip_regc_dec_ref(pjsip_regc *regc)

Decrement temporary busy counter. After this function is called, client registration structure may have been destroyed if there’s a pending destroy.

Parameters:: regc – The client registration structure.
Returns:: PJ_SUCCESS on success. PJ_EGONE if the registration structure has been destroyed inside the function.

pj_status_t pjsip_regc_set_reg_tsx_cb(pjsip_regc *regc, pjsip_regc_tsx_cb *tsx_cb)

Set callback to be called when the registration received a final response. This callback is different with the one specified during creation via pjsip_regc_create(). This callback will be called for any final response (including 401/407/423) and before any subsequent requests are sent. In case of unregistration, this callback will not be called.

Parameters:

regc – The client registration structure.
tsx_cb – Pointer to callback function to receive registration status.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_set_via_sent_by(pjsip_regc *regc, pjsip_host_port *via_addr, pjsip_transport *via_tp)

Set the “sent-by” field of the Via header for outgoing requests.

Parameters:

regc – The client registration structure.
via_addr – Set via_addr to use for the Via header or NULL to use the transport’s published name.
via_tp – via_addr will only be used if we are using via_tp transport.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_set_delay_before_refresh(pjsip_regc *regc, pj_uint32_t delay)

Set the number of seconds to refresh the client registration before the registration expires.

Parameters:

regc – The registration structure.
delay – The number of seconds to refresh the client registration before the registration expires.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_set_credentials(pjsip_regc *regc, int count, const pjsip_cred_info cred[])

Set authentication credentials to use by this registration.

Parameters:

regc – The registration structure.
count – Number of credentials in the array.
cred – Array of credentials.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_set_prefs(pjsip_regc *regc, const pjsip_auth_clt_pref *pref)

Set authentication preference.

Parameters:

regc – The registration structure.
pref – Authentication preference.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_set_route_set(pjsip_regc *regc, const pjsip_route_hdr *route_set)

Set route set to be used for outgoing requests.

Parameters:

regc – The client registration structure.
route_set – List containing Route headers.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_set_transport(pjsip_regc *regc, const pjsip_tpselector *sel)

Lock/bind client registration to a specific transport/listener. This is optional, as normally transport will be selected automatically based on the destination of requests upon resolver completion. When the client registration is explicitly bound to the specific transport/listener, all UAC transactions originated by the client registration will use the specified transport/listener when sending outgoing requests.

Note that this doesn’t affect the Contact header set for this client registration. Application must manually update the Contact header if necessary, to adjust the address according to the transport being selected.

Parameters:

regc – The client registration instance.
sel – Transport selector containing the specification of transport or listener to be used by this session to send requests.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_regc_release_transport(pjsip_regc *regc)

Release the reference to current transport being used by the regc, if any. The regc keeps the reference to the last transport being used in order to prevent it from being destroyed. In some situation however, such as when the transport is disconnected, it is necessary to instruct the regc to release this reference so that the transport can be destroyed. See https://github.com/pjsip/pjproject/issues/1481 for background info.

Parameters:: regc – The client registration instance.
Returns:: PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjsip_regc_add_headers(pjsip_regc *regc, const pjsip_hdr *hdr_list)

Add headers to be added to outgoing REGISTER requests.

Parameters:

regc – The client registration structure.
hdr_list – List containing SIP headers to be added for all outgoing REGISTER requests.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_register(pjsip_regc *regc, pj_bool_t autoreg, pjsip_tx_data **p_tdata)

Create REGISTER request for the specified client registration structure.

After successfull registration, application can inspect the contacts in the client registration structure to list what contacts are associaciated with the address of record being targeted in the registration.

Parameters:

regc – The client registration structure.
autoreg – If non zero, the library will automatically refresh the next registration until application unregister.
p_tdata – Pointer to receive the REGISTER request.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_unregister(pjsip_regc *regc, pjsip_tx_data **p_tdata)

Create REGISTER request to unregister the contacts that were previously registered by this client registration.

Parameters:

regc – The client registration structure.
p_tdata – Pointer to receive the REGISTER request.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_unregister_all(pjsip_regc *regc, pjsip_tx_data **p_tdata)

Create REGISTER request to unregister all contacts from server records. Note that this will unregister all registered contact for the AOR including contacts registered by other user agents. To only unregister contact registered by this client registration instance, use pjsip_regc_unregister() instead.

Parameters:

regc – The client registration structure.
p_tdata – Pointer to receive the REGISTER request.

Returns:

PJ_SUCCESS on success.

pj_status_t pjsip_regc_update_contact(pjsip_regc *regc, int ccnt, const pj_str_t contact[])

Update Contact details in the client registration structure. For each contact, if the contact is not found in existing contact, it will be added to the Contact list. If it matches existing contact, nothing will be added. This function will also mark existing contacts which are not specified in the new contact list as to be removed, by adding “expires=0” parameter to these contacts.

Once the contact list has been updated, application must update the registration by creating a new REGISTER request and send it to the registrar. This request will contain both old and new contacts; the old contacts will have it’s expires parameter set to zero to instruct the registrar to remove the bindings.

Parameters:

regc – The client registration structure.
ccnt – Number of contacts.
contact – Array of contacts, each contact item must be formatted as described in RFC 3261 Section 20.10: When the header field value contains a display name, the URI including all URI parameters is enclosed in “<” and “>”. If no “<” and “>” are present, all parameters after the URI are header parameters, not URI parameters. The display name can be tokens, or a quoted string, if a larger character set is desired.

Returns:

PJ_SUCCESS if sucessfull.

pj_status_t pjsip_regc_update_expires(pjsip_regc *regc, pj_uint32_t expires)

Update the expires value. The next REGISTER request will contain new expires value for the registration.

Parameters:

regc – The client registration structure.
expires – The new expires value.

Returns:

zero on successfull.

pj_status_t pjsip_regc_send(pjsip_regc *regc, pjsip_tx_data *tdata)

Sends outgoing REGISTER request. The process will complete asynchronously, and application will be notified via the callback when the process completes.

Parameters:

regc – The client registration structure.
tdata – Transmit data.

Returns:

PJ_SUCCESS on success.

struct pjsip_regc_cbparam

#include <sip_regc.h>

Structure to hold parameters when calling application’s callback. The application’s callback is called when the client registration process has finished.

Public Members

pjsip_regc *regc: Client registration structure.

void *token: Arbitrary token set by application

pj_status_t status: Error status. If this value is non-PJ_SUCCESS, some error has occured. Note that even when this contains PJ_SUCCESS the registration might have failed; in this case the code field will contain non successful (non-2xx status class) code

int code: SIP status code received.

pj_str_t reason: SIP reason phrase received.

pjsip_rx_data *rdata: The complete received response.

unsigned expiration: Next expiration interval, PJSIP_REGC_EXPIRATION_NOT_SPECIFIED if not specified.

int contact_cnt: Number of contacts in response.

pjsip_contact_hdr *contact[10]: Contacts.

pj_bool_t is_unreg: Expire header, if any, set to zero?

struct pjsip_regc_tsx_cb_param

#include <sip_regc.h>

Structure to hold parameters when calling application’s callback specified in pjsip_regc_set_reg_tsx_cb(). To update contact address, application can set the field contact_cnt and contact inside the callback.

Public Members

struct pjsip_regc_cbparam cbparam: cbparam

int contact_cnt: Number of Contacts

pj_str_t contact[10]: Array of Contacts

struct pjsip_regc_info

#include <sip_regc.h>

Client registration information.