Handle default body types for SIP event packages in res_pjsip_pubsub
[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          * \brief Indicates if this handler can be used as a default handler for an event type.
233          *
234          * Typically, a SUBSCRIBE request will contain one or more Accept headers that tell
235          * what format they expect the body of NOTIFY requests to use. However, every event
236          * package is required to define a default body format type to be used if a SUBSCRIBE
237          * request for the event contains no Accept header.
238          *
239          * If this value is non-zero, then this handler provides the default body format for
240          * the event package and can handle SUBSCRIBES with no Accept headers present.
241          * If this value is zero, then this handler provides an alternative body format
242          * from the default for the event package and cannot handle SUBSCRIBEs with no
243          * Accept header.
244          */
245         unsigned int handles_default_accept;
246         /*!
247          * \brief Called when a subscription is to be destroyed
248          *
249          * This is a subscriber and notifier callback.
250          *
251          * The handler is not expected to send any sort of requests or responses
252          * during this callback. The handler MUST, however, begin the destruction
253          * process for the subscription during this callback.
254          */
255    void (*subscription_shutdown)(struct ast_sip_subscription *subscription);
256
257         /*!
258          * \brief Called when a SUBSCRIBE arrives in order to create a new subscription
259          *
260          * This is a notifier callback.
261          *
262          * If the notifier wishes to accept the subscription, then it can create
263          * a new ast_sip_subscription to do so.
264          *
265          * If the notifier chooses to create a new subscription, then it must accept
266          * the incoming subscription using pjsip_evsub_accept() and it must also
267          * send an initial NOTIFY with the current subscription state.
268          *
269          * \param endpoint The endpoint from which we received the SUBSCRIBE
270          * \param rdata The SUBSCRIBE request
271          * \retval NULL The SUBSCRIBE has not been accepted
272          * \retval non-NULL The newly-created subscription
273          */
274         struct ast_sip_subscription *(*new_subscribe)(struct ast_sip_endpoint *endpoint,
275                         pjsip_rx_data *rdata);
276
277         /*!
278          * \brief Called when an endpoint renews a subscription.
279          *
280          * This is a notifier callback.
281          *
282          * Because of the way that the PJSIP evsub framework works, it will automatically
283          * send a response to the SUBSCRIBE. However, the subscription handler must send
284          * a NOTIFY with the current subscription state when this callback is called.
285          *
286          * The response_data that is passed into this callback is used to craft what should
287          * be in the response to the incoming SUBSCRIBE. It is initialized with a 200 status
288          * code and all other parameters are empty.
289          *
290          * \param sub The subscription that is being renewed
291          * \param rdata The SUBSCRIBE request in question
292          * \param[out] response_data Data pertaining to the SIP response that should be
293          * sent to the SUBSCRIBE
294          */
295         void (*resubscribe)(struct ast_sip_subscription *sub,
296                         pjsip_rx_data *rdata, struct ast_sip_subscription_response_data *response_data);
297
298         /*!
299          * \brief Called when a subscription times out.
300          *
301          * This is a notifier callback
302          *
303          * This indicates that the subscription has timed out. The subscription handler is
304          * expected to send a NOTIFY that terminates the subscription.
305          *
306          * \param sub The subscription that has timed out
307          */
308         void (*subscription_timeout)(struct ast_sip_subscription *sub);
309
310         /*!
311          * \brief Called when a subscription is terminated via a SUBSCRIBE or NOTIFY request
312          *
313          * This is a notifier and subscriber callback.
314          *
315          * The PJSIP subscription framework will automatically send the response to the
316          * request. If a notifier receives this callback, then the subscription handler
317          * is expected to send a final NOTIFY to terminate the subscription.
318          *
319          * \param sub The subscription being terminated
320          * \param rdata The request that terminated the subscription
321          */
322         void (*subscription_terminated)(struct ast_sip_subscription *sub, pjsip_rx_data *rdata);
323
324         /*!
325          * \brief Called when a subscription handler's outbound NOTIFY receives a response
326          *
327          * This is a notifier callback.
328          *
329          * \param sub The subscription
330          * \param rdata The NOTIFY response
331          */
332         void (*notify_response)(struct ast_sip_subscription *sub, pjsip_rx_data *rdata);
333
334         /*!
335          * \brief Called when a subscription handler receives an inbound NOTIFY
336          *
337          * This is a subscriber callback.
338          *
339          * Because of the way that the PJSIP evsub framework works, it will automatically
340          * send a response to the NOTIFY. By default this will be a 200 OK response, but
341          * this callback can change details of the response by returning response data
342          * to use.
343          *
344          * The response_data that is passed into this callback is used to craft what should
345          * be in the response to the incoming SUBSCRIBE. It is initialized with a 200 status
346          * code and all other parameters are empty.
347          *
348          * \param sub The subscription
349          * \param rdata The NOTIFY request
350          * \param[out] response_data Data pertaining to the SIP response that should be
351          * sent to the SUBSCRIBE
352          */
353         void (*notify_request)(struct ast_sip_subscription *sub,
354                         pjsip_rx_data *rdata, struct ast_sip_subscription_response_data *response_data);
355
356         /*!
357          * \brief Called when it is time for a subscriber to resubscribe
358          *
359          * This is a subscriber callback.
360          *
361          * The subscriber can reresh the subscription using the pjsip_evsub_initiate()
362          * function.
363          *
364          * \param sub The subscription to refresh
365          * \retval 0 Success
366          * \retval non-zero Failure
367          */
368         int (*refresh_subscription)(struct ast_sip_subscription *sub);
369         AST_LIST_ENTRY(ast_sip_subscription_handler) next;
370 };
371
372 /*!
373  * \brief Create a new ast_sip_subscription structure
374  *
375  * In most cases the pubsub core will create a general purpose subscription
376  * within PJSIP. However, PJSIP provides enhanced support for the following
377  * event packages:
378  *
379  * presence
380  * message-summary
381  *
382  * If either of these events are handled by the subscription handler, then
383  * the special-purpose event subscriptions will be created within PJSIP,
384  * and it will be expected that your subscription handler make use of the
385  * special PJSIP APIs.
386  *
387  * \param handler The subsription handler for this subscription
388  * \param role Whether we are acting as subscriber or notifier for this subscription
389  * \param endpoint The endpoint involved in this subscription
390  * \param rdata If acting as a notifier, the SUBSCRIBE request that triggered subscription creation
391  */
392 struct ast_sip_subscription *ast_sip_create_subscription(const struct ast_sip_subscription_handler *handler,
393                 enum ast_sip_subscription_role role, struct ast_sip_endpoint *endpoint, pjsip_rx_data *rdata);
394
395
396 /*!
397  * \brief Get the endpoint that is associated with this subscription
398  *
399  * This function will increase the reference count of the endpoint. Be sure to
400  * release the reference to it when you are finished with the endpoint.
401  *
402  * \retval NULL Could not get endpoint
403  * \retval non-NULL The endpoint
404  */
405 struct ast_sip_endpoint *ast_sip_subscription_get_endpoint(struct ast_sip_subscription *sub);
406
407 /*!
408  * \brief Get the serializer for the subscription
409  *
410  * Tasks that originate outside of a SIP servant thread should get the serializer
411  * and push the task to the serializer.
412  *
413  * \param sub The subscription
414  * \retval NULL Failure
415  * \retval non-NULL The subscription's serializer
416  */
417 struct ast_taskprocessor *ast_sip_subscription_get_serializer(struct ast_sip_subscription *sub);
418
419 /*!
420  * \brief Get the underlying PJSIP evsub structure
421  *
422  * This is useful when wishing to call PJSIP's API calls in order to
423  * create SUBSCRIBEs, NOTIFIES, etc. as well as get subscription state
424  *
425  * This function, as well as all methods called on the pjsip_evsub should
426  * be done in a SIP servant thread.
427  *
428  * \param sub The subscription
429  * \retval NULL Failure
430  * \retval non-NULL The underlying pjsip_evsub
431  */
432 pjsip_evsub *ast_sip_subscription_get_evsub(struct ast_sip_subscription *sub);
433
434 /*!
435  * \brief Get the underlying PJSIP dialog structure
436  *
437  * Call this function when information needs to be retrieved from the
438  * underlying pjsip dialog.
439  *
440  * This function, as well as all methods called on the pjsip_evsub should
441  * be done in a SIP servant thread.
442  *
443  * \param sub The subscription
444  * \retval NULL Failure
445  * \retval non-NULL The underlying pjsip_dialog
446  */
447 pjsip_dialog *ast_sip_subscription_get_dlg(struct ast_sip_subscription *sub);
448
449 /*!
450  * \brief Send a request created via a PJSIP evsub method
451  *
452  * Callers of this function should take care to do so within a SIP servant
453  * thread.
454  *
455  * \param sub The subscription on which to send the request
456  * \param tdata The request to send
457  * \retval 0 Success
458  * \retval non-zero Failure
459  */
460 int ast_sip_subscription_send_request(struct ast_sip_subscription *sub, pjsip_tx_data *tdata);
461
462 /*!
463  * \brief Alternative for ast_datastore_alloc()
464  *
465  * There are two major differences between this and ast_datastore_alloc()
466  * 1) This allocates a refcounted object
467  * 2) This will fill in a uid if one is not provided
468  *
469  * DO NOT call ast_datastore_free() on a datastore allocated in this
470  * way since that function will attempt to free the datastore rather
471  * than play nicely with its refcount.
472  *
473  * \param info Callbacks for datastore
474  * \param uid Identifier for datastore
475  * \retval NULL Failed to allocate datastore
476  * \retval non-NULL Newly allocated datastore
477  */
478 struct ast_datastore *ast_sip_subscription_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
479
480 /*!
481  * \brief Add a datastore to a SIP subscription
482  *
483  * Note that SIP uses reference counted datastores. The datastore passed into this function
484  * must have been allocated using ao2_alloc() or there will be serious problems.
485  *
486  * \param subscription The ssubscription to add the datastore to
487  * \param datastore The datastore to be added to the subscription
488  * \retval 0 Success
489  * \retval -1 Failure
490  */
491 int ast_sip_subscription_add_datastore(struct ast_sip_subscription *subscription, struct ast_datastore *datastore);
492
493 /*!
494  * \brief Retrieve a subscription datastore
495  *
496  * The datastore retrieved will have its reference count incremented. When the caller is done
497  * with the datastore, the reference counted needs to be decremented using ao2_ref().
498  *
499  * \param subscription The subscription from which to retrieve the datastore
500  * \param name The name of the datastore to retrieve
501  * \retval NULL Failed to find the specified datastore
502  * \retval non-NULL The specified datastore
503  */
504 struct ast_datastore *ast_sip_subscription_get_datastore(struct ast_sip_subscription *subscription, const char *name);
505
506 /*!
507  * \brief Remove a subscription datastore from the subscription
508  *
509  * This operation may cause the datastore's free() callback to be called if the reference
510  * count reaches zero.
511  *
512  * \param subscription The subscription to remove the datastore from
513  * \param name The name of the datastore to remove
514  */
515 void ast_sip_subscription_remove_datastore(struct ast_sip_subscription *subscription, const char *name);
516
517 /*!
518  * \brief Register a subscription handler
519  *
520  * \retval 0 Handler was registered successfully
521  * \retval non-zero Handler was not registered successfully
522  */
523 int ast_sip_register_subscription_handler(struct ast_sip_subscription_handler *handler);
524
525 /*!
526  * \brief Unregister a subscription handler
527  */
528 void ast_sip_unregister_subscription_handler(struct ast_sip_subscription_handler *handler);
529
530 #endif /* RES_PJSIP_PUBSUB_H */