nth: updated documentation. fixed problem in assert().

darcs-hash:20061113144623-65a35-eda62ae987427b43dec26ce60604a5a96cb993bc.gz

libsofia-sip-ua/nth/nth_server.c

@@ -257,6 +257,7 @@ void nth_site_request(server_t *srv,
  * HTTPTAG_SERVER(), and HTTPTAG_SERVER_STR(). All the tags are passed to
  * tport_tcreate() and tport_tbind(), too.
  *
+ * @since Support for multiple sites was added to @VERSION_1_12_4
  */
 nth_site_t *nth_site_create(nth_site_t *parent,  
 			    nth_request_f *callback,
@@ -1109,7 +1110,7 @@ static void nth_authentication_result(void *ai0, auth_status_t *as)
   int status;
 
   if (as->as_status != 0) {
-    assert(retval >= 300);
+    assert(as->as_status >= 300);
     nth_request_treply(req, status = as->as_status, as->as_phrase, 
 		       HTTPTAG_HEADER((http_header_t *)as->as_response), 
 		       TAG_END());
@@ -1157,11 +1158,32 @@ void nth_request_destroy(nth_request_t *req)
   su_free(req->req_server->srv_home, req);
 }
 
+/** Return request authentication status.
+ *
+ * @param req pointer to HTTP request object
+ * 
+ * @retval Status code
+ *
+ * @since New in @VERSION_1_12_4
+ */
 int nth_request_status(nth_request_t const *req)
 {
   return req ? req->req_status : 400;
 }
 
+/** Return request authentication status.
+ *
+ * @param req pointer to HTTP request object
+ * 
+ * @retval Pointer to authentication status struct
+ *
+ * @note The authentication status struct is freed when the #nth_request_t
+ * object is destroyed.
+ *
+ * @since New in @VERSION_1_12_4
+ *
+ * @sa AUTH
+ */
 auth_status_t *nth_request_auth(nth_request_t const *req)
 {
   return req ? req->req_as : NULL;

libsofia-sip-ua/nth/nth_tag.c

@@ -65,4 +65,18 @@ tag_typedef_t nthtag_authentication = PTRTAG_TYPEDEF(authentication);
 /* Server */
 tag_typedef_t nthtag_root = PTRTAG_TYPEDEF(root);
 tag_typedef_t nthtag_strict_host = BOOLTAG_TYPEDEF(scrict_host);
+
+/**@def NTHTAG_AUTH_MODULE()
+ *
+ * Pointer to authentication module.
+ *
+ * A site requires authentication from the clients if passed an
+ * authentication module pointer with NTHTAG_AUTH_MODULE(). Incoming client
+ * request is challenged with 401, upon successful authentication the
+ * authenticated username is stored in the #auth_status_t structure
+ * associated with the #nth_request_t object. It is up to application to
+ * authorize the user.
+ *
+ * @sa nth_site_create(), nth_site_set_params(), nth_request_auth().
+ */
 tag_typedef_t nthtag_auth_module = PTRTAG_TYPEDEF(auth_module);