High Layer API for performing client registration. More...

Data Structures
struct	pjsip_regc_cbparam

struct	pjsip_regc_tsx_cb_param

struct	pjsip_regc_info

Macros
#define	PJSIP_REGC_MAX_CONTACT 10

#define	PJSIP_REGC_EXPIRATION_NOT_SPECIFIED PJSIP_EXPIRES_NOT_SPECIFIED

#define	PJSIP_REGC_CONTACT_BUF_SIZE 512

Typedefs
typedef struct pjsip_regc	pjsip_regc

typedef void	pjsip_regc_cb(struct pjsip_regc_cbparam *param)

typedef void	pjsip_regc_tsx_cb(struct pjsip_regc_tsx_cb_param *param)

Functions
pjsip_module *	pjsip_regc_get_module (void)

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

pj_status_t	pjsip_regc_destroy (pjsip_regc *regc)

pj_status_t	pjsip_regc_destroy2 (pjsip_regc *regc, pj_bool_t force)

pj_status_t	pjsip_regc_get_info (pjsip_regc regc, pjsip_regc_info info)

pj_pool_t *	pjsip_regc_get_pool (pjsip_regc *regc)

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)

void	pjsip_regc_add_ref (pjsip_regc *regc)

pj_status_t	pjsip_regc_dec_ref (pjsip_regc *regc)

pj_status_t	pjsip_regc_set_reg_tsx_cb (pjsip_regc regc, pjsip_regc_tsx_cb tsx_cb)

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

pj_status_t	pjsip_regc_set_delay_before_refresh (pjsip_regc *regc, pj_uint32_t delay)

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

pj_status_t	pjsip_regc_set_prefs (pjsip_regc regc, const pjsip_auth_clt_pref pref)

pj_status_t	pjsip_regc_set_route_set (pjsip_regc regc, const pjsip_route_hdr route_set)

pj_status_t	pjsip_regc_set_transport (pjsip_regc regc, const pjsip_tpselector sel)

pj_status_t	pjsip_regc_release_transport (pjsip_regc *regc)

pj_status_t	pjsip_regc_add_headers (pjsip_regc regc, const pjsip_hdr hdr_list)

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

pj_status_t	pjsip_regc_unregister (pjsip_regc regc, pjsip_tx_data *p_tdata)

pj_status_t	pjsip_regc_unregister_all (pjsip_regc regc, pjsip_tx_data *p_tdata)

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

pj_status_t	pjsip_regc_update_expires (pjsip_regc *regc, pj_uint32_t expires)

pj_status_t	pjsip_regc_send (pjsip_regc regc, pjsip_tx_data tdata)

Detailed Description

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

Macro Definition Documentation

◆ PJSIP_REGC_MAX_CONTACT

#define PJSIP_REGC_MAX_CONTACT 10

Maximum contacts in registration.

◆ PJSIP_REGC_EXPIRATION_NOT_SPECIFIED

#define PJSIP_REGC_EXPIRATION_NOT_SPECIFIED PJSIP_EXPIRES_NOT_SPECIFIED

Expiration not specified.

◆ PJSIP_REGC_CONTACT_BUF_SIZE

#define PJSIP_REGC_CONTACT_BUF_SIZE 512

Buffer to hold all contacts.

Typedef Documentation

◆ pjsip_regc

typedef struct pjsip_regc pjsip_regc

Typedef for client registration data.

◆ pjsip_regc_cb

typedef void pjsip_regc_cb(struct pjsip_regc_cbparam *param)

Type declaration for callback to receive registration result.

◆ pjsip_regc_tsx_cb

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().

Function Documentation

◆ pjsip_regc_get_module()

pjsip_module * pjsip_regc_get_module ( void )

Get the module instance for client registration module.

Returns: client registration module.

◆ pjsip_regc_create()

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.

◆ pjsip_regc_destroy()

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.

◆ pjsip_regc_destroy2()

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.

◆ pjsip_regc_get_info()

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.

◆ pjsip_regc_get_pool()

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.

◆ pjsip_regc_init()

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.

◆ pjsip_regc_add_ref()

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.

◆ pjsip_regc_dec_ref()

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.

◆ pjsip_regc_set_reg_tsx_cb()

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.

◆ pjsip_regc_set_via_sent_by()

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.

◆ pjsip_regc_set_delay_before_refresh()

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.

◆ pjsip_regc_set_credentials()

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.

◆ pjsip_regc_set_prefs()

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.

◆ pjsip_regc_set_route_set()

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.

◆ pjsip_regc_set_transport()

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.

◆ pjsip_regc_release_transport()

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.

◆ pjsip_regc_add_headers()

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.

◆ pjsip_regc_register()

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.

◆ pjsip_regc_unregister()

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.

◆ pjsip_regc_unregister_all()

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.

◆ pjsip_regc_update_contact()

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.

◆ pjsip_regc_update_expires()

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.

◆ pjsip_regc_send()

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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ PJSIP_REGC_MAX_CONTACT

◆ PJSIP_REGC_EXPIRATION_NOT_SPECIFIED

◆ PJSIP_REGC_CONTACT_BUF_SIZE

Typedef Documentation

◆ pjsip_regc

◆ pjsip_regc_cb

◆ pjsip_regc_tsx_cb

Function Documentation

◆ pjsip_regc_get_module()

◆ pjsip_regc_create()

◆ pjsip_regc_destroy()

◆ pjsip_regc_destroy2()

◆ pjsip_regc_get_info()

◆ pjsip_regc_get_pool()

◆ pjsip_regc_init()

◆ pjsip_regc_add_ref()

◆ pjsip_regc_dec_ref()

◆ pjsip_regc_set_reg_tsx_cb()

◆ pjsip_regc_set_via_sent_by()

◆ pjsip_regc_set_delay_before_refresh()

◆ pjsip_regc_set_credentials()

◆ pjsip_regc_set_prefs()

◆ pjsip_regc_set_route_set()

◆ pjsip_regc_set_transport()

◆ pjsip_regc_release_transport()

◆ pjsip_regc_add_headers()

◆ pjsip_regc_register()

◆ pjsip_regc_unregister()

◆ pjsip_regc_unregister_all()

◆ pjsip_regc_update_contact()

◆ pjsip_regc_update_expires()

◆ pjsip_regc_send()