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

typedefPJ_BEGIN_DECL 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.

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_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.

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://trac.pjsip.org/repos/ticket/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.

struct pjsip_regc_info¶

#include <sip_regc.h>

Client registration information.

See: pjsip_regc_info