[asterisk-commits] dlee: branch dlee/stasis-http r379072 - /team/dlee/stasis-http/include/asterisk/

[SVN commits to the Asterisk project]

Author: dlee
Date: Mon Jan 14 15:54:08 2013
New Revision: 379072

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=379072
Log:
Doc comments

Modified:
    team/dlee/stasis-http/include/asterisk/stasis_http.h

Modified: team/dlee/stasis-http/include/asterisk/stasis_http.h
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-http/include/asterisk/stasis_http.h?view=diff&rev=379072&r1=379071&r2=379072
==============================================================================
--- team/dlee/stasis-http/include/asterisk/stasis_http.h (original)
+++ team/dlee/stasis-http/include/asterisk/stasis_http.h Mon Jan 14 15:54:08 2013
@@ -1,7 +1,7 @@
 /*
  * Asterisk -- An open source telephony toolkit.
  *
- * Copyright (C) 2012, Digium, Inc.
+ * Copyright (C) 2012 - 2013, Digium, Inc.
  *
  * David M. Lee, II <dlee at digium.com>
  *
@@ -23,31 +23,63 @@
  *
  * \brief Stasis RESTful API hooks.
  *
+ * This header file is used mostly as glue code between generated declarations
+ * and res_stasis_http.c.
+ *
  * \author David M. Lee, II <dlee at digium.com>
  */
 
 #include "asterisk/http.h"
 #include "asterisk/json.h"
 
-struct stasis_http_response {
-	struct ast_json *message;
-	int response_code;
-	const char *response_text;
-};
+struct stasis_http_response;
 
+/*!
+ * \brief Callback type for RESTful method handlers.
+ * \param get_params GET parameters from the HTTP request.
+ * \param path_vars Path variables from any wildcard path segments.
+ * \param headers HTTP headers from the HTTP requiest.
+ * \param[out] response The RESTful response.
+ */
 typedef void (*stasis_rest_callback)(struct ast_variable *get_params,
 				     struct ast_variable *path_vars,
 				     struct ast_variable *headers,
 				     struct stasis_http_response *response);
 
+/*!
+ * \brief Handler for a single RESTful path segment.
+ */
 struct stasis_rest_handlers {
+	/*! Path segement to handle */
 	const char *path_segment;
+	/*! If true (non-zero), path_segment is a wildcard, and will match all values.
+	 *
+	 * Value of the segement will be passed into the \a path_vars parameter of the callback.
+	 */
 	int is_wildcard;
+	/*! Callbacks for all handled HTTP methods. */
 	stasis_rest_callback callbacks[AST_HTTP_MAX_METHOD];
+	/*! Number of children in the children array */
 	size_t num_children;
+	/*! Handlers for sub-paths */
 	struct stasis_rest_handlers *children[];
 };
 
+/*!
+ * Response type for RESTful requests
+ */
+struct stasis_http_response {
+	/*! Response message */
+	struct ast_json *message;
+	/*! HTTP response code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html */
+	int response_code;
+	/*! Corresponding text for the response code */
+	const char *response_text; // Shouldn't http.c handle this?
+};
+
+/*!
+ * Handler for the root RESTful resource.
+ */
 struct stasis_rest_handlers *stasis_root_handler(void);
 
 #endif /* _ASTERISK_STASIS_HTTP_H */