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 */