From 5675cfe6c24fce3f1629371191b71806cfd4897c Mon Sep 17 00:00:00 2001 From: bel Date: Fri, 20 Jun 2014 23:32:17 +0200 Subject: [PATCH] Add comments for the C++ wrapper --- include/CivetServer.h | 88 ++++++++++++++++++++++--------------------- src/CivetServer.cpp | 3 +- 2 files changed, 48 insertions(+), 43 deletions(-) diff --git a/include/CivetServer.h b/include/CivetServer.h index b040e84f..80c110c0 100644 --- a/include/CivetServer.h +++ b/include/CivetServer.h @@ -70,7 +70,7 @@ public: /** * CivetServer * - * Basic class for embedded web server. This has a URL mapping built-in. + * Basic class for embedded web server. This has an URL mapping built-in. */ class CivetServer { @@ -128,16 +128,18 @@ public: * * Removes a handler. * - * @param - the exact URL used in addHandler(). + * @param uri - the exact URL used in addHandler(). */ void removeHandler(const std::string &uri); /** * getCookie(struct mg_connection *conn, const std::string &cookieName, std::string &cookieValue) + * + * Puts the cookie value string that matches the cookie name in the cookieValue destinaton string. + * * @param conn - the connection information * @param cookieName - cookie name to get the value from * @param cookieValue - cookie value is returned using thiis reference - * @puts the cookie value string that matches the cookie name in the _cookieValue string. * @returns the size of the cookie value string read. */ static int getCookie(struct mg_connection *conn, const std::string &cookieName, std::string &cookieValue); @@ -155,13 +157,15 @@ public: * * Returns a query paramter contained in the supplied buffer. The * occurance value is a zero-based index of a particular key name. This - * should nto be confused with the index over all of the keys. + * should not be confused with the index over all of the keys. Note that this + * function assumes that parameters are sent as text in http query string + * format, which is the default for web forms. * - * @param data the query string - * @param name the key to search for - * @param the destination string - * @param occurrence the occurrence of the selected name in the query (0 based). - * @return true of key was found + * @param conn - parameters are read from the data sent through this connection + * @param name - the key to search for + * @param dst - the destination string + * @param occurrence - the occurrence of the selected name in the query (0 based). + * @return true if key was found */ static bool getParam(struct mg_connection *conn, const char *name, std::string &dst, size_t occurrence=0); @@ -171,13 +175,13 @@ public: * * Returns a query paramter contained in the supplied buffer. The * occurance value is a zero-based index of a particular key name. This - * should nto be confused with the index over all of the keys. + * should not be confused with the index over all of the keys. * - * @param data the query string - * @param name the key to search for - * @param the destination string - * @param occurrence the occurrence of the selected name in the query (0 based). - * @return true of key was found + * @param data - the query string (text) + * @param name - the key to search for + * @param dst - the destination string + * @param occurrence - the occurrence of the selected name in the query (0 based). + * @return true if key was found */ static bool getParam(const std::string &data, const char *name, std::string &dst, size_t occurrence=0) { @@ -189,14 +193,14 @@ public: * * Returns a query paramter contained in the supplied buffer. The * occurance value is a zero-based index of a particular key name. This - * should nto be confused with the index over all of the keys. + * should not be confused with the index over all of the keys. * - * @param data the query string - * @param length length of the query string - * @param name the key to search for - * @param the destination string - * @param occurrence the occurrence of the selected name in the query (0 based). - * @return true of key was found + * @param data the - query string (text) + * @param data_len - length of the query string + * @param name - the key to search for + * @param dst - the destination string + * @param occurrence - the occurrence of the selected name in the query (0 based). + * @return true if key was found */ static bool getParam(const char *data, size_t data_len, const char *name, std::string &dst, size_t occurrence=0); @@ -205,9 +209,9 @@ public: /** * urlDecode(const std::string &, std::string &, bool) * - * @param src string to be decoded - * @param dst destination string - * @is_form_url_encoded true if form url encoded + * @param src - string to be decoded + * @param dst - destination string + * @param is_form_url_encoded - true if form url encoded * form-url-encoded data differs from URI encoding in a way that it * uses '+' as character for space, see RFC 1866 section 8.2.1 * http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt @@ -219,10 +223,10 @@ public: /** * urlDecode(const char *, size_t, std::string &, bool) * - * @param src buffer to be decoded - * @param src_len length of buffer to be decoded - * @param dst destination string - * @is_form_url_encoded true if form url encoded + * @param src - buffer to be decoded + * @param src_len - length of buffer to be decoded + * @param dst - destination string + * @param is_form_url_encoded - true if form url encoded * form-url-encoded data differs from URI encoding in a way that it * uses '+' as character for space, see RFC 1866 section 8.2.1 * http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt @@ -232,9 +236,9 @@ public: /** * urlDecode(const char *, std::string &, bool) * - * @param src buffer to be decoded (0 terminated) - * @param dst destination string - * @is_form_url_encoded true if form url encoded + * @param src - buffer to be decoded (0 terminated) + * @param dst - destination string + * @param is_form_url_encoded true - if form url encoded * form-url-encoded data differs from URI encoding in a way that it * uses '+' as character for space, see RFC 1866 section 8.2.1 * http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt @@ -244,9 +248,9 @@ public: /** * urlEncode(const std::string &, std::string &, bool) * - * @param src buffer to be encoded - * @param dst destination string - * @append true if string should not be cleared before encoding. + * @param src - buffer to be encoded + * @param dst - destination string + * @param append - true if string should not be cleared before encoding. */ static void urlEncode(const std::string &src, std::string &dst, bool append=false) { urlEncode(src.c_str(), src.length(), dst, append); @@ -255,19 +259,19 @@ public: /** * urlEncode(const char *, size_t, std::string &, bool) * - * @param src buffer to be encoded (0 terminated) - * @param dst destination string - * @append true if string should not be cleared before encoding. + * @param src - buffer to be encoded (0 terminated) + * @param dst - destination string + * @param append - true if string should not be cleared before encoding. */ static void urlEncode(const char *src, std::string &dst, bool append=false); /** * urlEncode(const char *, size_t, std::string &, bool) * - * @param src buffer to be encoded - * @param src_len length of buffer to be decoded - * @param dst destination string - * @append true if string should not be cleared before encoding. + * @param src - buffer to be encoded + * @param src_len - length of buffer to be decoded + * @param dst - destination string + * @param append - true if string should not be cleared before encoding. */ static void urlEncode(const char *src, size_t src_len, std::string &dst, bool append=false); diff --git a/src/CivetServer.cpp b/src/CivetServer.cpp index 3f0ac085..033f5275 100644 --- a/src/CivetServer.cpp +++ b/src/CivetServer.cpp @@ -181,7 +181,8 @@ CivetServer::getParam(struct mg_connection *conn, const char *name, if (con_len_str) { unsigned long con_len = atoi(con_len_str); if (con_len>0) { - // Add one extra character for 0-termination of strings + // Add one extra character: in case the post-data is a text, it is required as 0-termination. + // Do not increment con_len, since the 0 terminating is not part of the content (text or binary). conobj.postData = (char*)malloc(con_len + 1); if (conobj.postData != NULL) { // malloc may fail for huge requests