From 68c054a21ddf6f630e3803de0b25ea97e425c0ad Mon Sep 17 00:00:00 2001 From: m0gg Date: Mon, 11 Dec 2006 08:13:19 +0000 Subject: Documentation fixup --- libcsoap/soap-server.h | 77 ++++++++++++++++++++++++++++++++++++++++---- nanohttp/nanohttp-base64.c | 3 +- nanohttp/nanohttp-client.h | 71 +++++++++++++++++++++++++--------------- nanohttp/nanohttp-common.h | 32 +++++++++--------- nanohttp/nanohttp-request.h | 6 ++-- nanohttp/nanohttp-response.h | 6 ++-- nanohttp/nanohttp-server.h | 36 ++++++++++----------- nanohttp/nanohttp-socket.h | 6 ++-- nanohttp/nanohttp-ssl.c | 4 ++- nanohttp/nanohttp-ssl.h | 11 ++++--- nanohttp/nanohttp-url.h | 5 +-- 11 files changed, 172 insertions(+), 85 deletions(-) diff --git a/libcsoap/soap-server.h b/libcsoap/soap-server.h index 8cad6ff..4a850a8 100644 --- a/libcsoap/soap-server.h +++ b/libcsoap/soap-server.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: soap-server.h,v 1.20 2006/12/10 19:21:06 m0gg Exp $ + * $Id: soap-server.h,v 1.21 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A SOAP client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -28,21 +28,72 @@ * * @mainpage Project overview * - * @section seq_intro Introduction + * @section project_intro_sec Introduction * * cSOAP is a client/server SOAP library implemented in pure C. It comes with - * embedded transport servers for UDP and HTTP (nanohttp). The transferred XML + * embedded transport servers for UDP and HTTP (nanoHTTP). The transferred XML * structures are handled by libxml2. * - * @section seq_features Features + * @section project_features_sec Features * + * - @subpage soap_page * - different transport services - * - @ref nanohttp_page (HTTP including SSL) + * - @subpage nanohttp_page (HTTP including SSL) * - client/server UDP transport service (multicast) * - attachments via MIME * - message based security (XML encryption/signation) * - automatic generation of WS-Inspection * + * @section howto_sec HOWTOs and coding examples + * + * - @ref nanohttp_client_page + * - @ref nanohttp_server_page + * - @ref nanohttp_mime_page + * - @ref csoap_client_page + * - @ref csoap_server_page + * - @ref csoap_mime_page + * + * @section help_sec How to help + * + * The development of cSOAP highly depends on your input! If you are trying + * cSOAP let us know what you think of it (do you miss certain features?). Even + * if you decide not to use it, please let us know why. + * + * @section projects_sec Projects that use cSOAP + * + * @subsection CompLearn (http://complearn.org/) + * + * CompLear is a suite of simple-to-use utilities that you can use to apply + * compression techniques to the process of discovering and learning patterns. + * + * @section downloads_sec Downloads + * + * @subsection Download stable release + * + * A stable release is a tested version of cSOAP. Download this package if you + * want to use it in your productive projects. + * + * Download source code of libsoap-1.1.0.tar.gz: + * http://prdownloads.sourceforge.net/csoap/libsoap-1.1.0.tar.gz?download + * + * @subsection Download latest snapshot (nightly build) + * + * Latest snapshots are build nightly on a detected CVS commit. This is sometimes + * not very stable but in some case are snapshots the better choice then the + * stable version. This can happen if a very important bug was fixed or a new + * feature was introduced. It is recommend to join the mailinglist. + * + * Download latest snapshot (nightly build): + * http://csoap.sourceforge.net/downloads/libsoap-snapshot.tar.gz + * + * @subsection Checkout from CVS + * + * Do you want the latest source codes? You want to contribute a patch? Have you + * found a bug? Or whatever. You should check out csoap from CVS to play the game + * with us csoap developers. + * + * Web CVS access: http://csoap.cvs.sourceforge.net/csoap/libsoap/ + * * @author Ferhat Ayaz * @author Michael Rans * @author Matt Campbell @@ -54,6 +105,19 @@ * @see http://www.libxml.org/ * @see http://www.openssl.org/ * @see http://www.aleksey.com/xmlsec/ + * + */ + +/** @page soap_page + * + * T.B.D. + * + * @section soap_howto_sec HOWTOs and coding examples + * + * - @ref csoap_client_page + * - @ref csoap_server_page + * - @ref csoap_mime_page + * */ /** @page soap_server_page Howto write an SOAP server @@ -149,8 +213,7 @@ * * xmlDocFormatDump(stdout, req->env->root->doc, 1); * - * err = soap_env_new_with_response(req->env, &res->env); - * if (err != H_OK) + * if ((err = soap_env_new_with_response(req->env, &res->env)) != H_OK) * { * printf("soap_env_new_with_response failed (%s)\n", herror_message(err)); * return err; diff --git a/nanohttp/nanohttp-base64.c b/nanohttp/nanohttp-base64.c index 0e887d6..a0f4bec 100644 --- a/nanohttp/nanohttp-base64.c +++ b/nanohttp/nanohttp-base64.c @@ -1,5 +1,5 @@ /****************************************************************** -* $Id: nanohttp-base64.c,v 1.3 2006/11/28 23:45:57 m0gg Exp $ +* $Id: nanohttp-base64.c,v 1.4 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -128,6 +128,7 @@ void base64_decode_string(const unsigned char *instr, unsigned char *outstr) #ifdef BASE64_TEST_CASE_FROM_RFC2617 #include +#include int main(int argc, char **argv) { unsigned char *instr = "QWxhZGRpbjpvcGVuIHNlc2FtZQ=="; diff --git a/nanohttp/nanohttp-client.h b/nanohttp/nanohttp-client.h index b845ac3..9422997 100644 --- a/nanohttp/nanohttp-client.h +++ b/nanohttp/nanohttp-client.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: nanohttp-client.h,v 1.34 2006/12/10 19:21:06 m0gg Exp $ + * $Id: nanohttp-client.h,v 1.35 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -38,21 +38,22 @@ * * @section client_sec Table of contents * - * - Client initialization - * - Connection initialization - * - SSL related functions - * - Setting HTTP headers (optional) - * - Setting an HTTP header with uniq key - * - Setting multiple headers - * - Fetch the network resource - * - @ref get_sec - * - @ref post_sec - * - MIME attachments - * - Print out the result - * - Connection cleanup - * - Client cleanup - * - * @section init_sec Client initialization + * - @ref nanohttp_client_init_sec + * - @ref nanohttp_client_conn_init_sec + * - @ref nanohttp_client_ssl_sec + * - @ref nanohttp_client_header_sec + * - @ref nanohttp_client_header_uniq_sec + * - @ref nanohttp_client_header_mult_sec + * - @ref nanohttp_client_authorization_sec + * - @ref nanohttp_client_invoke_sec + * - @ref nanohttp_client_get_sec + * - @ref nanohttp_client_post_sec + * - @ref nanohttp_client_mime_sec + * - @ref nanohttp_client_result_sec + * - @ref nanohttp_client_conn_cleanup_sec + * - @ref nanohttp_client_cleanup_sec + * + * @section nanohttp_client_init_sec Client initialization * * @code * int main(int argc, char **argv) @@ -75,7 +76,7 @@ * } * @endcode * - * @section conn_sec Connection initialization + * @section nanohttp_client_conn_init_sec Connection initialization * * @code * if (!(conn = httpc_new())) @@ -86,16 +87,22 @@ * } * @endcode * - * @section ssl_sec SSL related functions + * @section nanohttp_client_ssl_sec SSL related functions * * T.B.D. * - * @section header_sec Setting HTTP headers (optional) + * @ref nanohttp_ssl_page + * + * @section nanohttp_client_header_sec Setting HTTP headers (optional) + * + * @subsection nanohttp_client_header_uniq_sec Setting an header with uniq key * * @code * httpc_set_header(conn, "my-key", "my-value"); * @endcode * + * @subsection nanohttp_client_header_mult_sec Setting headers with the same key + * * @code * httpc_add_header(conn, "Cookie", "name1:value1"); * httpc_add_header(conn, "Cookie", "name2:value2"); @@ -104,9 +111,19 @@ * Please see @ref general_header_fields and @ref request_header_fields for more * information. * - * @section fetch_sec Fetch the network resource + * @subsection nanohttp_client_authorization_sec HTTP autorization * - * @subsection get_sec HTTP GET method + * @code + * httpc_set_basic_authorization(conn, "username", "password"); + * @endcode + * + * @code + * httpc_set_basic_proxy_authorization(conn, "username", "password"); + * @endcode + * + * @section nanohttp_client_invoke_sec Fetch the network resource + * + * @subsection nanohttp_client_get_sec HTTP GET method * * @code * if ((status = httpc_get(conn, &result, argv[1])) != H_OK) @@ -118,7 +135,7 @@ * } * @endcode * - * @subsection post_sec HTTP POST method + * @subsection nanohttp_client_post_sec HTTP POST method * * @code * if ((status = httpc_post_begin(conn, argv[1])) != H_OK) @@ -146,11 +163,13 @@ * } * @endcode * - * @section mime_sec MIME attachments + * @section nanohttp_client_mime_sec MIME attachments * * T.B.D. * - * @section output_sec Print out the result + * @ref nanohttp_mime_page + * + * @section nanohttp_client_result_sec Print out the result * * @code * while (http_input_stream_is_read(res->in)) @@ -160,13 +179,13 @@ * } * @endcode * - * @section conn_clean_sec Connection cleanup + * @section nanohttp_client_conn_cleanup_sec Connection cleanup * * @code * hresponse_free(res); * @endcode * - * @section client_clean Client cleanup + * @section nanohttp_client_cleanup_sec Client cleanup * * @code * httpc_free(conn); diff --git a/nanohttp/nanohttp-common.h b/nanohttp/nanohttp-common.h index 052f814..03fe18d 100644 --- a/nanohttp/nanohttp-common.h +++ b/nanohttp/nanohttp-common.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: nanohttp-common.h,v 1.43 2006/12/10 19:21:06 m0gg Exp $ + * $Id: nanohttp-common.h,v 1.44 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003-2004 Ferhat Ayaz @@ -458,13 +458,15 @@ typedef enum _hreq_method * defines the class of response. The last two digits do not have any * categorization role. There are 5 values for the first digit: * - * - 1xx: Informational - Request received, continuing process - * - 2xx: Success - The action was successfully received, understood, and - * accepted - * - 3xx: Redirection - Further action must be taken in order to complete the - * request - * - 4xx: Client Error - The request contains bad syntax or cannot be fulfilled - * - 5xx: Server Error - The server failed to fulfill an apparently valid request + * - @ref status_informational_sec - Request received, continuing process + * - @ref status_success_sec - The action was successfully received, understood, + * and accepted + * - @ref status_redirection_sec - Further action must be taken in order to + * complete the request + * - @ref status_client_error_sec - The request contains bad syntax or cannot be + * fulfilled + * - @ref status_server_error_sec - The server failed to fulfill an apparently + * valid request * * The individual values of the numeric status codes defined for HTTP/1.1, and an * example set of corresponding Reason-Phrase's, are presented below. The reason @@ -484,7 +486,7 @@ typedef enum _hreq_method * since that entity is likely to include human-readable information which will * explain the unusual status. * - * \subsection status_informational_sec Informational 1xx + * @section status_informational_sec Informational 1xx * * This class of status code indicates a provisional response, consisting only * of the Status-Line and optional headers, and is terminated by an empty line. @@ -503,12 +505,12 @@ typedef enum _hreq_method * "Expect: 100-continue" field when it forwards a request, then it need not * forward the corresponding 100 (Continue) response(s).) * - * \subsection status_successful_sec Successful 2xx + * @section status_successful_sec Successful 2xx * * This class of status code indicates that the client's request was * successfully received, understood, and accepted. * - * \subsection status_refirection_sec Redirection 3xx + * @section status_redirection_sec Redirection 3xx * * This class of status code indicates that further action needs to be taken by * the user agent in order to fulfill the request. The action required MAY be @@ -517,7 +519,7 @@ typedef enum _hreq_method * detect infinite redirection loops, since such loops generate network traffic * for each redirection. * - * \subsection status_client_error_sec Client Error 4xx + * @section status_client_error_sec Client Error 4xx * * The 4xx class of status code is intended for cases in which the client seems * to have erred. Except when responding to a HEAD request, the server SHOULD @@ -534,7 +536,7 @@ typedef enum _hreq_method * unacknowledged input buffers before they can be read and interpreted by the * HTTP application. * - * \subsection status_server_error_sec Server Error 5xx + * @section status_server_error_sec Server Error 5xx * * Response status codes beginning with the digit "5" indicate cases in which * the server is aware that it has erred or is incapable of performing the @@ -549,7 +551,7 @@ typedef enum _hreq_method * @see http://www.ietf.org/rfc/rfc2616.txt * */ -/*{*/ +/*@{*/ /** * @@ -1200,7 +1202,7 @@ typedef enum _hreq_method */ #define HTTP_STATUS_505_REASON_PHRASE "HTTP Version not supported" -/*}*/ +/*@}*/ /** * diff --git a/nanohttp/nanohttp-request.h b/nanohttp/nanohttp-request.h index 209ef9a..739c3c9 100755 --- a/nanohttp/nanohttp-request.h +++ b/nanohttp/nanohttp-request.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: nanohttp-request.h,v 1.13 2006/12/10 12:23:45 m0gg Exp $ + * $Id: nanohttp-request.h,v 1.14 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003-2004 Ferhat Ayaz @@ -34,7 +34,7 @@ * @see http://www.ietf.org/rfc/rfc2616.txt * */ -/*{*/ +/*@{*/ /** * @@ -252,7 +252,7 @@ */ #define HEADER_USER_AGENT "User-Agent" -/*}*/ +/*@}*/ #ifdef __NHTTP_INTERNAL struct request_statistics diff --git a/nanohttp/nanohttp-response.h b/nanohttp/nanohttp-response.h index b198128..ce2984b 100755 --- a/nanohttp/nanohttp-response.h +++ b/nanohttp/nanohttp-response.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: nanohttp-response.h,v 1.13 2006/12/10 12:23:46 m0gg Exp $ + * $Id: nanohttp-response.h,v 1.14 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003-2004 Ferhat Ayaz @@ -34,7 +34,7 @@ * @see http://www.ietf.org/rfc/rfc2616.txt * */ -/*{*/ +/*@{*/ /** * @@ -150,7 +150,7 @@ */ #define HEADER_WWW_AUTHENTICATE "WWW-Authenticate" -/*}*/ +/*@}*/ /** * diff --git a/nanohttp/nanohttp-server.h b/nanohttp/nanohttp-server.h index 4205900..eb1f178 100644 --- a/nanohttp/nanohttp-server.h +++ b/nanohttp/nanohttp-server.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: nanohttp-server.h,v 1.30 2006/12/10 19:21:07 m0gg Exp $ + * $Id: nanohttp-server.h,v 1.31 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -38,7 +38,7 @@ * * @page nanohttp_page nanoHTTP * - * \section nanohttp_sec nanoHTTP + * @section nanohttp_sec nanoHTTP * * nanoHTTP is an embedded HTTP implementation. It comes with the following * features: @@ -46,11 +46,11 @@ * - attachments via MIME * - HTTPS support (SSL/TLS) using OpenSSL * - * \section links_sec Howto to the nanoHTTP library + * @section links_sec Howto to the nanoHTTP library * - * - \ref nanohttp_client_page - * - \ref nanohttp_server_page - * - \ref nanohttp_mime_page + * - @ref nanohttp_client_page + * - @ref nanohttp_server_page + * - @ref nanohttp_mime_page * * @author Ferhat Ayaz * @author Michael Rans @@ -66,15 +66,15 @@ /** @page nanohttp_server_page Howto write an HTTP server * - * \section server_sec Table of contents + * @section server_sec Table of contents * - * - \ref init_sec - * - \ref service_sec - * - \ref running_sec - * - \ref cleanup_sec - * - \ref function_sec + * - @ref init_sec + * - @ref service_sec + * - @ref running_sec + * - @ref cleanup_sec + * - @ref function_sec * - * \section init_sec Server initialization + * @section init_sec Server initialization * * @code * int main(int argc, char **argv) @@ -89,7 +89,7 @@ * } * @endcode * - * \section service_sec Service registration + * @section service_sec Service registration * * @code * if ((status = httpd_register("/", root_service)) != H_OK) @@ -131,7 +131,7 @@ * } * @endcode * - * \section running_sec Running the server + * @section running_sec Running the server * * @code * if ((status = httpd_run()) != H_OK) @@ -143,7 +143,7 @@ * } * @endcode * - * \section cleanup_sec Server cleanup + * @section cleanup_sec Server cleanup * * @code * httpd_destroy(); @@ -152,7 +152,7 @@ * } * @endcode * - * \section function_seq Sample service function + * @section function_seq Sample service function * * @code * static void headers_service(httpd_conn_t *conn, struct hrequest_t *req) @@ -191,7 +191,7 @@ /** * - * nanohttp command line flags + * nanoHTTP command line flags * */ #define NHTTPD_ARG_PORT "-NHTTPport" diff --git a/nanohttp/nanohttp-socket.h b/nanohttp/nanohttp-socket.h index 36f2c09..115defe 100644 --- a/nanohttp/nanohttp-socket.h +++ b/nanohttp/nanohttp-socket.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: nanohttp-socket.h,v 1.37 2006/12/10 19:21:07 m0gg Exp $ + * $Id: nanohttp-socket.h,v 1.38 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003 Ferhat Ayaz @@ -27,7 +27,7 @@ /** @defgroup socket_errors Socket errors * */ -/*{*/ +/*@{*/ /** * @@ -46,6 +46,8 @@ #define HSOCKET_ERROR_NOT_INITIALIZED (HSOCKET_ERROR + 9) #define HSOCKET_ERROR_IOCTL (HSOCKET_ERROR + 10) +/*@}*/ + /** * * @todo move the next two items to nanohttp-ssl.h diff --git a/nanohttp/nanohttp-ssl.c b/nanohttp/nanohttp-ssl.c index 46b90f1..4d3cb2c 100644 --- a/nanohttp/nanohttp-ssl.c +++ b/nanohttp/nanohttp-ssl.c @@ -1,5 +1,5 @@ /****************************************************************** -* $Id: nanohttp-ssl.c,v 1.36 2006/12/06 11:27:21 m0gg Exp $ +* $Id: nanohttp-ssl.c,v 1.37 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2001-2005 Rochester Institute of Technology @@ -84,6 +84,8 @@ #include "nanohttp-ssl.h" +#define CERT_SUBJECT 1 + static char *_hssl_certificate = NULL; static char *_hssl_certpass = NULL; static char *_hssl_ca_list = NULL; diff --git a/nanohttp/nanohttp-ssl.h b/nanohttp/nanohttp-ssl.h index cc8b7f7..aa5c781 100644 --- a/nanohttp/nanohttp-ssl.h +++ b/nanohttp/nanohttp-ssl.h @@ -1,5 +1,5 @@ /****************************************************************** -* $Id: nanohttp-ssl.h,v 1.25 2006/12/03 17:30:58 m0gg Exp $ +* $Id: nanohttp-ssl.h,v 1.26 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2001-2005 Rochester Institute of Technology @@ -31,12 +31,13 @@ */ #define NHTTPD_ARG_HTTPS "-NHTTPS" - /** * - * SSL Errors + * @defgroup ssl_errors_group SSL Errors * */ +/*@{*/ + #define HSSL_ERROR 1700 #define HSSL_ERROR_CA_LIST (HSSL_ERROR + 10) #define HSSL_ERROR_CONTEXT (HSSL_ERROR + 20) @@ -46,6 +47,8 @@ #define HSSL_ERROR_SERVER (HSSL_ERROR + 60) #define HSSL_ERROR_CONNECT (HSSL_ERROR + 70) +/*@}*/ + #ifdef __cplusplus extern "C" { #endif @@ -133,8 +136,6 @@ extern herror_t hssl_server_ssl(struct hsocket_t * sock); */ extern void hssl_cleanup(struct hsocket_t * sock); -#define CERT_SUBJECT 1 - /** * * Quick function for verifying a portion of the cert nid is any NID_ defined diff --git a/nanohttp/nanohttp-url.h b/nanohttp/nanohttp-url.h index 61342f5..6e72749 100644 --- a/nanohttp/nanohttp-url.h +++ b/nanohttp/nanohttp-url.h @@ -1,5 +1,5 @@ /****************************************************************** - * $Id: nanohttp-url.h,v 1.2 2006/12/10 19:21:07 m0gg Exp $ + * $Id: nanohttp-url.h,v 1.3 2006/12/11 08:13:19 m0gg Exp $ * * CSOAP Project: A http client/server library in C * Copyright (C) 2003-2004 Ferhat Ayaz @@ -48,9 +48,6 @@ typedef enum _hprotocol PROTOCOL_HTTPS } hprotocol_t; -#define URL_MAX_HOST_SIZE 120 -#define URL_MAX_CONTEXT_SIZE 1024 - /** * * The URL object. A representation of an URL like: -- cgit v1.1-32-gdbae