[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