BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

SIP Event State Publication (PUBLISH, RFC 3903)

Support for SIP Event State Publication (PUBLISH, RFC 3903) 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_tpjsip_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)
 

Variables

const pjsip_method pjsip_publish_method
 

Detailed Description

This module contains the implementation of Session Initiation Protocol (SIP) Extension for Event State Publication (PUBLISH) as defined by RFC 3903.

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

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
optThe option.

◆ pjsip_publishc_init_module()

pj_status_t pjsip_publishc_init_module ( pjsip_endpoint endpt)

Initialize client publication module.

Parameters
endptSIP 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
endptEndpoint, used to allocate pool from.
optOptions, or NULL to specify default options.
tokenOpaque data to be associated with the client publication.
cbPointer to callback function to receive publication status.
p_pubcPointer 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
pubcThe 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
pubcThe 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
pubcThe client publication structure.
eventThe Event identification (e.g. "presence").
target_uriThe URI of the presentity which the which the status is being published.
from_uriThe URI of the endpoint who sends the event publication. Normally the value would be the same as target_uri.
to_uriThe URI to be put in To header. Normally the value would be the same as target_uri.
expiresThe 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
pubcThe publication structure.
countNumber of credentials in the array.
cArray 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
pubcThe client publication structure.
rsList 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
pubcThe client publication structure.
hdr_listThe 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
pubcThe client publication 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.

◆ 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
pubcThe client publication session.
auto_refreshIf non zero, the library will automatically refresh the next publication until application unpublish.
p_tdataPointer 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
pubcThe client publication structure.
p_tdataPointer 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
pubcThe client publication structure.
expiresThe 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
pubcThe client publication structure.
tdataTransmit 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.

Variable Documentation

◆ pjsip_publish_method

const pjsip_method pjsip_publish_method

The SIP PUBLISH method constant.

 


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