2 * Asterisk -- An open source telephony toolkit.
4 * Copyright (C) 2013, Digium, Inc.
6 * Mark Michelson <mmichelson@digium.com>
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.
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.
19 #ifndef _RES_PJSIP_PUBSUB_H
20 #define _RES_PJSIP_PUBSUB_H
22 #include "asterisk/linkedlists.h"
24 /* Forward declarations */
28 struct ast_sip_endpoint;
30 struct ast_datastore_info;
33 * \brief Opaque structure representing a publication
35 struct ast_sip_publication;
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,
47 * \brief Callbacks that publication handlers will define
49 struct ast_sip_publish_handler {
50 /*! \brief The name of the event this handler deals with */
51 const char *event_name;
53 /*! \brief Publications */
54 struct ao2_container *publications;
57 * \brief Called when a PUBLISH to establish a new publication arrives.
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
63 int (*new_publication)(struct ast_sip_endpoint *endpoint, const char *resource);
65 * \brief Called when a publication has reached its expiration.
67 void (*publish_expire)(struct ast_sip_publication *pub);
69 * \brief Published resource has changed states.
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.
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
80 * AST_SIP_PUBLISH_STATE_ACTIVE is used when a publication that modifies state
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
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;
93 * \brief Given a publication, get the associated endpoint
95 * \param pub The publication
96 * \retval NULL Failure
97 * \retval non-NULL The associated endpoint
99 struct ast_sip_endpoint *ast_sip_publication_get_endpoint(struct ast_sip_publication *pub);
102 * \brief Register a publish handler
104 * \retval 0 Handler was registered successfully
105 * \retval non-zero Handler was not registered successfully
107 int ast_sip_register_publish_handler(struct ast_sip_publish_handler *handler);
110 * \brief Unregister a publish handler
112 void ast_sip_unregister_publish_handler(struct ast_sip_publish_handler *handler);
115 * \brief Add a datastore to a SIP publication
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.
120 * \param publication The publication to add the datastore to
121 * \param datastore The datastore to be added to the subscription
125 int ast_sip_publication_add_datastore(struct ast_sip_publication *publication, struct ast_datastore *datastore);
128 * \brief Retrieve a publication datastore
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().
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
138 struct ast_datastore *ast_sip_publication_get_datastore(struct ast_sip_publication *publication, const char *name);
141 * \brief Remove a publication datastore from the publication
143 * This operation may cause the datastore's free() callback to be called if the reference
144 * count reaches zero.
146 * \param publication The publication to remove the datastore from
147 * \param name The name of the datastore to remove
149 void ast_sip_publication_remove_datastore(struct ast_sip_publication *publication, const char *name);
152 * \brief Opaque structure representing an RFC 3265 SIP subscription
154 struct ast_sip_subscription;
157 * \brief Role for the subscription that is being created
159 enum ast_sip_subscription_role {
160 /* Sending SUBSCRIBEs, receiving NOTIFYs */
162 /* Sending NOTIFYs, receiving SUBSCRIBEs */
167 * \brief Data for responses to SUBSCRIBEs and NOTIFIEs
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.
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.
177 struct ast_sip_subscription_response_data {
178 /*! Status code of the response */
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;
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
200 struct ast_sip_notifier {
202 * \brief Default body type defined for the event package this notifier handles.
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.
209 const char *default_accept;
211 * \brief Called when a SUBSCRIBE arrives attempting to establish a new subscription.
213 * The notifier is expected to return the response that should be sent to the
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.
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.
224 int (*new_subscribe)(struct ast_sip_endpoint *endpoint, const char *resource);
226 * \brief The subscription is in need of a NOTIFY request.
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.
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
237 * \param sub The subscription to send the NOTIFY on.
238 * \param reason The reason why the NOTIFY is being sent.
242 int (*notify_required)(struct ast_sip_subscription *sub, enum ast_sip_subscription_notify_reason reason);
245 struct ast_sip_subscriber {
247 * \brief A NOTIFY has been received.
249 * The body of the NOTIFY is provided so that it may be parsed and appropriate
250 * internal state change may be generated.
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.
255 * \param sub The subscription on which the NOTIFY arrived
256 * \param body The body of the NOTIFY
257 * \param state The subscription state
259 void (*state_change)(struct ast_sip_subscription *sub, pjsip_msg_body *body, enum pjsip_evsub_state state);
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];
268 * \brief Called when a subscription is to be destroyed
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.
274 void (*subscription_shutdown)(struct ast_sip_subscription *subscription);
276 * \brief Converts the subscriber to AMI
278 * \param sub The subscription
279 * \param buf The string to write AMI data
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;
290 * \brief Create a new ast_sip_subscription structure
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.
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.
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);
304 * \brief Get the endpoint that is associated with this subscription
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.
309 * \retval NULL Could not get endpoint
310 * \retval non-NULL The endpoint
312 struct ast_sip_endpoint *ast_sip_subscription_get_endpoint(struct ast_sip_subscription *sub);
315 * \brief Get the serializer for the subscription
317 * Tasks that originate outside of a SIP servant thread should get the serializer
318 * and push the task to the serializer.
320 * \param sub The subscription
321 * \retval NULL Failure
322 * \retval non-NULL The subscription's serializer
324 struct ast_taskprocessor *ast_sip_subscription_get_serializer(struct ast_sip_subscription *sub);
327 * \brief Notify a SIP subscription of a state change.
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.
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.
338 * \retval non-zero Failure
340 int ast_sip_subscription_notify(struct ast_sip_subscription *sub, void *notify_data, int terminate);
343 * \brief Retrieve the local URI for this subscription
345 * This is the local URI as determined by the underlying SIP dialog.
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.
351 void ast_sip_subscription_get_local_uri(struct ast_sip_subscription *sub, char *buf, size_t size);
354 * \brief Retrive the remote URI for this subscription
356 * This is the remote URI as determined by the underlying SIP dialog.
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.
362 void ast_sip_subscription_get_remote_uri(struct ast_sip_subscription *sub, char *buf, size_t size);
365 * \brief Get the name of the subscribed resource.
367 const char *ast_sip_subscription_get_resource_name(struct ast_sip_subscription *sub);
370 * \brief Get a header value for a subscription.
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.
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.
381 void *ast_sip_subscription_get_header(const struct ast_sip_subscription *sub, const char *header);
384 * \brief Send a request created via a PJSIP evsub method
386 * Callers of this function should take care to do so within a SIP servant
389 * \param sub The subscription on which to send the request
390 * \param tdata The request to send
392 * \retval non-zero Failure
394 int ast_sip_subscription_send_request(struct ast_sip_subscription *sub, pjsip_tx_data *tdata);
397 * \brief Alternative for ast_datastore_alloc()
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
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.
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
412 struct ast_datastore *ast_sip_subscription_alloc_datastore(const struct ast_datastore_info *info, const char *uid);
415 * \brief Add a datastore to a SIP subscription
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.
420 * \param subscription The ssubscription to add the datastore to
421 * \param datastore The datastore to be added to the subscription
425 int ast_sip_subscription_add_datastore(struct ast_sip_subscription *subscription, struct ast_datastore *datastore);
428 * \brief Retrieve a subscription datastore
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().
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
438 struct ast_datastore *ast_sip_subscription_get_datastore(struct ast_sip_subscription *subscription, const char *name);
441 * \brief Remove a subscription datastore from the subscription
443 * This operation may cause the datastore's free() callback to be called if the reference
444 * count reaches zero.
446 * \param subscription The subscription to remove the datastore from
447 * \param name The name of the datastore to remove
449 void ast_sip_subscription_remove_datastore(struct ast_sip_subscription *subscription, const char *name);
452 * \brief Register a subscription handler
454 * \retval 0 Handler was registered successfully
455 * \retval non-zero Handler was not registered successfully
457 int ast_sip_register_subscription_handler(struct ast_sip_subscription_handler *handler);
460 * \brief Unregister a subscription handler
462 void ast_sip_unregister_subscription_handler(struct ast_sip_subscription_handler *handler);
465 * \brief Pubsub body generator
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.
471 struct ast_sip_pubsub_body_generator {
473 * \brief Content type
474 * In "plain/text", "plain" is the type
478 * \brief Content subtype
479 * In "plain/text", "text" is the subtype
483 * \brief allocate body structure.
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
491 * \param data The subscription data provided by the event handler
492 * \retval non-NULL The allocated body
493 * \retval NULL Failure
495 void *(*allocate_body)(void *data);
497 * \brief Add content to the body of a SIP request
499 * The body of the request has already been allocated by the body generator's
500 * allocate_body callback.
502 * \param body The body of the SIP request. The type is determined by the
504 * \param data The subscription data used to populate the body. The type is
505 * determined by the content type.
507 int (*generate_body_content)(void *body, void *data);
509 * \brief Convert the body to a string.
511 * \param body The request body.
512 * \param str The converted string form of the request body
514 void (*to_string)(void *body, struct ast_str **str);
516 * \brief Deallocate resources created for the body
518 * Optional callback to destroy resources allocated for the
521 * \param body Body to be destroyed
523 void (*destroy_body)(void *body);
524 AST_LIST_ENTRY(ast_sip_pubsub_body_generator) list;
528 * \brief Body supplement
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.
534 struct ast_sip_pubsub_body_supplement {
536 * \brief Content type
537 * In "plain/text", "plain" is the type
541 * \brief Content subtype
542 * In "plain/text", "text" is the subtype
546 * \brief Add additional content to a SIP request body.
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.
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.
557 int (*supplement_body)(void *body, void *data);
558 AST_LIST_ENTRY(ast_sip_pubsub_body_supplement) list;
563 * \brief Generate body content for a PUBLISH or NOTIFY
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
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
575 * \retval non-zero Failure
577 int ast_sip_pubsub_generate_body_content(const char *content_type,
578 const char *content_subtype, void *data, struct ast_str **str);
582 * \brief Register a body generator with the pubsub core.
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.
588 * \param generator Body generator to register
592 int ast_sip_pubsub_register_body_generator(struct ast_sip_pubsub_body_generator *generator);
596 * \brief Unregister a body generator with the pubsub core.
598 * \param generator Body generator to unregister
600 void ast_sip_pubsub_unregister_body_generator(struct ast_sip_pubsub_body_generator *generator);
604 * \brief Register a body generator with the pubsub core.
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.
610 * \param generator Body generator to register
614 int ast_sip_pubsub_register_body_supplement(struct ast_sip_pubsub_body_supplement *supplement);
618 * \brief Unregister a body generator with the pubsub core.
620 * \param generator Body generator to unregister
622 void ast_sip_pubsub_unregister_body_supplement(struct ast_sip_pubsub_body_supplement *supplement);
626 * \brief Get the body type used for this subscription
628 const char *ast_sip_subscription_get_body_type(struct ast_sip_subscription *sub);
632 * \brief Get the body subtype used for this subscription
634 const char *ast_sip_subscription_get_body_subtype(struct ast_sip_subscription *sub);
636 #endif /* RES_PJSIP_PUBSUB_H */