BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

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   ((pj_uint32_t)0xFFFFFFFFUL)
 
#define PJSIP_REGC_CONTACT_BUF_SIZE   512
 

Typedefs

typedef typedefPJ_BEGIN_DECL
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_modulepjsip_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_get_info (pjsip_regc *regc, pjsip_regc_info *info)
 
pj_pool_tpjsip_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)
 
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

#define PJSIP_REGC_MAX_CONTACT   10

Maximum contacts in registration.

#define PJSIP_REGC_EXPIRATION_NOT_SPECIFIED   ((pj_uint32_t)0xFFFFFFFFUL)

Expiration not specified.

#define PJSIP_REGC_CONTACT_BUF_SIZE   512

Buffer to hold all contacts.

Typedef Documentation

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

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_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
endptEndpoint, used to allocate pool from.
tokenA data to be associated with the client registration struct.
cbPointer to callback function to receive registration status.
p_regcPointer 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
regcThe 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
regcThe client registration structure.
infoClient 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
regcThe 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
regcThe client registration structure.
srv_urlServer URL.
from_urlThe person performing the registration, must be a SIP URL type.
to_urlThe address of record for which the registration is targetd, must be a SIP/SIPS URL.
ccntNumber of contacts in the array.
contactArray 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.
expiresDefault 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_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
regcThe client registration structure.
tsx_cbPointer 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
regcThe client registration structure.
via_addrSet via_addr to use for the Via header or NULL to use the transport's published name.
via_tpvia_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
regcThe registration structure.
delayThe 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
regcThe registration structure.
countNumber of credentials in the array.
credArray 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
regcThe registration structure.
prefAuthentication 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
regcThe client registration structure.
route_setList 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
regcThe client registration instance.
selTransport 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
regcThe 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
regcThe client registration structure.
hdr_listList 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
regcThe client registration structure.
autoregIf non zero, the library will automatically refresh the next registration until application unregister.
p_tdataPointer 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
regcThe client registration structure.
p_tdataPointer 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
regcThe client registration structure.
p_tdataPointer 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
regcThe client registration structure.
ccntNumber of contacts.
contactArray 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
regcThe client registration structure.
expiresThe 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
regcThe client registration structure.
tdataTransmit data.
Returns
PJ_SUCCESS on success.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.