SIP Event State Publication Client

Event State Publication Clien. More...

Data Structures
struct	pjsip_publishc_opt
struct	pjsip_publishc_cbparam

Macros
#define	PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED   ((pj_uint32_t)0xFFFFFFFFUL)

Typedefs
typedef struct pjsip_publishc	pjsip_publishc
typedef void	pjsip_publishc_cb(struct pjsip_publishc_cbparam *param)

Functions
void	pjsip_publishc_opt_default (pjsip_publishc_opt *opt)
pj_status_t	pjsip_publishc_init_module (pjsip_endpoint *endpt)
pj_status_t	pjsip_publishc_create (pjsip_endpoint *endpt, const pjsip_publishc_opt *opt, void *token, pjsip_publishc_cb *cb, pjsip_publishc **p_pubc)
pj_status_t	pjsip_publishc_destroy (pjsip_publishc *pubc)
pj_pool_t *	pjsip_publishc_get_pool (pjsip_publishc *pubc)
pj_status_t	pjsip_publishc_init (pjsip_publishc *pubc, const pj_str_t *event, const pj_str_t *target_uri, const pj_str_t *from_uri, const pj_str_t *to_uri, pj_uint32_t expires)
pj_status_t	pjsip_publishc_set_credentials (pjsip_publishc *pubc, int count, const pjsip_cred_info c[])
pj_status_t	pjsip_publishc_set_route_set (pjsip_publishc *pubc, const pjsip_route_hdr *rs)
pj_status_t	pjsip_publishc_set_headers (pjsip_publishc *pubc, const pjsip_hdr *hdr_list)
pj_status_t	pjsip_publishc_set_via_sent_by (pjsip_publishc *pubc, pjsip_host_port *via_addr, pjsip_transport *via_tp)
pj_status_t	pjsip_publishc_publish (pjsip_publishc *pubc, pj_bool_t auto_refresh, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_publishc_unpublish (pjsip_publishc *pubc, pjsip_tx_data **p_tdata)
pj_status_t	pjsip_publishc_update_expires (pjsip_publishc *pubc, pj_uint32_t expires)
pj_status_t	pjsip_publishc_send (pjsip_publishc *pubc, pjsip_tx_data *tdata)

Detailed Description

Macro Definition Documentation

PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED

#define PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED   ((pj_uint32_t)0xFFFFFFFFUL)

Expiration not specified.

Typedef Documentation

pjsip_publishc

typedef struct pjsip_publishc pjsip_publishc

Opaque declaration for client side event publication session.

pjsip_publishc_cb

typedef void pjsip_publishc_cb(struct pjsip_publishc_cbparam *param)

Type declaration for callback to receive publication result.

Function Documentation

pjsip_publishc_opt_default()

void pjsip_publishc_opt_default

(

pjsip_publishc_opt *

opt

)

Initialize client publication session option with default values.

Parameters

opt	The option.

pjsip_publishc_init_module()

pj_status_t pjsip_publishc_init_module

(

pjsip_endpoint *

endpt

)

Initialize client publication module.

Parameters

endpt

SIP endpoint.

Returns

PJ_SUCCESS on success.

pjsip_publishc_create()

pj_status_t pjsip_publishc_create	(	pjsip_endpoint *	endpt,
		const pjsip_publishc_opt *	opt,
		void *	token,
		pjsip_publishc_cb *	cb,
		pjsip_publishc **	p_pubc
	)

Create client publication structure.

Parameters

endpt	Endpoint, used to allocate pool from.
opt	Options, or NULL to specify default options.
token	Opaque data to be associated with the client publication.
cb	Pointer to callback function to receive publication status.
p_pubc	Pointer to receive client publication structure.

Returns

PJ_SUCCESS on success.

pjsip_publishc_destroy()

pj_status_t pjsip_publishc_destroy

(

pjsip_publishc *

pubc

)

Destroy client publication structure. If a publication 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

pubc	The client publication structure.

Returns

PJ_SUCCESS on success.

pjsip_publishc_get_pool()

pj_pool_t * pjsip_publishc_get_pool

(

pjsip_publishc *

pubc

)

Get the memory pool associated with a publication client session.

Parameters

pubc	The client publication structure.

Returns

pool handle.

pjsip_publishc_init()

pj_status_t pjsip_publishc_init	(	pjsip_publishc *	pubc,
		const pj_str_t *	event,
		const pj_str_t *	target_uri,
		const pj_str_t *	from_uri,
		const pj_str_t *	to_uri,
		pj_uint32_t	expires
	)

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

Parameters

pubc	The client publication structure.
event	The Event identification (e.g. "presence").
target_uri	The URI of the presentity which the which the status is being published.
from_uri	The URI of the endpoint who sends the event publication. Normally the value would be the same as target_uri.
to_uri	The URI to be put in To header. Normally the value would be the same as target_uri.
expires	The default expiration of the event publication. If the value PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED is given, then no default expiration will be applied.

Returns

PJ_SUCCESS on success.

pjsip_publishc_set_credentials()

pj_status_t pjsip_publishc_set_credentials	(	pjsip_publishc *	pubc,
		int	count,
		const pjsip_cred_info	c[]
	)

Set authentication credentials to use by this publication.

Parameters

pubc	The publication structure.
count	Number of credentials in the array.
c	Array of credentials.

Returns

PJ_SUCCESS on success.

pjsip_publishc_set_route_set()

pj_status_t pjsip_publishc_set_route_set	(	pjsip_publishc *	pubc,
		const pjsip_route_hdr *	rs
	)

Set route set to be used for outgoing requests.

Parameters

pubc	The client publication structure.
rs	List containing Route headers.

Returns

PJ_SUCCESS on success.

pjsip_publishc_set_headers()

pj_status_t pjsip_publishc_set_headers	(	pjsip_publishc *	pubc,
		const pjsip_hdr *	hdr_list
	)

Set list of headers to be added to each PUBLISH request generated by the client publication session. Note that application can also add the headers to the request after calling pjsip_publishc_publish() or pjsip_publishc_unpublish(), but the benefit of this function is the headers will also be added to requests generated internally by the session, such as during session renewal/refresh.

Note that calling this function will clear the previously added list of headers.

Parameters

pubc	The client publication structure.
hdr_list	The list of headers.

Returns

PJ_SUCCESS on success.

pjsip_publishc_set_via_sent_by()

pj_status_t pjsip_publishc_set_via_sent_by	(	pjsip_publishc *	pubc,
		pjsip_host_port *	via_addr,
		pjsip_transport *	via_tp
	)

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

Parameters

pubc	The client publication 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_publishc_publish()

pj_status_t pjsip_publishc_publish	(	pjsip_publishc *	pubc,
		pj_bool_t	auto_refresh,
		pjsip_tx_data **	p_tdata
	)

Create PUBLISH request for the specified client publication structure. Application can use this function to both create initial publication or to modify existing publication.

After the PUBLISH request is created, application MUST fill in the body part of the request with the appropriate content for the Event being published.

Note that publication refresh are handled automatically by the session (as long as auto_refresh argument below is non-zero), and application should not use this function to perform publication refresh.

Parameters

pubc	The client publication session.
auto_refresh	If non zero, the library will automatically refresh the next publication until application unpublish.
p_tdata	Pointer to receive the PUBLISH request. Note that the request DOES NOT have a message body.

Returns

PJ_SUCCESS on success.

pjsip_publishc_unpublish()

pj_status_t pjsip_publishc_unpublish	(	pjsip_publishc *	pubc,
		pjsip_tx_data **	p_tdata
	)

Create PUBLISH request to unpublish the current client publication.

Parameters

pubc	The client publication structure.
p_tdata	Pointer to receive the PUBLISH request.

Returns

PJ_SUCCESS on success.

pjsip_publishc_update_expires()

pj_status_t pjsip_publishc_update_expires	(	pjsip_publishc *	pubc,
		pj_uint32_t	expires
	)

Update the client publication expiration value. Note that this DOES NOT automatically send outgoing PUBLISH request to update the publication session. If application wants to do this, then it must construct a PUBLISH request and send it to the server.

Parameters

pubc	The client publication structure.
expires	The new expires value.

Returns

PU_SUCCESS on successfull.

pjsip_publishc_send()

pj_status_t pjsip_publishc_send	(	pjsip_publishc *	pubc,
		pjsip_tx_data *	tdata
	)

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

If the session has another PUBLISH request outstanding, the behavior depends on whether request queueing is enabled in the session (this was set by setting queue_request field of pjsip_publishc_opt to true when calling pjsip_publishc_create(). Default is true). If request queueing is enabled, the request will be queued and the function will return PJ_EPENDING. One the outstanding request is complete, the queued request will be sent automatically. If request queueing is disabled, the function will reject the request and return PJ_EBUSY.

Parameters

pubc	The client publication structure.
tdata	Transmit data.

Returns

- PJ_SUCCESS on success, or

• PJ_EPENDING if request is queued, or
• PJ_EBUSY if request is rejected because another PUBLISH request is in progress, or
• other status code to indicate the error.

References PJ_END_DECL.