Abstract PJSIP-specific elements from the pubsub API.
[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 enum ast_sip_publish_state {
38     /*! Publication has just been initialized */
39     AST_SIP_PUBLISH_STATE_INITIALIZED,
40     /*! Publication is currently active */
41     AST_SIP_PUBLISH_STATE_ACTIVE,
42     /*! Publication has been terminated */
43     AST_SIP_PUBLISH_STATE_TERMINATED,
44 };
45
46 /*!
47  * \brief Callbacks that publication handlers will define
48  */
49 struct ast_sip_publish_handler {
50         /*! \brief The name of the event this handler deals with */
51         const char *event_name;
52
53         /*! \brief Publications */
54         struct ao2_container *publications;
55
56         /*!
57          * \brief Called when a PUBLISH to establish a new publication arrives.
58          *
59          * \param endpoint The endpoint from whom the PUBLISH arrived.
60          * \param resource The resource whose state is being published.
61          * \return Response code for the incoming PUBLISH
62          */
63         int (*new_publication)(struct ast_sip_endpoint *endpoint, const char *resource);
64         /*!
65          * \brief Called when a publication has reached its expiration.
66          */
67         void (*publish_expire)(struct ast_sip_publication *pub);
68         /*!
69          * \brief Published resource has changed states.
70          *
71          * The state parameter can be used to take further action. For instance,
72          * if the state is AST_SIP_PUBLISH_STATE_INITIALIZED, then this is the initial
73          * PUBLISH request. This is a good time to set up datastores on the publication
74          * or any other initial needs.
75          *
76          * AST_SIP_PUBLISH_STATE_TERMINATED is used when the remote end is terminating
77          * its publication. This is a good opportunity to free any resources associated with
78          * the publication.
79          *
80          * AST_SIP_PUBLISH_STATE_ACTIVE is used when a publication that modifies state
81          * arrives.
82          *
83          * \param pub The publication whose state has changed
84          * \param body The body of the inbound PUBLISH
85          * \param state The state of the publication
86          */
87         int (*publication_state_change)(struct ast_sip_publication *pub, pjsip_msg_body *body,
88                         enum ast_sip_publish_state state);
89         AST_LIST_ENTRY(ast_sip_publish_handler) next;
90 };
91
92 /*!
93  * \brief Given a publication, get the associated endpoint
94  *
95  * \param pub The publication
96  * \retval NULL Failure
97  * \retval non-NULL The associated endpoint
98  */
99 struct ast_sip_endpoint *ast_sip_publication_get_endpoint(struct ast_sip_publication *pub);
100
101 /*!
102  * \brief Register a publish handler
103  *
104  * \retval 0 Handler was registered successfully
105  * \retval non-zero Handler was not registered successfully
106  */
107 int ast_sip_register_publish_handler(struct ast_sip_publish_handler *handler);
108
109 /*!
110  * \brief Unregister a publish handler
111  */
112 void ast_sip_unregister_publish_handler(struct ast_sip_publish_handler *handler);
113
114 /*!
115  * \brief Add a datastore to a SIP publication
116  *
117  * Note that SIP uses reference counted datastores. The datastore passed into this function
118  * must have been allocated using ao2_alloc() or there will be serious problems.
119  *
120  * \param publication The publication to add the datastore to
121  * \param datastore The datastore to be added to the subscription
122  * \retval 0 Success
123  * \retval -1 Failure
124  */
125 int ast_sip_publication_add_datastore(struct ast_sip_publication *publication, struct ast_datastore *datastore);
126
127 /*!
128  * \brief Retrieve a publication datastore
129  *
130  * The datastore retrieved will have its reference count incremented. When the caller is done
131  * with the datastore, the reference counted needs to be decremented using ao2_ref().
132  *
133  * \param publication The publication from which to retrieve the datastore
134  * \param name The name of the datastore to retrieve
135  * \retval NULL Failed to find the specified datastore
136  * \retval non-NULL The specified datastore
137  */
138 struct ast_datastore *ast_sip_publication_get_datastore(struct ast_sip_publication *publication, const char *name);
139
140 /*!
141  * \brief Remove a publication datastore from the publication
142  *
143  * This operation may cause the datastore's free() callback to be called if the reference
144  * count reaches zero.
145  *
146  * \param publication The publication to remove the datastore from
147  * \param name The name of the datastore to remove
148  */
149 void ast_sip_publication_remove_datastore(struct ast_sip_publication *publication, const char *name);
150
151 /*!
152  * \brief Opaque structure representing an RFC 3265 SIP subscription
153  */
154 struct ast_sip_subscription;
155
156 /*!
157  * \brief Role for the subscription that is being created
158  */
159 enum ast_sip_subscription_role {
160         /* Sending SUBSCRIBEs, receiving NOTIFYs */
161         AST_SIP_SUBSCRIBER,
162         /* Sending NOTIFYs, receiving SUBSCRIBEs */
163         AST_SIP_NOTIFIER,
164 };
165
166 /*!
167  * \brief Data for responses to SUBSCRIBEs and NOTIFIEs
168  *
169  * Some of PJSIP's evsub callbacks expect us to provide them
170  * with data so that they can craft a response rather than have
171  * us create our own response.
172  *
173  * Filling in the structure is optional, since the framework
174  * will automatically respond with a 200 OK response if we do
175  * not provide it with any additional data.
176  */
177 struct ast_sip_subscription_response_data {
178         /*! Status code of the response */
179         int status_code;
180         /*! Optional status text */
181         const char *status_text;
182         /*! Optional additional headers to add to the response */
183         struct ast_variable *headers;
184         /*! Optional body to add to the response */
185         struct ast_sip_body *body;
186 };
187
188 #define AST_SIP_MAX_ACCEPT 32
189 enum ast_sip_subscription_notify_reason {
190         /*! Initial NOTIFY for subscription */
191         AST_SIP_SUBSCRIPTION_NOTIFY_REASON_STARTED,
192         /*! Subscription has been renewed */
193         AST_SIP_SUBSCRIPTION_NOTIFY_REASON_RENEWED,
194         /*! Subscription is being terminated */
195         AST_SIP_SUBSCRIPTION_NOTIFY_REASON_TERMINATED,
196         /*! Other unspecified reason */
197         AST_SIP_SUBSCRIPTION_NOTIFY_REASON_OTHER
198 };
199
200 struct ast_sip_notifier {
201         /*!
202          * \brief Default body type defined for the event package this notifier handles.
203          *
204          * Typically, a SUBSCRIBE request will contain one or more Accept headers that tell
205          * what format they expect the body of NOTIFY requests to use. However, every event
206          * package is required to define a default body format type to be used if a SUBSCRIBE
207          * request for the event contains no Accept header.
208          */
209         const char *default_accept;
210         /*!
211          * \brief Called when a SUBSCRIBE arrives attempting to establish a new subscription.
212          *
213          * The notifier is expected to return the response that should be sent to the
214          * SUBSCRIBE request.
215          *
216          * If a 200-class response is returned, then the notifier's notify_required
217          * callback will immediately be called into with a reason of
218          * AST_SIP_SUBSCRIPTION_NOTIFY_REASON_STARTED.
219          *
220          * \param endpoint The endpoint from which we received the SUBSCRIBE
221          * \param resource The name of the resource to which the subscription is being made
222          * \return The response code to send to the SUBSCRIBE.
223          */
224         int (*new_subscribe)(struct ast_sip_endpoint *endpoint, const char *resource);
225         /*!
226          * \brief The subscription is in need of a NOTIFY request.
227          *
228          * A reason of AST_SIP_SUBSCRIPTION_NOTIFY_REASON_STARTED is given immediately
229          * after a SUBSCRIBE is accepted. This is a good opportunity for the notifier to
230          * perform setup duties such as establishing Stasis subscriptions or adding
231          * datastores to the subscription.
232          *
233          * A reason of AST_SIP_SUBSCRIPTION_NOTIFY_REASON_TERMINATED is given when the
234          * subscriber has terminated the subscription. If there are any duties that the
235          *
236          *
237          * \param sub The subscription to send the NOTIFY on.
238          * \param reason The reason why the NOTIFY is being sent.
239          * \retval 0 Success
240          * \retval -1 Failure
241          */
242         int (*notify_required)(struct ast_sip_subscription *sub, enum ast_sip_subscription_notify_reason reason);
243 };
244
245 struct ast_sip_subscriber {
246         /*!
247          * \brief A NOTIFY has been received.
248          *
249          * The body of the NOTIFY is provided so that it may be parsed and appropriate
250          * internal state change may be generated.
251          *
252          * The state can be used to determine if the subscription has been terminated
253          * by the far end or if this is just a typical resource state change.
254          *
255          * \param sub The subscription on which the NOTIFY arrived
256          * \param body The body of the NOTIFY
257          * \param state The subscription state
258          */
259         void (*state_change)(struct ast_sip_subscription *sub, pjsip_msg_body *body, enum pjsip_evsub_state state);
260 };
261
262 struct ast_sip_subscription_handler {
263         /*! The name of the event this subscriber deals with */
264         const char *event_name;
265         /*! The types of body this subscriber accepts. */
266         const char *accept[AST_SIP_MAX_ACCEPT];
267         /*!
268          * \brief Called when a subscription is to be destroyed
269          *
270          * The handler is not expected to send any sort of requests or responses
271          * during this callback. The handler MUST, however, begin the destruction
272          * process for the subscription during this callback.
273          */
274         void (*subscription_shutdown)(struct ast_sip_subscription *subscription);
275         /*!
276          * \brief Converts the subscriber to AMI
277          *
278          * \param sub The subscription
279          * \param buf The string to write AMI data
280          */
281         void (*to_ami)(struct ast_sip_subscription *sub, struct ast_str **buf);
282         /*! Subscriber callbacks for this handler */
283         struct ast_sip_subscriber *subscriber;
284         /*! Notifier callbacks for this handler */
285         struct ast_sip_notifier *notifier;
286         AST_LIST_ENTRY(ast_sip_subscription_handler) next;
287 };
288
289 /*!
290  * \brief Create a new ast_sip_subscription structure
291  *
292  * When a subscriber wishes to create a subscription, it may call this function
293  * to allocate resources and to send the initial SUBSCRIBE out.
294  *
295  * \param subscriber The subscriber that is making the request.
296  * \param endpoint The endpoint to whome the SUBSCRIBE will be sent.
297  * \param resource The resource to place in the SUBSCRIBE's Request-URI.
298  */
299 struct ast_sip_subscription *ast_sip_create_subscription(const struct ast_sip_subscription_handler *handler,
300                 struct ast_sip_endpoint *endpoint, const char *resource);
301
302
303 /*!
304  * \brief Get the endpoint that is associated with this subscription
305  *
306  * This function will increase the reference count of the endpoint. Be sure to
307  * release the reference to it when you are finished with the endpoint.
308  *
309  * \retval NULL Could not get endpoint
310  * \retval non-NULL The endpoint
311  */
312 struct ast_sip_endpoint *ast_sip_subscription_get_endpoint(struct ast_sip_subscription *sub);
313
314 /*!
315  * \brief Get the serializer for the subscription
316  *
317  * Tasks that originate outside of a SIP servant thread should get the serializer
318  * and push the task to the serializer.
319  *
320  * \param sub The subscription
321  * \retval NULL Failure
322  * \retval non-NULL The subscription's serializer
323  */
324 struct ast_taskprocessor *ast_sip_subscription_get_serializer(struct ast_sip_subscription *sub);
325
326 /*!
327  * \brief Notify a SIP subscription of a state change.
328  *
329  * This will create a NOTIFY body to be sent out for the subscribed resource.
330  * On real subscriptions, a NOTIFY request will be generated and sent.
331  * On virtual subscriptions, the NOTIFY is saved on the virtual subscription and the
332  * parent subscription is alerted.
333  *
334  * \param sub The subscription on which a state change is occurring.
335  * \param notify_data Event package-specific data used to create the NOTIFY body.
336  * \param terminate True if this NOTIFY is intended to terminate the subscription.
337  * \retval 0 Success
338  * \retval non-zero Failure
339  */
340 int ast_sip_subscription_notify(struct ast_sip_subscription *sub, void *notify_data, int terminate);
341
342 /*!
343  * \brief Retrieve the local URI for this subscription
344  *
345  * This is the local URI as determined by the underlying SIP dialog.
346  *
347  * \param sub The subscription
348  * \param[out] buf The buffer into which to store the URI.
349  * \param size The size of the buffer.
350  */
351 void ast_sip_subscription_get_local_uri(struct ast_sip_subscription *sub, char *buf, size_t size);
352
353 /*!
354  * \brief Retrive the remote URI for this subscription
355  *
356  * This is the remote URI as determined by the underlying SIP dialog.
357  *
358  * \param sub The subscription
359  * \param[out] buf The buffer into which to store the URI.
360  * \param size The size of the buffer.
361  */
362 void ast_sip_subscription_get_remote_uri(struct ast_sip_subscription *sub, char *buf, size_t size);
363
364 /*!
365  * \brief Get the name of the subscribed resource.
366  */
367 const char *ast_sip_subscription_get_resource_name(struct ast_sip_subscription *sub);
368
369 /*!
370  * \brief Get a header value for a subscription.
371  *
372  * For notifiers, the headers of the inbound SUBSCRIBE that started the dialog
373  * are stored on the subscription. This method allows access to the header. The
374  * return is the same as pjsip_msg_find_hdr_by_name(), meaning that it is dependent
375  * on the header being searched for.
376  *
377  * \param sub The subscription to search in.
378  * \param header The name of the header to search for.
379  * \return The discovered header, or NULL if the header cannot be found.
380  */
381 void *ast_sip_subscription_get_header(const struct ast_sip_subscription *sub, const char *header);
382
383 /*!
384  * \brief Send a request created via a PJSIP evsub method
385  *
386  * Callers of this function should take care to do so within a SIP servant
387  * thread.
388  *
389  * \param sub The subscription on which to send the request
390  * \param tdata The request to send
391  * \retval 0 Success
392  * \retval non-zero Failure
393  */
394 int ast_sip_subscription_send_request(struct ast_sip_subscription *sub, pjsip_tx_data *tdata);
395
396 /*!
397  * \brief Alternative for ast_datastore_alloc()
398  *
399  * There are two major differences between this and ast_datastore_alloc()
400  * 1) This allocates a refcounted object
401  * 2) This will fill in a uid if one is not provided
402  *
403  * DO NOT call ast_datastore_free() on a datastore allocated in this
404  * way since that function will attempt to free the datastore rather
405  * than play nicely with its refcount.
406  *
407  * \param info Callbacks for datastore
408  * \param uid Identifier for datastore
409  * \retval NULL Failed to allocate datastore
410  * \retval non-NULL Newly allocated datastore
411  */
412 struct ast_datastore *ast_sip_subscription_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
413
414 /*!
415  * \brief Add a datastore to a SIP subscription
416  *
417  * Note that SIP uses reference counted datastores. The datastore passed into this function
418  * must have been allocated using ao2_alloc() or there will be serious problems.
419  *
420  * \param subscription The ssubscription to add the datastore to
421  * \param datastore The datastore to be added to the subscription
422  * \retval 0 Success
423  * \retval -1 Failure
424  */
425 int ast_sip_subscription_add_datastore(struct ast_sip_subscription *subscription, struct ast_datastore *datastore);
426
427 /*!
428  * \brief Retrieve a subscription datastore
429  *
430  * The datastore retrieved will have its reference count incremented. When the caller is done
431  * with the datastore, the reference counted needs to be decremented using ao2_ref().
432  *
433  * \param subscription The subscription from which to retrieve the datastore
434  * \param name The name of the datastore to retrieve
435  * \retval NULL Failed to find the specified datastore
436  * \retval non-NULL The specified datastore
437  */
438 struct ast_datastore *ast_sip_subscription_get_datastore(struct ast_sip_subscription *subscription, const char *name);
439
440 /*!
441  * \brief Remove a subscription datastore from the subscription
442  *
443  * This operation may cause the datastore's free() callback to be called if the reference
444  * count reaches zero.
445  *
446  * \param subscription The subscription to remove the datastore from
447  * \param name The name of the datastore to remove
448  */
449 void ast_sip_subscription_remove_datastore(struct ast_sip_subscription *subscription, const char *name);
450
451 /*!
452  * \brief Register a subscription handler
453  *
454  * \retval 0 Handler was registered successfully
455  * \retval non-zero Handler was not registered successfully
456  */
457 int ast_sip_register_subscription_handler(struct ast_sip_subscription_handler *handler);
458
459 /*!
460  * \brief Unregister a subscription handler
461  */
462 void ast_sip_unregister_subscription_handler(struct ast_sip_subscription_handler *handler);
463
464 /*!
465  * \brief Pubsub body generator
466  *
467  * A body generator is responsible for taking Asterisk content
468  * and converting it into a body format to be placed in an outbound
469  * SIP NOTIFY or PUBLISH request.
470  */
471 struct ast_sip_pubsub_body_generator {
472         /*!
473          * \brief Content type
474          * In "plain/text", "plain" is the type
475          */
476         const char *type;
477         /*!
478          * \brief Content subtype
479          * In "plain/text", "text" is the subtype
480          */
481         const char *subtype;
482         /*!
483          * \brief allocate body structure.
484          *
485          * Body generators will have this method called when a NOTIFY
486          * or PUBLISH body needs to be created. The type returned depends on
487          * the type of content being produced for the body. The data parameter
488          * is provided by the subscription handler and will vary between different
489          * event types.
490          *
491          * \param data The subscription data provided by the event handler
492          * \retval non-NULL The allocated body
493          * \retval NULL Failure
494          */
495         void *(*allocate_body)(void *data);
496         /*!
497          * \brief Add content to the body of a SIP request
498          *
499          * The body of the request has already been allocated by the body generator's
500          * allocate_body callback.
501          *
502          * \param body The body of the SIP request. The type is determined by the
503          * content type.
504          * \param data The subscription data used to populate the body. The type is
505          * determined by the content type.
506          */
507         int (*generate_body_content)(void *body, void *data);
508         /*!
509          * \brief Convert the body to a string.
510          *
511          * \param body The request body.
512          * \param str The converted string form of the request body
513          */
514         void (*to_string)(void *body, struct ast_str **str);
515         /*!
516          * \brief Deallocate resources created for the body
517          *
518          * Optional callback to destroy resources allocated for the
519          * message body.
520          *
521          * \param body Body to be destroyed
522          */
523         void (*destroy_body)(void *body);
524         AST_LIST_ENTRY(ast_sip_pubsub_body_generator) list;
525 };
526
527 /*!
528  * \brief Body supplement
529  *
530  * Body supplements provide additions to bodies not already
531  * provided by body generators. This may include proprietary
532  * extensions, optional content, or other nonstandard fare.
533  */
534 struct ast_sip_pubsub_body_supplement {
535         /*!
536          * \brief Content type
537          * In "plain/text", "plain" is the type
538          */
539         const char *type;
540         /*!
541          * \brief Content subtype
542          * In "plain/text", "text" is the subtype
543          */
544         const char *subtype;
545         /*!
546          * \brief Add additional content to a SIP request body.
547          *
548          * A body generator will have already allocated a body and populated
549          * it with base data for the event. The supplement's duty is, if desired,
550          * to extend the body to have optional data beyond what a base RFC specifies.
551          *
552          * \param body The body of the SIP request. The type is determined by the
553          * body generator that allocated the body.
554          * \param data The subscription data used to populate the body. The type is
555          * determined by the content type.
556          */
557         int (*supplement_body)(void *body, void *data);
558         AST_LIST_ENTRY(ast_sip_pubsub_body_supplement) list;
559 };
560
561 /*!
562  * \since 13.0.0
563  * \brief Generate body content for a PUBLISH or NOTIFY
564  *
565  * This function takes a pre-allocated body and calls into registered body
566  * generators in order to fill in the body with appropriate details.
567  * The primary body generator will be called first, followed by the
568  * supplementary body generators
569  *
570  * \param content_type The content type of the body
571  * \param content_subtype The content subtype of the body
572  * \param data The data associated with body generation.
573  * \param[out] str The string representation of the generated body
574  * \retval 0 Success
575  * \retval non-zero Failure
576  */
577 int ast_sip_pubsub_generate_body_content(const char *content_type,
578                 const char *content_subtype, void *data, struct ast_str **str);
579
580 /*!
581  * \since 13.0.0
582  * \brief Register a body generator with the pubsub core.
583  *
584  * This may fail if an attempt is made to register a primary body supplement
585  * for a given content type if a primary body supplement for that content type
586  * has already been registered.
587  *
588  * \param generator Body generator to register
589  * \retval 0 Success
590  * \retval -1 Failure
591  */
592 int ast_sip_pubsub_register_body_generator(struct ast_sip_pubsub_body_generator *generator);
593
594 /*!
595  * \since 13.0.0
596  * \brief Unregister a body generator with the pubsub core.
597  *
598  * \param generator Body generator to unregister
599  */
600 void ast_sip_pubsub_unregister_body_generator(struct ast_sip_pubsub_body_generator *generator);
601
602 /*!
603  * \since 13.0.0
604  * \brief Register a body generator with the pubsub core.
605  *
606  * This may fail if an attempt is made to register a primary body supplement
607  * for a given content type if a primary body supplement for that content type
608  * has already been registered.
609  *
610  * \param generator Body generator to register
611  * \retval 0 Success
612  * \retval -1 Failure
613  */
614 int ast_sip_pubsub_register_body_supplement(struct ast_sip_pubsub_body_supplement *supplement);
615
616 /*!
617  * \since 13.0.0
618  * \brief Unregister a body generator with the pubsub core.
619  *
620  * \param generator Body generator to unregister
621  */
622 void ast_sip_pubsub_unregister_body_supplement(struct ast_sip_pubsub_body_supplement *supplement);
623
624 /*!
625  * \since 13.0.0
626  * \brief Get the body type used for this subscription
627  */
628 const char *ast_sip_subscription_get_body_type(struct ast_sip_subscription *sub);
629
630 /*!
631  * \since 13.0.0
632  * \brief Get the body subtype used for this subscription
633  */
634 const char *ast_sip_subscription_get_body_subtype(struct ast_sip_subscription *sub);
635
636 #endif /* RES_PJSIP_PUBSUB_H */