[asterisk-commits] mmichelson: branch mmichelson/rls-rlmi r418363 - in /team/mmichelson/rls-rlmi...
SVN commits to the Asterisk project
asterisk-commits at lists.digium.com
Thu Jul 10 16:27:54 CDT 2014
Author: mmichelson
Date: Thu Jul 10 16:27:48 2014
New Revision: 418363
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=418363
Log:
Add doxygen and clear trailing whitespace.
Modified:
team/mmichelson/rls-rlmi/include/asterisk/res_pjsip_pubsub.h
team/mmichelson/rls-rlmi/res/res_pjsip_pubsub.c
Modified: team/mmichelson/rls-rlmi/include/asterisk/res_pjsip_pubsub.h
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/rls-rlmi/include/asterisk/res_pjsip_pubsub.h?view=diff&rev=418363&r1=418362&r2=418363
==============================================================================
--- team/mmichelson/rls-rlmi/include/asterisk/res_pjsip_pubsub.h (original)
+++ team/mmichelson/rls-rlmi/include/asterisk/res_pjsip_pubsub.h Thu Jul 10 16:27:48 2014
@@ -332,10 +332,9 @@
/*!
* \brief Notify a SIP subscription of a state change.
*
- * This will create a NOTIFY body to be sent out for the subscribed resource.
- * On real subscriptions, a NOTIFY request will be generated and sent.
- * On virtual subscriptions, the NOTIFY is saved on the virtual subscription and the
- * parent subscription is alerted.
+ * This tells the pubsub core that a the state of a subscribed resource has changed.
+ * The pubsub core will generate an appropriate NOTIFY request to send to the
+ * subscriber.
*
* \param sub The subscription on which a state change is occurring.
* \param notify_data Event package-specific data used to create the NOTIFY body.
@@ -348,7 +347,7 @@
/*!
* \brief Retrieve the local URI for this subscription
*
- * This is the local URI as determined by the underlying SIP dialog.
+ * This is the local URI of the subscribed resource.
*
* \param sub The subscription
* \param[out] buf The buffer into which to store the URI.
Modified: team/mmichelson/rls-rlmi/res/res_pjsip_pubsub.c
URL: http://svnview.digium.com/svn/asterisk/team/mmichelson/rls-rlmi/res/res_pjsip_pubsub.c?view=diff&rev=418363&r1=418362&r2=418363
==============================================================================
--- team/mmichelson/rls-rlmi/res/res_pjsip_pubsub.c (original)
+++ team/mmichelson/rls-rlmi/res/res_pjsip_pubsub.c Thu Jul 10 16:27:48 2014
@@ -1475,6 +1475,30 @@
return res;
}
+/*!
+ * \param Create a pseudo-random string of a fixed length.
+ *
+ * This function is useful for generating a string whose randomness
+ * does not need to be across all time and space.
+ *
+ * This is currently used for boundaries and Content-ID
+ * headers for multipart bodies. This is used instead of a UUID
+ * for two main reasons:
+ *
+ * 1) Since it is possible to generate many Content-IDs in a
+ * single multipart body, this is quicker than creating UUIDs.
+ * 2) Since multipart bodies tend to be large, using a smaller
+ * random string than a UUID can reduce the size of the generated
+ * bodies.
+ *
+ * This function will write a null byte at the final position
+ * in the buffer (buf[size - 1]). So if you pass in a size of
+ * 10, then this will generate a random 9-character string.
+ *
+ * \param buf Buffer to write random string into.
+ * \param size The size of the buffer.
+ * \return A pointer to buf
+ */
static char *generate_random_string(char *buf, size_t size)
{
int i;
@@ -1487,6 +1511,19 @@
return buf;
}
+/*!
+ * \brief Add a resource XML element to an RLMI body
+ *
+ * Each resource element represents a subscribed resource in the list. This function currently
+ * will unconditionally add an instance element to each created resource element. Instance
+ * elements refer to later parts in the multipart body.
+ *
+ * \param pool PJLIB allocation pool
+ * \param cid Content-ID header of the resource
+ * \param resource_name Name of the resource
+ * \param resource_uri URI of the resource
+ * \param state State of the subscribed resource
+ */
static void add_rlmi_resource(pj_pool_t *pool, pj_xml_node *rlmi, const pjsip_generic_string_hdr *cid,
const char *resource_name, const pjsip_sip_uri *resource_uri, pjsip_evsub_state state)
{
@@ -1498,7 +1535,8 @@
char id[6];
char uri[PJSIP_MAX_URL_SIZE];
- pj_str_t cid_stripped = {
+ /* This creates a string representing the Content-ID without the enclosing < > */
+ const pj_str_t cid_stripped = {
.ptr = cid->hvalue.ptr + 1,
.slen = cid->hvalue.slen - 2,
};
@@ -1513,23 +1551,56 @@
pj_strdup2(pool, &name->content, resource_name);
generate_random_string(id, sizeof(id));
+
ast_sip_presence_xml_create_attr(pool, instance, "id", id);
ast_sip_presence_xml_create_attr(pool, instance, "state",
state == PJSIP_EVSUB_STATE_TERMINATED ? "terminated" : "active");
+
+ /* Use the PJLIB-util XML library directly here since we are using a
+ * pj_str_t
+ */
cid_attr = pj_xml_attr_new(pool, &cid_name, &cid_stripped);
pj_xml_add_attr(instance, cid_attr);
}
+/*!
+ * \brief A multipart body part and meta-information
+ *
+ * When creating a multipart body part, the end result (the
+ * pjsip_multipart_part) is hard to inspect without undoing
+ * a lot of what was done to create it. Therefore, we use this
+ * structure to store meta-information about the body part.
+ *
+ * The main consumer of this is the creator of the RLMI body
+ * part of a multipart resource list body.
+ */
struct body_part {
+ /*! Content-ID header for the body part */
pjsip_generic_string_hdr *cid;
+ /*! Subscribed resource represented in the body part */
const char *resource;
+ /*! URI for the subscribed body part */
pjsip_sip_uri *uri;
+ /*! Subscription state of the resource represented in the body part */
pjsip_evsub_state state;
+ /*! The actual body part that will be present in the multipart body */
pjsip_multipart_part *part;
};
+/*!
+ * \brief Type declaration for container of body part structures
+ */
AST_VECTOR(body_part_list, struct body_part *);
+/*!
+ * \brief Create a Content-ID header
+ *
+ * Content-ID headers are required by RFC2387 for multipart/related
+ * bodies. They serve as identifiers for each part of the multipart body.
+ *
+ * \param pool PJLIB allocation pool
+ * \param sub Subscription to a resource
+ */
static pjsip_generic_string_hdr *generate_content_id_hdr(pj_pool_t *pool,
const struct ast_sip_subscription *sub)
{
@@ -1539,6 +1610,7 @@
size_t alloc_size;
pj_str_t cid_value;
+ /* '<' + '@' + '>' = 3. pj_str_t does not require a null-terminator */
alloc_size = sizeof(id) + pj_strlen(&sub->uri->host) + 3;
cid_value.ptr = pj_pool_alloc(pool, alloc_size);
cid_value.slen = sprintf(cid_value.ptr, "<%s@%.*s>",
@@ -1549,6 +1621,21 @@
return cid;
}
+/*!
+ * \brief Create an RLMI body part for a multipart resource list body
+ *
+ * RLMI (Resource list meta information) is a special body type that lists
+ * the subscribed resources and tells subscribers the number of subscribed
+ * resources and what other body parts are in the multipart body. The
+ * RLMI body also has a version number that a subscriber can use to ensure
+ * that the locally-stored state corresponds to server state.
+ *
+ * \param pool The allocation pool
+ * \param sub The subscription representing the subscribed resource list
+ * \param body_parts A container of body parts that RLMI will refer to
+ * \param full_state Indicates whether this is a full or partial state notification
+ * \return The multipart part representing the RLMI body
+ */
static pjsip_multipart_part *build_rlmi_body(pj_pool_t *pool, struct ast_sip_subscription *sub,
struct body_part_list *body_parts, int full_state)
{
@@ -1598,23 +1685,29 @@
static pjsip_msg_body *generate_notify_body(pj_pool_t *pool, struct ast_sip_subscription *root,
int force_full_state);
-static void free_body_part(struct body_part *part)
-{
- ast_free(part);
-}
-
+/*!
+ * \brief Destroy a list of body parts
+ *
+ * \param parts The container of parts to destroy
+ */
static void free_body_parts(struct body_part_list *parts)
{
int i;
for (i = 0; i < AST_VECTOR_SIZE(parts); ++i) {
struct body_part *part = AST_VECTOR_GET(parts, i);
- free_body_part(part);
+ ast_free(part);
}
AST_VECTOR_FREE(parts);
}
+/*!
+ * \brief Allocate and initialize a body part structure
+ *
+ * \param pool PJLIB allocation pool
+ * \param sub Subscription representing a subscribed resource
+ */
static struct body_part *allocate_body_part(pj_pool_t *pool, const struct ast_sip_subscription *sub)
{
struct body_part *bp;
@@ -1632,6 +1725,14 @@
return bp;
}
+/*!
+ * \brief Create a multipart body part for a subscribed resource
+ *
+ * \param pool PJLIB allocation pool
+ * \param sub The subscription representing a subscribed resource
+ * \param parts A vector of parts to append the created part to.
+ * \param use_full_state Unused locally, but may be passed to other functions
+ */
static void build_body_part(pj_pool_t *pool, struct ast_sip_subscription *sub,
struct body_part_list *parts, int use_full_state)
{
@@ -1646,7 +1747,7 @@
body = generate_notify_body(pool, sub, use_full_state);
if (!body) {
/* Partial state was requested and the resource has not changed state */
- free_body_part(bp);
+ ast_free(bp);
return;
}
@@ -1657,6 +1758,12 @@
AST_VECTOR_APPEND(parts, bp);
}
+/*!
+ * \brief Create and initialize the PJSIP multipart body structure for a resource list subscription
+ *
+ * \param pool
+ * \return The multipart message body
+ */
static pjsip_msg_body *create_multipart_body(pj_pool_t *pool)
{
pjsip_media_type media_type;
@@ -1673,11 +1780,23 @@
pj_strdup2(pool, &media_type_param->value, "\"application/rlmi+xml\"");
pj_list_insert_before(&media_type.param, media_type_param);
-
+
pj_cstr(&pj_boundary, generate_random_string(boundary, sizeof(boundary)));
return pjsip_multipart_create(pool, &media_type, &pj_boundary);
}
+/*!
+ * \brief Create a resource list body for NOTIFY requests
+ *
+ * Resource list bodies are multipart/related bodies. The first part of the multipart body
+ * is an RLMI body that describes the rest of the parts to come. The other parts of the body
+ * convey state of individual subscribed resources.
+ *
+ * \param pool PJLIB allocation pool
+ * \param sub Subscription details from which to generate body
+ * \param force_full_state If true, ignore resource list settings and send a full state notification
+ * \return The generated multipart/related body
+ */
static pjsip_msg_body *generate_list_body(pj_pool_t *pool, struct ast_sip_subscription *sub,
int force_full_state)
{
@@ -1688,13 +1807,13 @@
int use_full_state = force_full_state ? 1 : sub->full_state;
AST_VECTOR_INIT(&body_parts, AST_VECTOR_SIZE(&sub->children));
-
+
multipart = create_multipart_body(pool);
for (i = 0; i < AST_VECTOR_SIZE(&sub->children); ++i) {
build_body_part(pool, AST_VECTOR_GET(&sub->children, i), &body_parts, use_full_state);
}
-
+
rlmi_part = build_rlmi_body(pool, sub, &body_parts, use_full_state);
pjsip_multipart_add_part(pool, multipart, rlmi_part);
@@ -1706,6 +1825,13 @@
return multipart;
}
+/*!
+ * \brief Create the body for a NOTIFY request.
+ *
+ * \param pool The pool used for allocations
+ * \param root The root of the subscription tree
+ * \param force_full_state If true, ignore resource list settings and send a full state notification
+ */
static pjsip_msg_body *generate_notify_body(pj_pool_t *pool, struct ast_sip_subscription *root,
int force_full_state)
{
@@ -1736,6 +1862,9 @@
return body;
}
+/*!
+ * \brief Shortcut method to create a Require: eventlist header
+ */
static pjsip_require_hdr *create_require_eventlist(pj_pool_t *pool)
{
pjsip_require_hdr *require;
@@ -1747,6 +1876,14 @@
return require;
}
+/*!
+ * \brief Send a NOTIFY request to a subscriber
+ *
+ * \param sub_tree The subscription tree representing the subscription
+ * \param force_full_state If true, ignore resource list settings and send full resource list state.
+ * \retval 0 Success
+ * \retval non-zero Failure
+ */
static int send_notify(struct sip_subscription_tree *sub_tree, int force_full_state)
{
pjsip_evsub *evsub = sub_tree->evsub;
@@ -1794,9 +1931,9 @@
static int sched_cb(const void *data)
{
- /* Why the #*(@% does the scheduler give us const data?! */
struct sip_subscription_tree *sub_tree = (struct sip_subscription_tree *) data;
+ /* We don't need to bump the refcount of sub_tree since we bumped it when scheduling this task */
ast_sip_push_task(sub_tree->serializer, serialized_send_notify, sub_tree);
return 0;
}
More information about the asterisk-commits
mailing list