f6c6e4109cbd2ded37436d89ec0d9d2fd542e28e
[asterisk/asterisk.git] / include / asterisk / res_pjsip_pubsub.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2013, Digium, Inc.
5  *
6  * Mark Michelson <mmichelson@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 #ifndef _RES_PJSIP_PUBSUB_H
20 #define _RES_PJSIP_PUBSUB_H
21
22 #include "asterisk/linkedlists.h"
23
24 /* Forward declarations */
25 struct pjsip_rx_data;
26 struct pjsip_tx_data;
27 struct pjsip_evsub;
28 struct ast_sip_endpoint;
29 struct ast_datastore;
30 struct ast_datastore_info;
31
32 /*!
33  * \brief Opaque structure representing a publication
34  */
35 struct ast_sip_publication;
36
37 /*!
38  * \brief Callbacks that publication handlers will define
39  */
40 struct ast_sip_publish_handler {
41         /*! \brief The name of the event this handler deals with */
42         const char *event_name;
43
44         /*! \brief Publications */
45         struct ao2_container *publications;
46
47         /*!
48          * \brief Called when a PUBLISH to establish a new publication arrives.
49          *
50          * \param endpoint The endpoint from whom the PUBLISH arrived
51          * \param rdata The PUBLISH request
52          * \retval NULL PUBLISH was not accepted
53          * \retval non-NULL New publication
54          *
55          * \note The callback is expected to send a response for the PUBLISH in success cases.
56          */
57         struct ast_sip_publication *(*new_publication)(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
58
59         /*!
60          * \brief Called when a PUBLISH for an existing publication arrives.
61          *
62          * This PUBLISH may be intending to change state or it may be simply renewing
63          * the publication since the publication is nearing expiration. The callback
64          * is expected to send a response to the PUBLISH.
65          *
66          * \param pub The publication on which the PUBLISH arrived
67          * \param rdata The PUBLISH request
68          * \retval 0 Publication was accepted
69          * \retval non-zero Publication was denied
70          *
71          * \note The callback is expected to send a response for the PUBLISH.
72          */
73         int (*publish_refresh)(struct ast_sip_publication *pub, pjsip_rx_data *rdata);
74
75         /*!
76          * \brief Called when a publication has reached its expiration.
77          */
78         void (*publish_expire)(struct ast_sip_publication *pub);
79
80         /*!
81          * \brief Called when a PUBLISH arrives to terminate a publication.
82          *
83          * \param pub The publication that is terminating
84          * \param rdata The PUBLISH request terminating the publication
85          *
86          * \note The callback is expected to send a response for the PUBLISH.
87          */
88         void (*publish_termination)(struct ast_sip_publication *pub, pjsip_rx_data *rdata);
89
90         AST_LIST_ENTRY(ast_sip_publish_handler) next;
91 };
92
93 /*!
94  * \brief Create a new publication
95  *
96  * Publication handlers should call this when a PUBLISH arrives to establish a new publication.
97  *
98  * \param endpoint The endpoint from whom the PUBLISHes arrive
99  * \param rdata The PUBLISH that established the publication
100  * \retval NULL Failed to create a publication
101  * \retval non-NULL The newly-created publication
102  */
103 struct ast_sip_publication *ast_sip_create_publication(struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
104
105 /*!
106  * \brief Given a publication, get the associated endpoint
107  *
108  * \param pub The publication
109  * \retval NULL Failure
110  * \retval non-NULL The associated endpoint
111  */
112 struct ast_sip_endpoint *ast_sip_publication_get_endpoint(struct ast_sip_publication *pub);
113
114 /*!
115  * \brief Create a response to an inbound PUBLISH
116  *
117  * The created response must be sent using ast_sip_publication_send_response
118  *
119  * \param pub The publication
120  * \param status code The status code to place in the response
121  * \param rdata The request to which the response is being made
122  * \param[out] tdata The created response
123  */
124 int ast_sip_publication_create_response(struct ast_sip_publication *pub, int status_code, pjsip_rx_data *rdata,
125         pjsip_tx_data **tdata);
126
127 /*!
128  * \brief Send a response for an inbound PUBLISH
129  *
130  * \param pub The publication
131  * \param rdata The request to which the response was made
132  * \param tdata The response to the request
133  */
134 pj_status_t ast_sip_publication_send_response(struct ast_sip_publication *pub, pjsip_rx_data *rdata,
135         pjsip_tx_data *tdata);
136
137 /*!
138  * \brief Register a publish handler
139  *
140  * \retval 0 Handler was registered successfully
141  * \retval non-zero Handler was not registered successfully
142  */
143 int ast_sip_register_publish_handler(struct ast_sip_publish_handler *handler);
144
145 /*!
146  * \brief Unregister a publish handler
147  */
148 void ast_sip_unregister_publish_handler(struct ast_sip_publish_handler *handler);
149
150 /*!
151  * \brief Add a datastore to a SIP publication
152  *
153  * Note that SIP uses reference counted datastores. The datastore passed into this function
154  * must have been allocated using ao2_alloc() or there will be serious problems.
155  *
156  * \param publication The publication to add the datastore to
157  * \param datastore The datastore to be added to the subscription
158  * \retval 0 Success
159  * \retval -1 Failure
160  */
161 int ast_sip_publication_add_datastore(struct ast_sip_publication *publication, struct ast_datastore *datastore);
162
163 /*!
164  * \brief Retrieve a publication datastore
165  *
166  * The datastore retrieved will have its reference count incremented. When the caller is done
167  * with the datastore, the reference counted needs to be decremented using ao2_ref().
168  *
169  * \param publication The publication from which to retrieve the datastore
170  * \param name The name of the datastore to retrieve
171  * \retval NULL Failed to find the specified datastore
172  * \retval non-NULL The specified datastore
173  */
174 struct ast_datastore *ast_sip_publication_get_datastore(struct ast_sip_publication *publication, const char *name);
175
176 /*!
177  * \brief Remove a publication datastore from the publication
178  *
179  * This operation may cause the datastore's free() callback to be called if the reference
180  * count reaches zero.
181  *
182  * \param publication The publication to remove the datastore from
183  * \param name The name of the datastore to remove
184  */
185 void ast_sip_publication_remove_datastore(struct ast_sip_publication *publication, const char *name);
186
187 /*!
188  * \brief Opaque structure representing an RFC 3265 SIP subscription
189  */
190 struct ast_sip_subscription;
191
192 /*!
193  * \brief Role for the subscription that is being created
194  */
195 enum ast_sip_subscription_role {
196         /* Sending SUBSCRIBEs, receiving NOTIFYs */
197         AST_SIP_SUBSCRIBER,
198         /* Sending NOTIFYs, receiving SUBSCRIBEs */
199         AST_SIP_NOTIFIER,
200 };
201
202 /*!
203  * \brief Data for responses to SUBSCRIBEs and NOTIFIEs
204  *
205  * Some of PJSIP's evsub callbacks expect us to provide them
206  * with data so that they can craft a response rather than have
207  * us create our own response.
208  *
209  * Filling in the structure is optional, since the framework
210  * will automatically respond with a 200 OK response if we do
211  * not provide it with any additional data.
212  */
213 struct ast_sip_subscription_response_data {
214         /*! Status code of the response */
215         int status_code;
216         /*! Optional status text */
217         const char *status_text;
218         /*! Optional additional headers to add to the response */
219         struct ast_variable *headers;
220         /*! Optional body to add to the response */
221         struct ast_sip_body *body;
222 };
223
224 #define AST_SIP_MAX_ACCEPT 32
225
226 struct ast_sip_subscription_handler {
227         /*! The name of the event this handler deals with */
228         const char *event_name;
229         /*! The types of body this handler accepts */
230         const char *accept[AST_SIP_MAX_ACCEPT];
231
232         /*!
233          * \brief Called when a subscription is to be destroyed
234          *
235          * This is a subscriber and notifier callback.
236          *
237          * The handler is not expected to send any sort of requests or responses
238          * during this callback. The handler MUST, however, begin the destruction
239          * process for the subscription during this callback.
240          */
241    void (*subscription_shutdown)(struct ast_sip_subscription *subscription);
242
243         /*!
244          * \brief Called when a SUBSCRIBE arrives in order to create a new subscription
245          *
246          * This is a notifier callback.
247          *
248          * If the notifier wishes to accept the subscription, then it can create
249          * a new ast_sip_subscription to do so.
250          *
251          * If the notifier chooses to create a new subscription, then it must accept
252          * the incoming subscription using pjsip_evsub_accept() and it must also
253          * send an initial NOTIFY with the current subscription state.
254          *
255          * \param endpoint The endpoint from which we received the SUBSCRIBE
256          * \param rdata The SUBSCRIBE request
257          * \retval NULL The SUBSCRIBE has not been accepted
258          * \retval non-NULL The newly-created subscription
259          */
260         struct ast_sip_subscription *(*new_subscribe)(struct ast_sip_endpoint *endpoint,
261                         pjsip_rx_data *rdata);
262
263         /*!
264          * \brief Called when an endpoint renews a subscription.
265          *
266          * This is a notifier callback.
267          *
268          * Because of the way that the PJSIP evsub framework works, it will automatically
269          * send a response to the SUBSCRIBE. However, the subscription handler must send
270          * a NOTIFY with the current subscription state when this callback is called.
271          *
272          * The response_data that is passed into this callback is used to craft what should
273          * be in the response to the incoming SUBSCRIBE. It is initialized with a 200 status
274          * code and all other parameters are empty.
275          *
276          * \param sub The subscription that is being renewed
277          * \param rdata The SUBSCRIBE request in question
278          * \param[out] response_data Data pertaining to the SIP response that should be
279          * sent to the SUBSCRIBE
280          */
281         void (*resubscribe)(struct ast_sip_subscription *sub,
282                         pjsip_rx_data *rdata, struct ast_sip_subscription_response_data *response_data);
283
284         /*!
285          * \brief Called when a subscription times out.
286          *
287          * This is a notifier callback
288          *
289          * This indicates that the subscription has timed out. The subscription handler is
290          * expected to send a NOTIFY that terminates the subscription.
291          *
292          * \param sub The subscription that has timed out
293          */
294         void (*subscription_timeout)(struct ast_sip_subscription *sub);
295
296         /*!
297          * \brief Called when a subscription is terminated via a SUBSCRIBE or NOTIFY request
298          *
299          * This is a notifier and subscriber callback.
300          *
301          * The PJSIP subscription framework will automatically send the response to the
302          * request. If a notifier receives this callback, then the subscription handler
303          * is expected to send a final NOTIFY to terminate the subscription.
304          *
305          * \param sub The subscription being terminated
306          * \param rdata The request that terminated the subscription
307          */
308         void (*subscription_terminated)(struct ast_sip_subscription *sub, pjsip_rx_data *rdata);
309
310         /*!
311          * \brief Called when a subscription handler's outbound NOTIFY receives a response
312          *
313          * This is a notifier callback.
314          *
315          * \param sub The subscription
316          * \param rdata The NOTIFY response
317          */
318         void (*notify_response)(struct ast_sip_subscription *sub, pjsip_rx_data *rdata);
319
320         /*!
321          * \brief Called when a subscription handler receives an inbound NOTIFY
322          *
323          * This is a subscriber callback.
324          *
325          * Because of the way that the PJSIP evsub framework works, it will automatically
326          * send a response to the NOTIFY. By default this will be a 200 OK response, but
327          * this callback can change details of the response by returning response data
328          * to use.
329          *
330          * The response_data that is passed into this callback is used to craft what should
331          * be in the response to the incoming SUBSCRIBE. It is initialized with a 200 status
332          * code and all other parameters are empty.
333          *
334          * \param sub The subscription
335          * \param rdata The NOTIFY request
336          * \param[out] response_data Data pertaining to the SIP response that should be
337          * sent to the SUBSCRIBE
338          */
339         void (*notify_request)(struct ast_sip_subscription *sub,
340                         pjsip_rx_data *rdata, struct ast_sip_subscription_response_data *response_data);
341
342         /*!
343          * \brief Called when it is time for a subscriber to resubscribe
344          *
345          * This is a subscriber callback.
346          *
347          * The subscriber can reresh the subscription using the pjsip_evsub_initiate()
348          * function.
349          *
350          * \param sub The subscription to refresh
351          * \retval 0 Success
352          * \retval non-zero Failure
353          */
354         int (*refresh_subscription)(struct ast_sip_subscription *sub);
355         AST_LIST_ENTRY(ast_sip_subscription_handler) next;
356 };
357
358 /*!
359  * \brief Create a new ast_sip_subscription structure
360  *
361  * In most cases the pubsub core will create a general purpose subscription
362  * within PJSIP. However, PJSIP provides enhanced support for the following
363  * event packages:
364  *
365  * presence
366  * message-summary
367  *
368  * If either of these events are handled by the subscription handler, then
369  * the special-purpose event subscriptions will be created within PJSIP,
370  * and it will be expected that your subscription handler make use of the
371  * special PJSIP APIs.
372  *
373  * \param handler The subsription handler for this subscription
374  * \param role Whether we are acting as subscriber or notifier for this subscription
375  * \param endpoint The endpoint involved in this subscription
376  * \param rdata If acting as a notifier, the SUBSCRIBE request that triggered subscription creation
377  */
378 struct ast_sip_subscription *ast_sip_create_subscription(const struct ast_sip_subscription_handler *handler,
379                 enum ast_sip_subscription_role role, struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
380
381
382 /*!
383  * \brief Get the endpoint that is associated with this subscription
384  *
385  * This function will increase the reference count of the endpoint. Be sure to
386  * release the reference to it when you are finished with the endpoint.
387  *
388  * \retval NULL Could not get endpoint
389  * \retval non-NULL The endpoint
390  */
391 struct ast_sip_endpoint *ast_sip_subscription_get_endpoint(struct ast_sip_subscription *sub);
392
393 /*!
394  * \brief Get the serializer for the subscription
395  *
396  * Tasks that originate outside of a SIP servant thread should get the serializer
397  * and push the task to the serializer.
398  *
399  * \param sub The subscription
400  * \retval NULL Failure
401  * \retval non-NULL The subscription's serializer
402  */
403 struct ast_taskprocessor *ast_sip_subscription_get_serializer(struct ast_sip_subscription *sub);
404
405 /*!
406  * \brief Get the underlying PJSIP evsub structure
407  *
408  * This is useful when wishing to call PJSIP's API calls in order to
409  * create SUBSCRIBEs, NOTIFIES, etc. as well as get subscription state
410  *
411  * This function, as well as all methods called on the pjsip_evsub should
412  * be done in a SIP servant thread.
413  *
414  * \param sub The subscription
415  * \retval NULL Failure
416  * \retval non-NULL The underlying pjsip_evsub
417  */
418 pjsip_evsub *ast_sip_subscription_get_evsub(struct ast_sip_subscription *sub);
419
420 /*!
421  * \brief Get the underlying PJSIP dialog structure
422  *
423  * Call this function when information needs to be retrieved from the
424  * underlying pjsip dialog.
425  *
426  * This function, as well as all methods called on the pjsip_evsub should
427  * be done in a SIP servant thread.
428  *
429  * \param sub The subscription
430  * \retval NULL Failure
431  * \retval non-NULL The underlying pjsip_dialog
432  */
433 pjsip_dialog *ast_sip_subscription_get_dlg(struct ast_sip_subscription *sub);
434
435 /*!
436  * \brief Send a request created via a PJSIP evsub method
437  *
438  * Callers of this function should take care to do so within a SIP servant
439  * thread.
440  *
441  * \param sub The subscription on which to send the request
442  * \param tdata The request to send
443  * \retval 0 Success
444  * \retval non-zero Failure
445  */
446 int ast_sip_subscription_send_request(struct ast_sip_subscription *sub, pjsip_tx_data *tdata);
447
448 /*!
449  * \brief Alternative for ast_datastore_alloc()
450  *
451  * There are two major differences between this and ast_datastore_alloc()
452  * 1) This allocates a refcounted object
453  * 2) This will fill in a uid if one is not provided
454  *
455  * DO NOT call ast_datastore_free() on a datastore allocated in this
456  * way since that function will attempt to free the datastore rather
457  * than play nicely with its refcount.
458  *
459  * \param info Callbacks for datastore
460  * \param uid Identifier for datastore
461  * \retval NULL Failed to allocate datastore
462  * \retval non-NULL Newly allocated datastore
463  */
464 struct ast_datastore *ast_sip_subscription_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
465
466 /*!
467  * \brief Add a datastore to a SIP subscription
468  *
469  * Note that SIP uses reference counted datastores. The datastore passed into this function
470  * must have been allocated using ao2_alloc() or there will be serious problems.
471  *
472  * \param subscription The ssubscription to add the datastore to
473  * \param datastore The datastore to be added to the subscription
474  * \retval 0 Success
475  * \retval -1 Failure
476  */
477 int ast_sip_subscription_add_datastore(struct ast_sip_subscription *subscription, struct ast_datastore *datastore);
478
479 /*!
480  * \brief Retrieve a subscription datastore
481  *
482  * The datastore retrieved will have its reference count incremented. When the caller is done
483  * with the datastore, the reference counted needs to be decremented using ao2_ref().
484  *
485  * \param subscription The subscription from which to retrieve the datastore
486  * \param name The name of the datastore to retrieve
487  * \retval NULL Failed to find the specified datastore
488  * \retval non-NULL The specified datastore
489  */
490 struct ast_datastore *ast_sip_subscription_get_datastore(struct ast_sip_subscription *subscription, const char *name);
491
492 /*!
493  * \brief Remove a subscription datastore from the subscription
494  *
495  * This operation may cause the datastore's free() callback to be called if the reference
496  * count reaches zero.
497  *
498  * \param subscription The subscription to remove the datastore from
499  * \param name The name of the datastore to remove
500  */
501 void ast_sip_subscription_remove_datastore(struct ast_sip_subscription *subscription, const char *name);
502
503 /*!
504  * \brief Register a subscription handler
505  *
506  * \retval 0 Handler was registered successfully
507  * \retval non-zero Handler was not registered successfully
508  */
509 int ast_sip_register_subscription_handler(struct ast_sip_subscription_handler *handler);
510
511 /*!
512  * \brief Unregister a subscription handler
513  */
514 void ast_sip_unregister_subscription_handler(struct ast_sip_subscription_handler *handler);
515
516 #endif /* RES_PJSIP_PUBSUB_H */