1
/* $Id: publish.h 4173 2012-06-20 10:39:05Z ming $ */
3
* Copyright (C) 2008-2011 Teluu Inc. (http://www.teluu.com)
4
* Copyright (C) 2003-2008 Benny Prijono <benny@prijono.org>
6
* This program is free software; you can redistribute it and/or modify
7
* it under the terms of the GNU General Public License as published by
8
* the Free Software Foundation; either version 2 of the License, or
9
* (at your option) any later version.
11
* This program is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14
* GNU General Public License for more details.
16
* You should have received a copy of the GNU General Public License
17
* along with this program; if not, write to the Free Software
18
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
#ifndef __PJSIP_SIMPLE_PUBLISH_H__
21
#define __PJSIP_SIMPLE_PUBLISH_H__
25
* @brief SIP Extension for Event State Publication (PUBLISH, RFC 3903)
28
#include <pjsip/sip_util.h>
29
#include <pjsip/sip_auth.h>
36
@defgroup PJSIP_SIMPLE_PUBLISH SIP Event State Publication (PUBLISH, RFC 3903)
38
@brief Support for SIP Event State Publication (PUBLISH, RFC 3903)
41
This module contains the implementation of Session Initiation Protocol (SIP)
42
Extension for Event State Publication (PUBLISH) as defined by RFC 3903.
46
* The SIP PUBLISH method constant.
48
extern const pjsip_method pjsip_publish_method;
51
/*****************************************************************************
52
* @defgroup PJSIP_SIMPLE_PUBLISH_CLIENT SIP Event State Publication Client
53
* @ingroup PJSIP_SIMPLE
54
* @brief Event State Publication Clien
59
/** Expiration not specified. */
60
#define PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED ((pj_uint32_t)0xFFFFFFFFUL)
63
* Opaque declaration for client side event publication session.
65
typedef struct pjsip_publishc pjsip_publishc;
69
* Client publication options. Application should initialize this structure
70
* with its default values by calling #pjsip_publishc_opt_default()
72
typedef struct pjsip_publishc_opt
75
* Specify whether the client publication session should queue the
76
* PUBLISH request should there be another PUBLISH transaction still
77
* pending. If this is set to false, the client will return error
78
* on the PUBLISH request if there is another PUBLISH transaction still
81
* Default: PJSIP_PUBLISHC_QUEUE_REQUEST
83
pj_bool_t queue_request;
88
/** Structure to hold parameters when calling application's callback.
89
* The application's callback is called when the client publication process
92
struct pjsip_publishc_cbparam
94
pjsip_publishc *pubc; /**< Client publication structure. */
95
void *token; /**< Arbitrary token. */
96
pj_status_t status; /**< Error status. */
97
int code; /**< SIP status code received. */
98
pj_str_t reason; /**< SIP reason phrase received. */
99
pjsip_rx_data *rdata; /**< The complete received response. */
100
int expiration;/**< Next expiration interval. If the
101
value is -1, it means the session
102
will not renew itself. */
106
/** Type declaration for callback to receive publication result. */
107
typedef void pjsip_publishc_cb(struct pjsip_publishc_cbparam *param);
111
* Initialize client publication session option with default values.
113
* @param opt The option.
115
PJ_DECL(void) pjsip_publishc_opt_default(pjsip_publishc_opt *opt);
119
* Initialize client publication module.
121
* @param endpt SIP endpoint.
123
* @return PJ_SUCCESS on success.
125
PJ_DECL(pj_status_t) pjsip_publishc_init_module(pjsip_endpoint *endpt);
129
* Create client publication structure.
131
* @param endpt Endpoint, used to allocate pool from.
132
* @param opt Options, or NULL to specify default options.
133
* @param token Opaque data to be associated with the client publication.
134
* @param cb Pointer to callback function to receive publication status.
135
* @param p_pubc Pointer to receive client publication structure.
137
* @return PJ_SUCCESS on success.
139
PJ_DECL(pj_status_t) pjsip_publishc_create( pjsip_endpoint *endpt,
140
const pjsip_publishc_opt *opt,
142
pjsip_publishc_cb *cb,
143
pjsip_publishc **p_pubc);
147
* Destroy client publication structure. If a publication transaction is
148
* in progress, then the structure will be deleted only after a final response
149
* has been received, and in this case, the callback won't be called.
151
* @param pubc The client publication structure.
153
* @return PJ_SUCCESS on success.
155
PJ_DECL(pj_status_t) pjsip_publishc_destroy(pjsip_publishc *pubc);
160
* Get the memory pool associated with a publication client session.
162
* @param pubc The client publication structure.
163
* @return pool handle.
165
PJ_DECL(pj_pool_t*) pjsip_publishc_get_pool(pjsip_publishc *pubc);
169
* Initialize client publication structure with various information needed to
170
* perform the publication.
172
* @param pubc The client publication structure.
173
* @param event The Event identification (e.g. "presence").
174
* @param target_uri The URI of the presentity which the which the status
175
* is being published.
176
* @param from_uri The URI of the endpoint who sends the event
177
* publication. Normally the value would be the same as
179
* @param to_uri The URI to be put in To header. Normally the value
180
* would be the same as target_uri.
181
* @param expires The default expiration of the event publication.
182
* If the value PJSIP_PUBC_EXPIRATION_NOT_SPECIFIED is
183
* given, then no default expiration will be applied.
185
* @return PJ_SUCCESS on success.
187
PJ_DECL(pj_status_t) pjsip_publishc_init(pjsip_publishc *pubc,
188
const pj_str_t *event,
189
const pj_str_t *target_uri,
190
const pj_str_t *from_uri,
191
const pj_str_t *to_uri,
192
pj_uint32_t expires);
196
* Set authentication credentials to use by this publication.
198
* @param pubc The publication structure.
199
* @param count Number of credentials in the array.
200
* @param c Array of credentials.
202
* @return PJ_SUCCESS on success.
204
PJ_DECL(pj_status_t) pjsip_publishc_set_credentials(pjsip_publishc *pubc,
206
const pjsip_cred_info c[]);
209
* Set route set to be used for outgoing requests.
211
* @param pubc The client publication structure.
212
* @param rs List containing Route headers.
214
* @return PJ_SUCCESS on success.
216
PJ_DECL(pj_status_t) pjsip_publishc_set_route_set(pjsip_publishc *pubc,
217
const pjsip_route_hdr *rs);
221
* Set list of headers to be added to each PUBLISH request generated by
222
* the client publication session. Note that application can also add
223
* the headers to the request after calling #pjsip_publishc_publish()
224
* or #pjsip_publishc_unpublish(), but the benefit of this function is
225
* the headers will also be added to requests generated internally by
226
* the session, such as during session renewal/refresh.
228
* Note that calling this function will clear the previously added list
231
* @param pubc The client publication structure.
232
* @param hdr_list The list of headers.
234
* @return PJ_SUCCESS on success.
236
PJ_DECL(pj_status_t) pjsip_publishc_set_headers(pjsip_publishc *pubc,
237
const pjsip_hdr *hdr_list);
240
* Set the "sent-by" field of the Via header for outgoing requests.
242
* @param pubc The client publication structure.
243
* @param via_addr Set via_addr to use for the Via header or NULL to use
244
* the transport's published name.
245
* @param via_tp via_addr will only be used if we are using via_tp
248
* @return PJ_SUCCESS on success.
250
PJ_DECL(pj_status_t) pjsip_publishc_set_via_sent_by(pjsip_publishc *pubc,
251
pjsip_host_port *via_addr,
252
pjsip_transport *via_tp);
256
* Create PUBLISH request for the specified client publication structure.
257
* Application can use this function to both create initial publication
258
* or to modify existing publication.
260
* After the PUBLISH request is created, application MUST fill in the
261
* body part of the request with the appropriate content for the Event
264
* Note that publication refresh are handled automatically by the session
265
* (as long as auto_refresh argument below is non-zero), and application
266
* should not use this function to perform publication refresh.
268
* @param pubc The client publication session.
269
* @param auto_refresh If non zero, the library will automatically
270
* refresh the next publication until application
272
* @param p_tdata Pointer to receive the PUBLISH request. Note that
273
* the request DOES NOT have a message body.
275
* @return PJ_SUCCESS on success.
277
PJ_DECL(pj_status_t) pjsip_publishc_publish(pjsip_publishc *pubc,
278
pj_bool_t auto_refresh,
279
pjsip_tx_data **p_tdata);
283
* Create PUBLISH request to unpublish the current client publication.
285
* @param pubc The client publication structure.
286
* @param p_tdata Pointer to receive the PUBLISH request.
288
* @return PJ_SUCCESS on success.
290
PJ_DECL(pj_status_t) pjsip_publishc_unpublish(pjsip_publishc *pubc,
291
pjsip_tx_data **p_tdata);
295
* Update the client publication expiration value. Note that this DOES NOT
296
* automatically send outgoing PUBLISH request to update the publication
297
* session. If application wants to do this, then it must construct a
298
* PUBLISH request and send it to the server.
300
* @param pubc The client publication structure.
301
* @param expires The new expires value.
303
* @return PU_SUCCESS on successfull.
305
PJ_DECL(pj_status_t) pjsip_publishc_update_expires(pjsip_publishc *pubc,
306
pj_uint32_t expires );
310
* Sends outgoing PUBLISH request. The process will complete asynchronously,
311
* and application will be notified via the callback when the process
314
* If the session has another PUBLISH request outstanding, the behavior
315
* depends on whether request queueing is enabled in the session (this was
316
* set by setting \a queue_request field of #pjsip_publishc_opt to true
317
* when calling #pjsip_publishc_create(). Default is true). If request
318
* queueing is enabled, the request will be queued and the function will
319
* return PJ_EPENDING. One the outstanding request is complete, the queued
320
* request will be sent automatically. If request queueing is disabled, the
321
* function will reject the request and return PJ_EBUSY.
323
* @param pubc The client publication structure.
324
* @param tdata Transmit data.
326
* @return - PJ_SUCCESS on success, or
327
* - PJ_EPENDING if request is queued, or
328
* - PJ_EBUSY if request is rejected because another PUBLISH
329
* request is in progress, or
330
* - other status code to indicate the error.
332
PJ_DECL(pj_status_t) pjsip_publishc_send(pjsip_publishc *pubc,
333
pjsip_tx_data *tdata);
348
#endif /* __PJSIP_SIMPLE_PUBLISH_H__ */