1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
/* $Header: /pjproject/pjsip/src/pjsip_simple/presence.h 6 8/24/05 10:33a Bennylp $ */
#ifndef __PJSIP_SIMPLE_PRESENCE_H__
#define __PJSIP_SIMPLE_PRESENCE_H__
/**
* @file presence.h
* @brief SIP Extension for Presence (RFC 3856)
*/
#include <pjsip_simple/event_notify.h>
#include <pjsip_simple/pidf.h>
#include <pjsip_simple/xpidf.h>
PJ_BEGIN_DECL
/**
* @defgroup PJSIP_SIMPLE_PRES SIP Extension for Presence (RFC 3856)
* @ingroup PJSIP_SIMPLE
* @{
*
* This module contains the implementation of SIP Presence Extension as
* described in RFC 3856. It uses the SIP Event Notification framework
* (event_notify.h) and extends the framework by implementing "presence"
* event package.
*/
/**
* Presence message body type.
*/
typedef enum pjsip_pres_type
{
PJSIP_PRES_TYPE_PIDF,
PJSIP_PRES_TYPE_XPIDF,
} pjsip_pres_type;
/**
* This structure describe a presentity, for both subscriber and notifier.
*/
typedef struct pjsip_presentity
{
pjsip_event_sub *sub; /**< Event subscribtion record. */
pjsip_pres_type pres_type; /**< Presentity type. */
pjsip_msg_body *uas_body; /**< Message body (UAS only). */
union {
pjpidf_pres *pidf;
pjxpidf_pres *xpidf;
} uas_data; /**< UAS data. */
pj_str_t timestamp; /**< Time of last update. */
void *user_data; /**< Application data. */
} pjsip_presentity;
/**
* This structure describe callback that is registered to receive notification
* from the presence module.
*/
typedef struct pjsip_presence_cb
{
/**
* This callback is first called when the module receives incoming
* SUBSCRIBE request to determine whether application wants to accept
* the request. If it does, then on_presence_request will be called.
*
* @param rdata The received message.
* @return Application should return 2xx to accept the request,
* or failure status (>=300) to reject the request.
*/
void (*accept_presence)(pjsip_rx_data *rdata, int *status);
/**
* This callback is called when the module receive the first presence
* subscription request.
*
* @param pres The presence descriptor.
* @param rdata The incoming request.
* @param timeout Timeout to be set for incoming request. Otherwise
* app can just leave this and accept the default.
*/
void (*on_received_request)(pjsip_presentity *pres, pjsip_rx_data *rdata,
int *timeout);
/**
* This callback is called when the module received subscription refresh
* request.
*
* @param pres The presence descriptor.
* @param rdata The incoming request.
*/
void (*on_received_refresh)(pjsip_presentity *pres, pjsip_rx_data *rdata);
/**
* This callback is called when the module receives incoming NOTIFY
* request.
*
* @param pres The presence descriptor.
* @param open The latest status of the presentity.
*/
void (*on_received_update)(pjsip_presentity *pres, pj_bool_t open);
/**
* This callback is called when the subscription has terminated.
*
* @param sub The subscription instance.
* @param reason The termination reason.
*/
void (*on_terminated)(pjsip_presentity *pres, const pj_str_t *reason);
} pjsip_presence_cb;
/**
* Initialize the presence module and register callback.
*
* @param cb Callback structure.
*/
PJ_DECL(void) pjsip_presence_init(const pjsip_presence_cb *cb);
/**
* Create to presence subscription of a presentity URL.
*
* @param endpt Endpoint instance.
* @param local_url Local URL.
* @param remote_url Remote URL which the presence is being subscribed.
* @param expires The expiration.
* @param user_data User data to attach to presence subscription.
*
* @return The presence structure if successfull, or NULL if
* failed.
*/
PJ_DECL(pjsip_presentity*) pjsip_presence_create( pjsip_endpoint *endpt,
const pj_str_t *local_url,
const pj_str_t *remote_url,
int expires,
void *user_data );
/**
* Set credentials to be used by this presentity for outgoing requests.
*
* @param pres Presentity instance.
* @param count Number of credentials in the array.
* @param cred Array of credentials.
*
* @return Zero on success.
*/
PJ_DECL(pj_status_t) pjsip_presence_set_credentials( pjsip_presentity *pres,
int count,
const pjsip_cred_info cred[]);
/**
* Set route set for outgoing requests.
*
* @param pres Presentity instance.
* @param route_set List of route headers.
*
* @return Zero on success.
*/
PJ_DECL(pj_status_t) pjsip_presence_set_route_set( pjsip_presentity *pres,
const pjsip_route_hdr *hdr );
/**
* Send SUBSCRIBE request for the specified presentity.
*
* @param pres The presentity instance.
*
* @return Zero on success.
*/
PJ_DECL(pj_status_t) pjsip_presence_subscribe( pjsip_presentity *pres );
/**
* Ceased the presence subscription.
*
* @param pres The presence structure.
*
* @return Zero on success.
*/
PJ_DECL(pj_status_t) pjsip_presence_unsubscribe( pjsip_presentity *pres );
/**
* Notify subscriber about change in local status.
*
* @param pres The presence structure.
* @param state Set the state of the subscription.
* @param open Set the presence status (open or closed).
*
* @return Zero if a NOTIFY request can be sent.
*/
PJ_DECL(pj_status_t) pjsip_presence_notify( pjsip_presentity *pres,
pjsip_event_sub_state state,
pj_bool_t open );
/**
* Destroy presence structure and the underlying subscription.
*
* @param pres The presence structure.
*
* @return Zero if the subscription was destroyed, or one if
* the subscription can not be destroyed immediately
* and will be destroyed later, or -1 if failed.
*/
PJ_DECL(pj_status_t) pjsip_presence_destroy( pjsip_presentity *pres );
/**
* @}
*/
PJ_END_DECL
#endif /* __PJSIP_SIMPLE_PRESENCE_H__ */
|
