pjsip logo pjsip.org
Open source SIP stack and media stack for presence, im/instant messaging, and multimedia communication
Loading

HOME

SIP/media Features
High Performance SIP
Small Footprint SIP
Symbian Port

FAQ

Documentation

Licensing

Download

Development (Trac)

Projects using pjsip

Mailing List

Open Source Links

About: PJLIB, PJLIB-UTIL, PJSIP, and PJMEDIA are created by: Benny Prijono
<bennylp@pjsip.org>

 

Home --> Documentations --> PJSIP Reference

Client Registration
[User Agent Library]

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

Data Structures

struct  pjsip_regc_cbparam
struct  pjsip_regc_info

Defines

#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)

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

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

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

 

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