From 7f4bac9727922bedde4b882d2a760ff078fd8c3f Mon Sep 17 00:00:00 2001 From: Marcelo Roberto Jimenez Date: Tue, 10 Jun 2008 03:23:08 +0000 Subject: [PATCH] Doxygen. git-svn-id: https://pupnp.svn.sourceforge.net/svnroot/pupnp/trunk@431 119443c7-1b9e-41f8-b6fc-b9c35fce742c --- Doxyfile | 2 +- threadutil/src/ThreadPool.c | 76 ++- upnp/inc/UpnpGlobal.h | 3 +- upnp/inc/upnptools.h | 3 +- upnp/sample/common/sample_util.h | 12 +- upnp/sample/tvctrlpt/upnp_tv_ctrlpt.c | 11 +- upnp/src/api/upnptools.c | 11 +- upnp/src/genlib/net/uri/uri.c | 791 ++++++++--------------- upnp/src/inc/client_table.h | 284 ++++++--- upnp/src/inc/uri.h | 866 ++++++++++++++------------ 10 files changed, 982 insertions(+), 1077 deletions(-) diff --git a/Doxyfile b/Doxyfile index 064b2b0..d334ad3 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1029,7 +1029,7 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = DEBUG INCLUDE_DEVICE_APIS INCLUDE_CLIENT_APIS EXCLUDE_GENA=0 EXCLUDE_DOM=0 +PREDEFINED = DEBUG UPNP_HAVE_TOOLS INCLUDE_DEVICE_APIS INCLUDE_CLIENT_APIS EXCLUDE_GENA=0 EXCLUDE_DOM=0 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/threadutil/src/ThreadPool.c b/threadutil/src/ThreadPool.c index 2a9a0a7..cc9ae53 100644 --- a/threadutil/src/ThreadPool.c +++ b/threadutil/src/ThreadPool.c @@ -1,41 +1,51 @@ -/////////////////////////////////////////////////////////////////////////// -// -// Copyright (c) 2000-2003 Intel Corporation -// All rights reserved. -// -// Redistribution and use in source and binary forms, with or without -// modification, are permitted provided that the following conditions are met: -// -// * Redistributions of source code must retain the above copyright notice, -// this list of conditions and the following disclaimer. -// * Redistributions in binary form must reproduce the above copyright notice, -// this list of conditions and the following disclaimer in the documentation -// and/or other materials provided with the distribution. -// * Neither name of Intel Corporation nor the names of its contributors -// may be used to endorse or promote products derived from this software -// without specific prior written permission. -// -// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR -// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, -// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, -// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR -// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY -// OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING -// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -// -/////////////////////////////////////////////////////////////////////////// +/******************************************************************************* + * + * Copyright (c) 2000-2003 Intel Corporation + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * - Redistributions of source code must retain the above copyright notice, + * this list of conditions and the following disclaimer. + * - Redistributions in binary form must reproduce the above copyright notice, + * this list of conditions and the following disclaimer in the documentation + * and/or other materials provided with the distribution. + * - Neither name of Intel Corporation nor the names of its contributors + * may be used to endorse or promote products derived from this software + * without specific prior written permission. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR + * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, + * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, + * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR + * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY + * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING + * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + ******************************************************************************/ + + +/*! + * \file + */ + #include "ThreadPool.h" + + #include "FreeList.h" + + #include #include - #include + /**************************************************************************** * Function: DiffMillis * @@ -1506,6 +1516,7 @@ int TPAttrSetMaxJobsTotal( ThreadPoolAttr *attr, int maxJobsTotal ) return 0; } + #ifdef STATS void ThreadPoolPrintStats(ThreadPoolStats *stats) { @@ -1535,6 +1546,7 @@ void ThreadPoolPrintStats(ThreadPoolStats *stats) } #endif /* STATS */ + /**************************************************************************** * Function: ThreadPoolGetStats * @@ -1597,6 +1609,7 @@ int ThreadPoolGetStats( ThreadPool *tp, ThreadPoolStats *stats ) #endif /* STATS */ + #ifdef WIN32 #if defined(_MSC_VER) || defined(_MSC_EXTENSIONS) #define DELTA_EPOCH_IN_MICROSECS 11644473600000000Ui64 @@ -1639,3 +1652,4 @@ int gettimeofday(struct timeval *tv, struct timezone *tz) return 0; } #endif /* WIN32 */ + diff --git a/upnp/inc/UpnpGlobal.h b/upnp/inc/UpnpGlobal.h index 20934a7..f08b86b 100644 --- a/upnp/inc/UpnpGlobal.h +++ b/upnp/inc/UpnpGlobal.h @@ -7,8 +7,7 @@ /*! * \file * - * \brief The purpose of this file is to define constants that for some reason - * might not be defined on every system. + * \brief Defines constants that for some reason are not defined on some systems. */ diff --git a/upnp/inc/upnptools.h b/upnp/inc/upnptools.h index 942ad44..c28c157 100644 --- a/upnp/inc/upnptools.h +++ b/upnp/inc/upnptools.h @@ -49,7 +49,8 @@ */ -#include "upnp.h" +#include "ixml.h" /* for IXML_Document */ + /* Function declarations only if tools compiled into the library */ #if UPNP_HAVE_TOOLS diff --git a/upnp/sample/common/sample_util.h b/upnp/sample/common/sample_util.h index 302327a..649b50c 100644 --- a/upnp/sample/common/sample_util.h +++ b/upnp/sample/common/sample_util.h @@ -39,15 +39,17 @@ extern "C" { #endif /* __cplusplus */ -#include -#include - #include "ithread.h" -#include "ixml.h" +#include "ixml.h" /* for IXML_Document, IXML_Element */ +#include "upnp.h" /* for Upnp_EventType */ #include "upnptools.h" -// mutex to control displaying of events +#include +#include + + +/* mutex to control displaying of events */ extern ithread_mutex_t display_mutex; diff --git a/upnp/sample/tvctrlpt/upnp_tv_ctrlpt.c b/upnp/sample/tvctrlpt/upnp_tv_ctrlpt.c index e62beba..84ab52c 100644 --- a/upnp/sample/tvctrlpt/upnp_tv_ctrlpt.c +++ b/upnp/sample/tvctrlpt/upnp_tv_ctrlpt.c @@ -33,7 +33,10 @@ #include "upnp_tv_ctrlpt.h" -/* +#include "upnp.h" + + +/*! Mutex for protecting the global device list in a multi-threaded, asynchronous environment. All functions should lock this mutex before reading @@ -50,7 +53,7 @@ char *TvServiceType[] = { }; char *TvServiceName[] = { "Control", "Picture" }; -/* +/*! Global arrays for storing variable names and counts for TvControl and TvPicture services */ @@ -61,12 +64,12 @@ char *TvVarName[TV_SERVICE_SERVCOUNT][TV_MAXVARS] = { char TvVarCount[TV_SERVICE_SERVCOUNT] = { TV_CONTROL_VARCOUNT, TV_PICTURE_VARCOUNT }; -/* +/*! Timeout to request during subscriptions */ int default_timeout = 1801; -/* +/*! The first node in the global device list, or NULL if empty */ struct TvDeviceNode *GlobalDeviceList = NULL; diff --git a/upnp/src/api/upnptools.c b/upnp/src/api/upnptools.c index d0a3411..2311140 100644 --- a/upnp/src/api/upnptools.c +++ b/upnp/src/api/upnptools.c @@ -41,14 +41,17 @@ #if EXCLUDE_DOM == 0 +#include "upnp.h" +#include "upnptools.h" + + +#include "uri.h" + + #include #include -#include "upnptools.h" -#include "uri.h" - - /*! Maximum action header buffer length. */ #define HEADER_LENGTH 2000 diff --git a/upnp/src/genlib/net/uri/uri.c b/upnp/src/genlib/net/uri/uri.c index 9cec794..dbf2fac 100644 --- a/upnp/src/genlib/net/uri/uri.c +++ b/upnp/src/genlib/net/uri/uri.c @@ -30,9 +30,11 @@ ******************************************************************************/ -/******************************************************************************* - * Purpose: This file contains functions for uri, url parsing utility. - ******************************************************************************/ +/*! + * \file + * + * \brief Contains functions for uri, url parsing utility. + */ #ifdef __FreeBSD__ @@ -44,237 +46,169 @@ #include "config.h" + + #include "uri.h" + + #include "upnpapi.h" -/************************************************************************ -* Function : is_reserved -* -* Parameters : -* char in ; char to be matched for RESERVED characters -* -* Description : Returns a 1 if a char is a RESERVED char as defined in -* http://www.ietf.org/rfc/rfc2396.txt RFC explaining URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_reserved( char in ) +/*! + * \brief Returns a 1 if a char is a RESERVED char as defined in + * http://www.ietf.org/rfc/rfc2396.txt RFC explaining URIs). + * + * \return 1 if char is a RESERVED char. + */ +static int is_reserved( + /*! [in] Char to be matched for RESERVED characters. */ + char in) { - if( strchr( RESERVED, in ) ) - return 1; - else - return 0; -} - -/************************************************************************ -* Function : is_mark -* -* Parameters : -* char in ; character to be matched for MARKED characters -* -* Description : Returns a 1 if a char is a MARK char as defined in -* http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_mark( char in ) -{ - if( strchr( MARK, in ) ) - return 1; - else - return 0; -} - -/************************************************************************ -* Function : is_unreserved -* -* Parameters : -* char in ; character to be matched for UNRESERVED characters -* -* Description : Returns a 1 if a char is an unreserved char as defined in -* http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_unreserved( char in ) -{ - if( isalnum( in ) || ( is_mark( in ) ) ) - return 1; - else - return 0; -} - -/************************************************************************ -* Function : is_escaped -* -* Parameters : -* char * in ; character to be matched for ESCAPED characters -* -* Description : Returns a 1 if a char[3] sequence is escaped as defined -* in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* size of array is NOT checked (MUST be checked by caller) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -is_escaped( const char *in ) -{ - - if( ( in[0] == '%' ) && ( isxdigit( in[1] ) ) && isxdigit( in[2] ) ) { - - return 1; - } else - return 0; -} - -/************************************************************************ -* Function : replace_escaped -* -* Parameters : -* char * in ; string of characters -* int index ; index at which to start checking the characters -* int *max ; -* -* Description : Replaces an escaped sequence with its unescaped version -* as in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* Size of array is NOT checked (MUST be checked by caller) -* -* Return : int ; -* -* Note : This function modifies the string. If the sequence is an -* escaped sequence it is replaced, the other characters in the -* string are shifted over, and NULL characters are placed at the -* end of the string. -************************************************************************/ -int -replace_escaped( char *in, - int index, - size_t *max ) -{ - int tempInt = 0; - char tempChar = 0; - int i = 0; - int j = 0; - - if( ( in[index] == '%' ) && ( isxdigit( in[index + 1] ) ) - && isxdigit( in[index + 2] ) ) { - //Note the "%2x", makes sure that we convert a maximum of two - //characters. - if( sscanf( &in[index + 1], "%2x", &tempInt ) != 1 ) - return 0; - - tempChar = ( char )tempInt; - - for( i = index + 3, j = index; j < ( *max ); i++, j++ ) { - in[j] = tempChar; - if( i < ( *max ) ) - tempChar = in[i]; - else - tempChar = 0; - } - ( *max ) -= 2; - return 1; - } else - return 0; -} - -/************************************************************************ -* Function : parse_uric -* -* Parameters : -* char *in ; string of characters -* int max ; maximum limit -* token *out ; token object where the string of characters is -* copied -* -* Description : Parses a string of uric characters starting at in[0] -* as defined in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining -* URIs) -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_uric( const char *in, - int max, - token * out ) -{ - int i = 0; - - while( ( i < max ) - && ( ( is_unreserved( in[i] ) ) || ( is_reserved( in[i] ) ) - || ( ( i + 2 < max ) && ( is_escaped( &in[i] ) ) ) ) ) { - i++; - } - - out->size = i; - out->buff = in; - return i; + if (strchr(RESERVED, in)) { + return 1; + } else { + return 0; + } } -/************************************************************************ -* Function : copy_token -* -* Parameters : -* const token *in ; source token -* const char * in_base ; -* token * out ; destination token -* char * out_base ; -* -* Description : Tokens are generally pointers into other strings -* this copies the offset and size from a token (in) relative to -* one string (in_base) into a token (out) relative to another -* string (out_base) -* -* Return : void ; -* -* Note : -************************************************************************/ -static void -copy_token( const token * in, - const char *in_base, - token * out, - char *out_base ) +/*! + * \brief Returns a 1 if a char is a MARK char as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * \return 1 if char is a MARKED char. + */ +int is_mark( + /*! [in] Char to be matched for MARKED characters. */ + char in) { - out->size = in->size; - out->buff = out_base + ( in->buff - in_base ); + if (strchr(MARK, in)) { + return 1; + } else { + return 0; + } } -/************************************************************************ -* Function : copy_URL_list -* -* Parameters : -* URL_list *in ; Source URL list -* URL_list *out ; Destination URL list -* -* Description : Copies one URL_list into another. This includes -* dynamically allocating the out->URLs field (the full string), -* and the structures used to hold the parsedURLs. This memory MUST -* be freed by the caller through: free_URL_list(&out) -* -* Return : int ; -* HTTP_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On Failure to allocate memory -* -* Note : -************************************************************************/ -int -copy_URL_list( URL_list * in, - URL_list * out ) + +/*! + * \brief Returns a 1 if a char is an UNRESERVED char as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * \return 1 if char is a UNRESERVED char. + */ +int is_unreserved( + /*! [in] Char to be matched for UNRESERVED characters. */ + char in) +{ + if (isalnum(in) || is_mark(in)) { + return 1; + } else { + return 0; + } +} + + +/*! + * \brief Returns a 1 if a char[3] sequence is ESCAPED as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * Size of array is NOT checked (MUST be checked by caller). + * + * \return 1 if char is a ESCAPED char. + */ +int is_escaped( + /*! [in] Char sequence to be matched for ESCAPED characters. */ + const char *in) +{ + if (in[0] == '%' && isxdigit(in[1]) && isxdigit(in[2])) { + return 1; + } else { + return 0; + } +} + + +int replace_escaped(char *in, int index, size_t *max) +{ + int tempInt = 0; + char tempChar = 0; + int i = 0; + int j = 0; + + if (in[index] == '%' && isxdigit(in[index + 1]) && isxdigit(in[index + 2])) { + /* Note the "%2x", makes sure that we convert a maximum of two + * characters. */ + if (sscanf(&in[index + 1], "%2x", &tempInt) != 1) { + return 0; + } + + tempChar = ( char )tempInt; + for (i = index + 3, j = index; j < *max; i++, j++) { + in[j] = tempChar; + if (i < *max) { + tempChar = in[i]; + } else { + tempChar = 0; + } + } + *max -= 2; + return 1; + } else { + return 0; + } +} + + +/*! + * \brief Parses a string of uric characters starting at in[0] as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * \return + */ +static int parse_uric( + /*! [in] String of characters. */ + const char *in, + /*! [in] Maximum limit. */ + int max, + /*! [out] Token object where the string of characters is copied. */ + token *out) +{ + int i = 0; + + while (i < max && + (is_unreserved(in[i]) || + is_reserved(in[i]) || + ((i + 2 < max) && is_escaped(&in[i])))) { + i++; + } + + out->size = i; + out->buff = in; + return i; +} + + +/*! + * \brief Tokens are generally pointers into other strings. This copies the + * offset and size from a token (in) relative to one string (in_base) into + * a token (out) relative to another string (out_base). + */ +static void copy_token( + /*! [in] Source token. */ + const token *in, + /*! [in] . */ + const char *in_base, + /*! [out] Destination token. */ + token *out, + /*! [in] . */ + char *out_base) +{ + out->size = in->size; + out->buff = out_base + (in->buff - in_base); +} + + +int copy_URL_list(URL_list *in, URL_list *out) { int len = strlen( in->URLs ) + 1; int i = 0; @@ -312,68 +246,34 @@ copy_URL_list( URL_list * in, sizeof(struct sockaddr_storage) ); } out->size = in->size; + return HTTP_SUCCESS; - } -/************************************************************************ -* Function : free_URL_list -* -* Parameters : -* URL_list * list ; URL List object -* -* Description : Frees the memory associated with a URL_list. Frees the -* dynamically allocated members of of list. Does NOT free the -* pointer to the list itself ( i.e. does NOT free(list)) -* -* Return : void ; -* -* Note : -************************************************************************/ -void -free_URL_list( URL_list * list ) + +void free_URL_list(URL_list *list) { - if( list->URLs ) - free( list->URLs ); - if( list->parsedURLs ) - free( list->parsedURLs ); - list->size = 0; + if (list->URLs) { + free(list->URLs); + } + if (list->parsedURLs) { + free(list->parsedURLs); + } + list->size = 0; } -/************************************************************************ -* Function : print_uri -* -* Parameters : -* uri_type *in ; URI object -* -* Description : Function useful in debugging for printing a parsed uri. -* -* Return : void ; -* -* Note : -************************************************************************/ + #ifdef DEBUG -void print_uri( uri_type *in ) +void print_uri(uri_type *in) { - print_token( &in->scheme ); - print_token( &in->hostport.text ); - print_token( &in->pathquery ); - print_token( &in->fragment ); + print_token(&in->scheme); + print_token(&in->hostport.text); + print_token(&in->pathquery); + print_token(&in->fragment); } -#endif +#endif /* DEBUG */ + -/************************************************************************ -* Function : print_token -* -* Parameters : -* token * in ; token -* -* Description : Function useful in debugging for printing a token. -* -* Return : void ; -* -* Note : -************************************************************************/ #ifdef DEBUG void print_token(token * in) { @@ -385,115 +285,47 @@ void print_token(token * in) putchar( '\'' ); putchar( '\n' ); } -#endif +#endif /* DEBUG */ -/************************************************************************ -* Function : token_string_casecmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares buffer in the token object with the buffer -* in in2 -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_string_casecmp( - token * in1, - char *in2 ) + +int token_string_casecmp(token *in1, char *in2) { - int in2_length = strlen( in2 ); + int in2_length = strlen(in2); - if( in1->size != in2_length ) - return 1; - else - return strncasecmp( in1->buff, in2, in1->size ); -} - -/************************************************************************ -* Function : token_string_cmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares a null terminated string to a token (exact) -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int -token_string_cmp( token * in1, - char *in2 ) -{ - int in2_length = strlen( in2 ); - - if( in1->size != in2_length ) - return 1; - else - return strncmp( in1->buff, in2, in1->size ); -} - -/************************************************************************ -* Function : token_cmp -* -* Parameters : -* token *in1 ; First token object whose buffer is to be compared -* token *in2 ; Second token object used for the comparison -* -* Description : Compares two tokens -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int -token_cmp( token * in1, - token * in2 ) -{ - if( in1->size != in2->size ) - return 1; - else - return memcmp( in1->buff, in2->buff, in1->size ); + if (in1->size != in2_length) { + return 1; + } else { + return strncasecmp(in1->buff, in2, in1->size); + } } -/************************************************************************ -* Function : parse_hostport -* -* Parameters : -* char *in ; string of characters representing host and port -* int max ; sets a maximum limit (not used). -* hostport_type *out ; out parameter where the host and port -* are represented as an internet address -* -* Description : Parses a string representing a host and port -* (e.g. "127.127.0.1:80" or "localhost") and fills out a -* hostport_type struct with internet address and a token -* representing the full host and port. uses gethostbyname. -* -* Returns: The number of characters that form up the host and port. -* UPNP_E_INVALID_URL on error. -* -* Note : -************************************************************************/ -int -parse_hostport( const char *in, - int max, - hostport_type * out ) +int token_string_cmp(token * in1, char *in2) +{ + int in2_length = strlen(in2); + + if (in1->size != in2_length) { + return 1; + } else { + return strncmp(in1->buff, in2, in1->size); + } +} + + +int token_cmp(token *in1, token *in2) +{ + if (in1->size != in2->size) { + return 1; + } else { + return memcmp(in1->buff, in2->buff, in1->size); + } +} + + +int parse_hostport( + const char *in, + int max, + hostport_type *out) { char workbuf[256]; char* c; @@ -636,28 +468,23 @@ parse_hostport( const char *in, return hostport_size; } -/************************************************************************ -* Function : parse_scheme -* -* Parameters : -* char * in ; string of characters representing a scheme -* int max ; maximum number of characters -* token * out ; output parameter whose buffer is filled in with -* the scheme -* -* Description : parses a uri scheme starting at in[0] as defined in -* http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* (e.g. "http:" -> scheme= "http"). -* Note, string MUST include ':' within the max charcters -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_scheme( const char *in, - int max, - token * out ) +/*! + * \brief parses a uri scheme starting at in[0] as defined in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs). + * + * (e.g. "http:" -> scheme= "http"). + * + * \note String MUST include ':' within the max charcters. + * + * \return + */ +static int parse_scheme( + /*! [in] String of characters representing a scheme. */ + const char *in, + /*! [in] Maximum number of characters. */ + int max, + /*! [out] Output parameter whose buffer is filled in with the scheme. */ + token *out) { int i = 0; @@ -686,26 +513,8 @@ parse_scheme( const char *in, } -/************************************************************************ -* Function : remove_escaped_chars -* -* Parameters : -* INOUT char *in ; string of characters to be modified -* INOUT int *size ; size limit for the number of characters -* -* Description : removes http escaped characters such as: "%20" and -* replaces them with their character representation. i.e. -* "hello%20foo" -> "hello foo". The input IS MODIFIED in place. -* (shortened). Extra characters are replaced with NULL. -* -* Return : int ; -* UPNP_E_SUCCESS -* -* Note : -************************************************************************/ -int -remove_escaped_chars( INOUT char *in, - INOUT size_t *size ) + +int remove_escaped_chars(INOUT char *in, INOUT size_t *size ) { int i = 0; @@ -715,37 +524,8 @@ remove_escaped_chars( INOUT char *in, return UPNP_E_SUCCESS; } -/************************************************************************ -* Function : remove_dots -* -* Parameters : -* char *in ; string of characters from which "dots" have to be -* removed -* int size ; size limit for the number of characters -* -* Description : Removes ".", and ".." from a path. If a ".." can not -* be resolved (i.e. the .. would go past the root of the path) an -* error is returned. The input IS modified in place.) -* -* Return : int ; -* UPNP_E_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On failure to allocate memory -* UPNP_E_INVALID_URL - Failure to resolve URL -* -* Note : -* Examples -* char path[30]="/../hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_INVALID_URL -* char path[30]="/./hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_SUCCESS, -* in = "/hello" -* char path[30]="/./hello/foo/../goodbye" -> -* UPNP_E_SUCCESS, in = "/hello/goodbye" -************************************************************************/ -int -remove_dots( char *in, - int size ) +int remove_dots(char *in, size_t size) { char *copyTo = in; char *copyFrom = in; @@ -810,30 +590,8 @@ remove_dots( char *in, return UPNP_E_SUCCESS; } -/************************************************************************ -* Function : resolve_rel_url -* -* Parameters : -* char * base_url ; Base URL -* char * rel_url ; Relative URL -* -* Description : resolves a relative url with a base url returning a NEW -* (dynamically allocated with malloc) full url. If the base_url is -* NULL, then a copy of the rel_url is passed back if the rel_url -* is absolute then a copy of the rel_url is passed back if neither -* the base nor the rel_url are Absolute then NULL is returned. -* otherwise it tries and resolves the relative url with the base -* as described in: http://www.ietf.org/rfc/rfc2396.txt (RFCs -* explaining URIs) -* : resolution of '..' is NOT implemented, but '.' is resolved -* -* Return : char * ; -* -* Note : -************************************************************************/ -char * -resolve_rel_url( char *base_url, - char *rel_url ) + +char *resolve_rel_url(char *base_url, char *rel_url) { uri_type base; uri_type rel; @@ -920,8 +678,8 @@ resolve_rel_url( char *base_url, if( remove_dots( out_finger, strlen( out_finger ) ) != UPNP_E_SUCCESS ) { - free( out ); - //free(rel_url); + free(out); + /* free(rel_url); */ return NULL; } } @@ -929,46 +687,23 @@ resolve_rel_url( char *base_url, } } } else { - free( out ); - //free(rel_url); + free(out); + /* free(rel_url); */ return NULL; } } } else { - free( out ); - //free(rel_url); + free(out); + /* free(rel_url); */ return NULL; } - //free(rel_url); + /* free(rel_url); */ return out; } -/************************************************************************ -* Function : parse_uri -* -* Parameters : -* char * in ; character string containing uri information to be -* parsed -* int max ; maximum limit on the number of characters -* uri_type * out ; out parameter which will have the parsed uri -* information -* -* Description : parses a uri as defined in http://www.ietf.org/rfc/ -* rfc2396.txt (RFC explaining URIs) -* Handles absolute, relative, and opaque uris. Parses into the -* following pieces: scheme, hostport, pathquery, fragment (path and -* query are treated as one token) -* Caller should check for the pieces they require. -* -* Return : int ; -* -* Note : -************************************************************************/ -int -parse_uri( const char *in, - int max, - uri_type * out ) + +int parse_uri(const char *in, int max, uri_type *out) { int begin_path = 0; int begin_hostport = 0; @@ -1018,34 +753,22 @@ parse_uri( const char *in, return HTTP_SUCCESS; } -/************************************************************************ -* Function : parse_uri_and_unescape -* -* Parameters : -* char * in ; -* int max ; -* uri_type * out ; -* -* Description : Same as parse_uri, except that all strings are -* unescaped (%XX replaced by chars) -* -* Return : int ; -* -* Note: This modifies 'pathquery' and 'fragment' parts of the input -************************************************************************/ -int -parse_uri_and_unescape( char *in, - int max, - uri_type *out ) -{ - int ret; - if( ( ret = parse_uri( in, max, out ) ) != HTTP_SUCCESS ) - return ret; - if( out->pathquery.size > 0 ) - remove_escaped_chars( (char *)out->pathquery.buff, &out->pathquery.size ); - if( out->fragment.size > 0 ) - remove_escaped_chars( (char *)out->fragment.buff, &out->fragment.size ); - return HTTP_SUCCESS; +int parse_uri_and_unescape(char *in, int max, uri_type *out) +{ + int ret = parse_uri(in, max, out); + + if (ret != HTTP_SUCCESS) { + return ret; + } + + if (out->pathquery.size > 0) { + remove_escaped_chars((char *)out->pathquery.buff, &out->pathquery.size); + } + if (out->fragment.size > 0) { + remove_escaped_chars((char *)out->fragment.buff, &out->fragment.size); + } + + return HTTP_SUCCESS; } diff --git a/upnp/src/inc/client_table.h b/upnp/src/inc/client_table.h index 8c04e7f..701fca1 100644 --- a/upnp/src/inc/client_table.h +++ b/upnp/src/inc/client_table.h @@ -34,24 +34,29 @@ #define CLIENT_TABLE_H +/*! + * \file + */ + + #ifdef __cplusplus extern "C" { #endif +#include "service_table.h" +#include "upnp.h" +#include "UpnpString.h" +#include "upnp_timeout.h" +#include "uri.h" +#include "TimerThread.h" + + #include #include #include -#include "service_table.h" -#include "UpnpString.h" -#include "TimerThread.h" -#include "upnp.h" -#include "upnp_timeout.h" -#include "uri.h" - - extern TimerThread gTimerThread; @@ -61,114 +66,205 @@ extern TimerThread gTimerThread; typedef struct s_ClientSubscription ClientSubscription; -/** Constructor */ +/*! + * \brief Constructor. + */ ClientSubscription *UpnpClientSubscription_new(); -/** Destructor */ -void UpnpClientSubscription_delete(ClientSubscription *p); -/** Copy Constructor */ -ClientSubscription *UpnpClientSubscription_dup(const ClientSubscription *p); +/*! + * \brief Destructor. + */ +void UpnpClientSubscription_delete( + /*! [in] The \b this pointer. */ + ClientSubscription *p); -/** Assignment operator */ -void UpnpClientSubscription_assign(ClientSubscription *q, const ClientSubscription *p); -/* */ -int UpnpClientSubscription_get_RenewEventId(const ClientSubscription *p); -void UpnpClientSubscription_set_RenewEventId(ClientSubscription *p, int n); +/*! + * \brief Copy Constructor. + */ +ClientSubscription *UpnpClientSubscription_dup( + /*! [in] The \b this pointer. */ + const ClientSubscription *p); -/* */ -const UpnpString *UpnpClientSubscription_get_SID(const ClientSubscription *p); -void UpnpClientSubscription_set_SID(ClientSubscription *p, const UpnpString *s); -void UpnpClientSubscription_strcpy_SID(ClientSubscription *p, const char *s); -/* */ -const UpnpString *UpnpClientSubscription_get_ActualSID(const ClientSubscription *p); -void UpnpClientSubscription_set_ActualSID(ClientSubscription *p, const UpnpString *s); -void UpnpClientSubscription_strcpy_ActualSID(ClientSubscription *p, const char *s); +/*! + * \brief Assignment operator. + */ +void UpnpClientSubscription_assign( + /*! [in] The \b this pointer. */ + ClientSubscription *q, + const ClientSubscription *p); -/* */ -const UpnpString *UpnpClientSubscription_get_EventURL(const ClientSubscription *p); -void UpnpClientSubscription_set_EventURL(ClientSubscription *p, const UpnpString *s); -void UpnpClientSubscription_strcpy_EventURL(ClientSubscription *p, const char *s); -/* */ -ClientSubscription *UpnpClientSubscription_get_Next(const ClientSubscription *p); -void UpnpClientSubscription_set_Next(ClientSubscription *p, ClientSubscription *q); +/*! + * \brief + */ +int UpnpClientSubscription_get_RenewEventId( + /*! [in] The \b this pointer. */ + const ClientSubscription *p); + + +/*! + * \brief + */ +void UpnpClientSubscription_set_RenewEventId( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + /*! [in] . */ + int n); + + +/*! + * \brief + */ +const UpnpString *UpnpClientSubscription_get_SID( + /*! [in] The \b this pointer. */ + const ClientSubscription *p); + + +/*! + * \brief + */ +void UpnpClientSubscription_set_SID( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + const UpnpString *s); + + +/*! + * \brief + */ +void UpnpClientSubscription_strcpy_SID( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + const char *s); + + +/*! + * \brief + */ +const UpnpString *UpnpClientSubscription_get_ActualSID( + /*! [in] The \b this pointer. */ + const ClientSubscription *p); + + +/*! + * \brief + */ +void UpnpClientSubscription_set_ActualSID( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + const UpnpString *s); + + +/*! + * \brief + */ +void UpnpClientSubscription_strcpy_ActualSID( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + const char *s); + + +/*! + * \brief + */ +const UpnpString *UpnpClientSubscription_get_EventURL( + /*! [in] The \b this pointer. */ + const ClientSubscription *p); + + +/*! + * \brief + */ +void UpnpClientSubscription_set_EventURL( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + const UpnpString *s); + + +/*! + * \brief + */ +void UpnpClientSubscription_strcpy_EventURL( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + const char *s); + + +/*! + * \brief + */ +ClientSubscription *UpnpClientSubscription_get_Next( + /*! [in] The \b this pointer. */ + const ClientSubscription *p); + + +/*! + * \brief + */ +void UpnpClientSubscription_set_Next( + /*! [in] The \b this pointer. */ + ClientSubscription *p, + ClientSubscription *q); -/************************************************************************ - * Function: free_client_subscription +/*! + * \brief Free memory allocated for client subscription data. * - * Parameters: - * ClientSubscription *sub; - Client subscription to be freed - * - * Description: Free memory allocated for client subscription data. - * Remove timer thread associated with this subscription event. - ************************************************************************/ -void free_client_subscription(ClientSubscription * sub); + * Remove timer thread associated with this subscription event. + */ +void free_client_subscription( + /*! [in] Client subscription to be freed. */ + ClientSubscription *sub); -/************************************************************************ - * Function: freeClientSubList - * - * Parameters: - * ClientSubscription *list; Client subscription - * - * Description: Free the client subscription table. - * - * Return: void - ************************************************************************/ -void freeClientSubList(ClientSubscription *list); +/*! + * \brief Free the client subscription table. + */ +void freeClientSubList( + /*! [in] Client subscription list to be freed. */ + ClientSubscription *list); -/************************************************************************ - * Function: RemoveClientSubClientSID - * - * Parameters: - * ClientSubscription **head; Head of the subscription list - * const UpnpString sid; Subscription ID to be mactched - * - * Description: Remove the client subscription matching the - * subscritpion id represented by the const Upnp_SID sid parameter - * from the table and update the table. - * - * Return: void - ************************************************************************/ -void RemoveClientSubClientSID(ClientSubscription **head, const UpnpString *sid); - - -/************************************************************************ - * Function: GetClientSubClientSID - * - * Parameters: - * ClientSubscription *head; Head of the subscription list - * const UpnpString *sid; Subscription ID to be matched - * - * Description: Return the client subscription from the client table - * that matches const Upnp_SID sid subscrition id value. - * - * Return: ClientSubscription * The matching subscription - ************************************************************************/ -ClientSubscription *GetClientSubClientSID( - ClientSubscription *head, +/*! + * \brief Remove the client subscription matching the subscritpion id + * represented by the const Upnp_SID sid parameter from the table and + * update the table. + */ +void RemoveClientSubClientSID( + /*! [in] Head of the subscription list. */ + ClientSubscription **head, + /*! [in] Subscription ID to be mactched. */ const UpnpString *sid); -/************************************************************************ - * Function: GetClientSubActualSID +/*! + * \brief Return the client subscription from the client table that matches + * const Upnp_SID sid subscrition id value. * - * Parameters: - * ClientSubscription *head; Head of the subscription list - * token *sid; Subscription ID to be matched + * \return The matching subscription. + */ +ClientSubscription *GetClientSubClientSID( + /*! [in] Head of the subscription list. */ + ClientSubscription *head, + /*! [in] Subscription ID to be mactched. */ + const UpnpString *sid); + + +/*! + * \brief Returns the client subscription from the client subscription table + * that has the matching token *sid buffer value. * - * Description: Returns the client subscription from the client - * subscription table that has the matching token *sid buffer value. - * - * Return: ClientSubscription *; The matching subscription - ************************************************************************/ -ClientSubscription *GetClientSubActualSID(ClientSubscription *head, token *sid); + * \return The matching subscription. + */ +ClientSubscription *GetClientSubActualSID( + /*! [in] Head of the subscription list. */ + ClientSubscription *head, + /*! [in] Subscription ID to be mactched. */ + token *sid); #endif /* INCLUDE_CLIENT_APIS */ diff --git a/upnp/src/inc/uri.h b/upnp/src/inc/uri.h index ef2055c..b7cef7a 100644 --- a/upnp/src/inc/uri.h +++ b/upnp/src/inc/uri.h @@ -34,7 +34,12 @@ #define GENLIB_NET_URI_H -#include "upnp.h" +/*! + * \file + */ + + +#include "UpnpGlobal.h" /* for */ #include @@ -72,455 +77,514 @@ extern "C" { #define RESERVED ";/?:@&=+$,{}" //added {} for compatibility #define HTTP_SUCCESS 1 + #define FALSE 0 #define TAB 9 #define CR 13 #define LF 10 #define SOCKET_BUFFER_SIZE 5000 -enum hostType { HOSTNAME, IPv4address }; -enum pathType { ABS_PATH, REL_PATH, OPAQUE_PART }; + +enum hostType { + HOSTNAME, + IPv4address +}; + + +enum pathType { + ABS_PATH, + REL_PATH, + OPAQUE_PART +}; + + #ifdef WIN32 - // there is a conflict in windows with other symbols - enum uriType { absolute, relative }; + /* there is a conflict in windows with other symbols */ + enum uriType { + absolute, + relative + }; #else - enum uriType { ABSOLUTE, RELATIVE }; + enum uriType { + ABSOLUTE, + RELATIVE + }; #endif -/* Buffer used in parsinghttp messages, urls, etc. generally this simply -* holds a pointer into a larger array */ +/*! + * \brief Buffer used in parsinghttp messages, urls, etc. generally this simply + * holds a pointer into a larger array. + */ typedef struct TOKEN { - const char *buff; - size_t size; + const char *buff; + size_t size; } token; -/* Represents a host port:e.g. :"127.127.0.1:80" -* text is a token pointing to the full string representation */ +/*! + * \brief Represents a host port: e.g. "127.127.0.1:80" text is a token + * pointing to the full string representation. + */ typedef struct HOSTPORT { - token text; //full host port - struct sockaddr_storage IPaddress; //Network Byte Order + /*! Full host port. */ + token text; + /* Network Byte Order */ + struct sockaddr_storage IPaddress; } hostport_type; -/* Represents a URI used in parse_uri and elsewhere */ + +/*! + * \brief Represents a URI used in parse_uri and elsewhere + */ typedef struct URI{ - enum uriType type; - token scheme; - enum pathType path_type; - token pathquery; - token fragment; - hostport_type hostport; + enum uriType type; + token scheme; + enum pathType path_type; + token pathquery; + token fragment; + hostport_type hostport; } uri_type; -/* Represents a list of URLs as in the "callback" header of SUBSCRIBE -* message in GENA -* char * URLs holds dynamic memory */ + +/*! + * \brief Represents a list of URLs as in the "callback" header of SUBSCRIBE + * message in GENA. "char *" URLs holds dynamic memory. + */ typedef struct URL_LIST { - int size; - char * URLs; //all the urls, delimited by <> - uri_type *parsedURLs; + /*! */ + int size; + /*! All the urls, delimited by <> */ + char *URLs; + /*! */ + uri_type *parsedURLs; } URL_list; -/************************************************************************ -* Function : replace_escaped -* -* Parameters : -* char * in ; string of characters -* int index ; index at which to start checking the characters -* size_t *max ; -* -* Description : Replaces an escaped sequence with its unescaped version -* as in http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) -* Size of array is NOT checked (MUST be checked by caller) -* -* Return : int ; -* -* Note : This function modifies the string. If the sequence is an -* escaped sequence it is replaced, the other characters in the -* string are shifted over, and NULL characters are placed at the -* end of the string. -************************************************************************/ -int replace_escaped(char * in, int index, size_t *max); +/*! + * \brief Replaces an escaped sequence with its unescaped version as in + * http://www.ietf.org/rfc/rfc2396.txt (RFC explaining URIs) + * + * Size of array is NOT checked (MUST be checked by caller) + * + * \note This function modifies the string. If the sequence is an escaped + * sequence it is replaced, the other characters in the string are shifted + * over, and NULL characters are placed at the end of the string. + * + * \return + */ +int replace_escaped( + /*! [in] String of characters. */ + char *in, + /*! [in] Index at which to start checking the characters. */ + int index, + /*! [out] . */ + size_t *max); -/************************************************************************ -* Function : copy_URL_list -* -* Parameters : -* URL_list *in ; Source URL list -* URL_list *out ; Destination URL list -* -* Description : Copies one URL_list into another. This includes -* dynamically allocating the out->URLs field (the full string), -* and the structures used to hold the parsedURLs. This memory MUST -* be freed by the caller through: free_URL_list(&out) -* -* Return : int ; -* HTTP_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On Failure to allocate memory -* -* Note : -************************************************************************/ -int copy_URL_list( URL_list *in, URL_list *out); -/************************************************************************ -* Function : free_URL_list -* -* Parameters : -* URL_list * list ; URL List object -* -* Description : Frees the memory associated with a URL_list. Frees the -* dynamically allocated members of of list. Does NOT free the -* pointer to the list itself ( i.e. does NOT free(list)) -* -* Return : void ; -* -* Note : -************************************************************************/ -void free_URL_list(URL_list * list); +/*! + * \brief Copies one URL_list into another. + * + * This includes dynamically allocating the out->URLs field (the full string), + * and the structures used to hold the parsedURLs. This memory MUST be freed + * by the caller through: free_URL_list(&out). + * + * \return + * \li HTTP_SUCCESS - On Success. + * \li UPNP_E_OUTOF_MEMORY - On Failure to allocate memory. + */ +int copy_URL_list( + /*! [in] Source URL list. */ + URL_list *in, + /*! [out] Destination URL list. */ + URL_list *out); -/************************************************************************ -* Function : print_uri -* -* Parameters : -* uri_type *in ; URI object -* -* Description : Function useful in debugging for printing a parsed uri. -* -* Return : void ; -* -* Note : -************************************************************************/ +/*! + * \brief Frees the memory associated with a URL_list. + * + * Frees the dynamically allocated members of of list. Does NOT free the + * pointer to the list itself ( i.e. does NOT free(list)). + */ +void free_URL_list( + /*! [in] URL list object. */ + URL_list *list); + + +/*! + * \brief Function useful in debugging for printing a parsed uri. + */ #ifdef DEBUG -void print_uri(uri_type *in); +void print_uri( + /*! [in] URI object to print. */ + uri_type *in); #else static UPNP_INLINE void print_uri(uri_type *in) {} #endif -/************************************************************************ -* Function : print_token -* -* Parameters : -* token * in ; -* -* Description : Function useful in debugging for printing a token. -* -* Return : void ; -* -* Note : -************************************************************************/ + +/*! + * \brief Function useful in debugging for printing a token. + */ #ifdef DEBUG -void print_token(token *in); +void print_token( + /*! [in] Token object to print. */ + token *in); #else static UPNP_INLINE void print_token(token * in) {} #endif -/************************************************************************ -* Function : token_string_casecmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares buffer in the token object with the buffer -* in in2 -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_string_casecmp( token * in1, char * in2); -/************************************************************************ -* Function : token_string_cmp -* -* Parameters : -* token * in1 ; Token object whose buffer is to be compared -* char * in2 ; string of characters to compare with -* -* Description : Compares a null terminated string to a token (exact) -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_string_cmp( token * in1, char * in2); - -/************************************************************************ -* Function : token_cmp -* -* Parameters : -* token *in1 ; First token object whose buffer is to be compared -* token *in2 ; Second token object used for the comparison -* -* Description : Compares two tokens -* -* Return : int ; -* < 0 string1 less than string2 -* 0 string1 identical to string2 -* > 0 string1 greater than string2 -* -* Note : -************************************************************************/ -int token_cmp( token *in1, token *in2); - -/************************************************************************ -* Function : parse_port -* -* Parameters : -* int max ; sets a maximum limit -* char * port ; port to be parsed. -* unsigned short * out ; out parameter where the port is parsed -* and converted into network format -* -* Description : parses a port (i.e. '4000') and converts it into a -* network ordered unsigned short int. -* -* Return : int ; -* -* Note : -************************************************************************/ -int parse_port(int max, const char *port, unsigned short int *out); - -/************************************************************************ -* Function : parse_hostport -* -* Parameters : -* char *in ; string of characters representing host and port -* int max ; sets a maximum limit -* hostport_type *out ; out parameter where the host and port -* are represented as an internet address -* -* Description : Parses a string representing a host and port -* (e.g. "127.127.0.1:80" or "localhost") and fills out a -* hostport_type struct with internet address and a token -* representing the full host and port. uses gethostbyname. -* -* Return : int ; -* -* Note : -************************************************************************/ -int parse_hostport(const char *in, int max, hostport_type *out ); - -/************************************************************************ -* Function : remove_escaped_chars -* -* Parameters : -* INOUT char *in ; string of characters to be modified -* INOUT size_t *size ; size limit for the number of characters -* -* Description : removes http escaped characters such as: "%20" and -* replaces them with their character representation. i.e. -* "hello%20foo" -> "hello foo". The input IS MODIFIED in place. -* (shortened). Extra characters are replaced with NULL. -* -* Return : int ; -* UPNP_E_SUCCESS -* -* Note : -************************************************************************/ -int remove_escaped_chars(char *in, size_t *size); - -/************************************************************************ -* Function : remove_dots -* -* Parameters : -* char *in ; string of characters from which "dots" have to be -* removed -* int size ; size limit for the number of characters -* -* Description : Removes ".", and ".." from a path. If a ".." can not -* be resolved (i.e. the .. would go past the root of the path) an -* error is returned. The input IS modified in place.) -* -* Return : int ; -* UPNP_E_SUCCESS - On Success -* UPNP_E_OUTOF_MEMORY - On failure to allocate memory -* UPNP_E_INVALID_URL - Failure to resolve URL -* -* Note : -* Examples -* char path[30]="/../hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_INVALID_URL -* char path[30]="/./hello"; -* remove_dots(path, strlen(path)) -> UPNP_E_SUCCESS, -* in = "/hello" -* char path[30]="/./hello/foo/../goodbye" -> -* UPNP_E_SUCCESS, in = "/hello/goodbye" - -************************************************************************/ -int remove_dots(char * in, int size); - -/************************************************************************ -* Function : resolve_rel_url -* -* Parameters : -* char * base_url ; Base URL -* char * rel_url ; Relative URL -* -* Description : resolves a relative url with a base url returning a NEW -* (dynamically allocated with malloc) full url. If the base_url is -* NULL, then a copy of the rel_url is passed back if the rel_url -* is absolute then a copy of the rel_url is passed back if neither -* the base nor the rel_url are Absolute then NULL is returned. -* otherwise it tries and resolves the relative url with the base -* as described in: http://www.ietf.org/rfc/rfc2396.txt (RFCs -* explaining URIs) -* : resolution of '..' is NOT implemented, but '.' is resolved -* -* Return : char * ; -* -* Note : -************************************************************************/ -char * resolve_rel_url( char * base_url, char * rel_url); - -/************************************************************************ -* Function : parse_uri -* -* Parameters : -* char * in ; character string containing uri information to be -* parsed -* int max ; maximum limit on the number of characters -* uri_type * out ; out parameter which will have the parsed uri -* information -* -* Description : parses a uri as defined in http://www.ietf.org/rfc/ -* rfc2396.txt (RFC explaining URIs) -* Handles absolute, relative, and opaque uris. Parses into the -* following pieces: scheme, hostport, pathquery, fragment (path and -* query are treated as one token) -* Caller should check for the pieces they require. -* -* Return : int ; -* -* Note : -************************************************************************/ -int parse_uri(const char * in, int max, uri_type * out); - -/************************************************************************ -* Function : parse_uri_and_unescape -* -* Parameters : -* char * in ; -* int max ; -* uri_type * out ; -* -* Description : Same as parse_uri, except that all strings are -* unescaped (%XX replaced by chars) -* -* Return : int ; -* -* Note: This modifies 'pathquery' and 'fragment' parts of the input -************************************************************************/ -int parse_uri_and_unescape(char * in, int max, uri_type * out); - -int parse_token( char * in, token * out, int max_size); - -/************************************************************************ -* commented #defines, functions and typdefs * -************************************************************************/ - -/************************************************************************ -* Commented #defines * -************************************************************************/ -//#define HTTP_E_BAD_URL UPNP_E_INVALID_URL -//#define HTTP_E_READ_SOCKET UPNP_E_SOCKET_READ -//#define HTTP_E_BIND_SOCKET UPNP_E_SOCKET_BIND -//#define HTTP_E_WRITE_SOCKET UPNP_E_SOCKET_WRITE -//#define HTTP_E_CONNECT_SOCKET UPNP_E_SOCKET_CONNECT -//#define HTTP_E_SOCKET UPNP_E_OUTOF_SOCKET -//#define HTTP_E_BAD_RESPONSE UPNP_E_BAD_RESPONSE -//#define HTTP_E_BAD_REQUEST UPNP_E_BAD_REQUEST -//#define HTTP_E_BAD_IP_ADDRESS UPNP_E_INVALID_URL - -//#define RESPONSE_TIMEOUT 30 - -/************************************************************************ -* Commented typedefs * -************************************************************************/ -//Buffer used to store data read from a socket during an http transfer -//in function read_bytes. -//typedef struct SOCKET_BUFFER{ -// char buff[SOCKET_BUFFER_SIZE]; -// int size; -// struct SOCKET_BUFFER *next; -//} socket_buffer; - -//typedef struct HTTP_HEADER { -// token header; -// token value; -// struct HTTP_HEADER * next; -//} http_header; - -//typedef struct HTTP_STATUS_LINE{ -// token http_version; -// token status_code; -// token reason_phrase; -//} http_status; - -//typedef struct HTTP_REQUEST_LINE { -// token http_version; -// uri_type request_uri; -// token method; -//} http_request; - -//Represents a parsed HTTP_MESSAGE head_list is dynamically allocated -//typedef struct HTTP_MESSAGE { -// http_status status; -// http_request request; -// http_header * header_list; -// token content; -//} http_message; - -/************************************************************************ -* Commented functions * -************************************************************************ - -EXTERN_C int transferHTTP( char * request, char * toSend, - int toSendSize, char **out, char * Url); +/*! + * \brief Compares buffer in the token object with the buffer in in2. + * + * \return + * \li < 0, if string1 is less than string2. + * \li == 0, if string1 is identical to string2 . + * \li > 0, if string1 is greater than string2. + */ +int token_string_casecmp( + /*! [in] Token object whose buffer is to be compared. */ + token *in1, + /*! [in] String of characters to compare with. */ + char *in2); -EXTERN_C int transferHTTPRaw( char * toSend, int toSendSize, - char **out, char *URL); +/*! + * \brief Compares a null terminated string to a token (exact). + * + * \return + * \li < 0, if string1 is less than string2. + * \li == 0, if string1 is identical to string2 . + * \li > 0, if string1 is greater than string2. + */ +int token_string_cmp( + /*! [in] Token object whose buffer is to be compared. */ + token *in1, + /*! [in] String of characters to compare with. */ + char *in2); -helper function -EXTERN_C int transferHTTPparsedURL( char * request, - char * toSend, int toSendSize, - char **out, uri_type *URL); -assumes that char * out has enough space ( 38 characters) -outputs the current time in the following null terminated string: - "DATE: Sun, Jul 06 2000 08:53:01 GMT\r\n" -EXTERN_C void currentTmToHttpDate(char *out); +/*! + * \brief Compares two tokens. + * + * \return + * \li < 0, if string1 is less than string2. + * \li == 0, if string1 is identical to string2 . + * \li > 0, if string1 is greater than string2. + */ +int token_cmp( + /*! [in] First token object whose buffer is to be compared. */ + token *in1, + /*! [in] Second token object used for the comparison. */ + token *in2); -EXTERN_C int parse_http_response( char * in, http_message * out, - int max_len); -EXTERN_C int parse_http_request( char * in, http_message *out, - int max_len); +/*! + * \brief Parses a port (i.e. '4000') and converts it into a network ordered + * unsigned short int. + * + * \return + */ +int parse_port( + /*! [in] Sets a maximum limit. */ + int max, + /*! [in] Port to be parsed. */ + const char *port, + /*! [out] Output parameter where the port is parsed and converted into + * network format. */ + unsigned short int *out); -EXTERN_C void print_http_message( http_message * message); -EXTERN_C int search_for_header( http_message * in, - char * header, token *out_value); -EXTERN_C void print_status_line(http_status *in); -EXTERN_C void print_request_line(http_request *in); -EXTERN_C int parse_http_line( char * in, int max_size); -EXTERN_C int parse_not_LWS( char *in, token *out, int max_size); -EXTERN_C int parse_LWS( char * in, int max_size); +/*! + * \brief Parses a string representing a host and port (e.g. "127.127.0.1:80" + * or "localhost") and fills out a hostport_type struct with internet address + * and a token representing the full host and port. + * + * Uses gethostbyname. + */ +int parse_hostport( + /*! [in] String of characters representing host and port. */ + const char *in, + /*! [in] Sets a maximum limit. */ + int max, + /*! [out] Output parameter where the host and port are represented as + * an internet address. */ + hostport_type *out); -EXTERN_C size_t write_bytes(int fd, char * bytes, size_t n, - int timeout); -EXTERN_C void free_http_message(http_message * message); -************************************************************************/ +/*! + * \brief Removes http escaped characters such as: "%20" and replaces them with + * their character representation. i.e. "hello%20foo" -> "hello foo". + * + * The input IS MODIFIED in place (shortened). Extra characters are replaced + * with \b NULL. + * + * \return UPNP_E_SUCCESS. + */ +int remove_escaped_chars( + /*! [in,out] String of characters to be modified. */ + char *in, + /*! [in,out] Size limit for the number of characters. */ + size_t *size); + + +/*! + * \brief Removes ".", and ".." from a path. + * + * If a ".." can not be resolved (i.e. the .. would go past the root of the + * path) an error is returned. + * + * The input IS modified in place.) + * + * \note Examples + * char path[30]="/../hello"; + * remove_dots(path, strlen(path)) -> UPNP_E_INVALID_URL + * char path[30]="/./hello"; + * remove_dots(path, strlen(path)) -> UPNP_E_SUCCESS, + * in = "/hello" + * char path[30]="/./hello/foo/../goodbye" -> + * UPNP_E_SUCCESS, in = "/hello/goodbye" + * + * \return + * \li UPNP_E_SUCCESS - On Success. + * \li UPNP_E_OUTOF_MEMORY - On failure to allocate memory. + * \li UPNP_E_INVALID_URL - Failure to resolve URL. + */ +int remove_dots( + /*! [in] String of characters from which "dots" have to be removed. */ + char *in, + /*! [in] Size limit for the number of characters. */ + size_t size); + + +/*! + * \brief resolves a relative url with a base url returning a NEW (dynamically + * allocated with malloc) full url. + * + * If the base_url is \b NULL, then a copy of the rel_url is passed back if + * the rel_url is absolute then a copy of the rel_url is passed back if neither + * the base nor the rel_url are Absolute then NULL is returned. Otherwise it + * tries and resolves the relative url with the base as described in + * http://www.ietf.org/rfc/rfc2396.txt (RFCs explaining URIs). + * + * The resolution of '..' is NOT implemented, but '.' is resolved. + * + * \return + */ +char *resolve_rel_url( + /*! [in] Base URL. */ + char *base_url, + /*! [in] Relative URL. */ + char *rel_url); + + +/*! + * \brief Parses a uri as defined in http://www.ietf.org/rfc/rfc2396.txt + * (RFC explaining URIs). + * + * Handles absolute, relative, and opaque uris. Parses into the following + * pieces: scheme, hostport, pathquery, fragment (path and query are treated + * as one token) + * + * Caller should check for the pieces they require. + * + * \return + */ +int parse_uri( + /*! [in] Character string containing uri information to be parsed. */ + const char *in, + /*! [in] Maximum limit on the number of characters. */ + int max, + /*! [out] Output parameter which will have the parsed uri information. */ + uri_type *out); + + +/*! + * \brief Same as parse_uri(), except that all strings are unescaped + * (%XX replaced by chars). + * + * \note This modifies 'pathquery' and 'fragment' parts of the input. + * + * \return + */ +int parse_uri_and_unescape( + /*! [in] Character string containing uri information to be parsed. */ + char *in, + /*! [in] Maximum limit on the number of characters. */ + int max, + /*! [out] Output parameter which will have the parsed uri information. */ + uri_type *out); + + +/*! + * \brief + * + * \return + */ +int parse_token( + /*! [in] . */ + char *in, + /*! [out] . */ + token *out, + /*! [in] . */ + int max_size); + + +/* Commented #defines, functions and typdefs */ + +#if 0 +#define HTTP_E_BAD_URL UPNP_E_INVALID_URL +#define HTTP_E_READ_SOCKET UPNP_E_SOCKET_READ +#define HTTP_E_BIND_SOCKET UPNP_E_SOCKET_BIND +#define HTTP_E_WRITE_SOCKET UPNP_E_SOCKET_WRITE +#define HTTP_E_CONNECT_SOCKET UPNP_E_SOCKET_CONNECT +#define HTTP_E_SOCKET UPNP_E_OUTOF_SOCKET +#define HTTP_E_BAD_RESPONSE UPNP_E_BAD_RESPONSE +#define HTTP_E_BAD_REQUEST UPNP_E_BAD_REQUEST +#define HTTP_E_BAD_IP_ADDRESS UPNP_E_INVALID_URL + +#define RESPONSE_TIMEOUT 30 +#endif + +#if 0 +/*! + * Buffer used to store data read from a socket during an http transfer in + * function read_bytes. + */ +typedef struct SOCKET_BUFFER{ + char buff[SOCKET_BUFFER_SIZE]; + int size; + struct SOCKET_BUFFER *next; +} socket_buffer; + + +typedef struct HTTP_HEADER { + token header; + token value; + struct HTTP_HEADER * next; +} http_header; + + +typedef struct HTTP_STATUS_LINE{ + token http_version; + token status_code; + token reason_phrase; +} http_status; + + +typedef struct HTTP_REQUEST_LINE { + token http_version; + uri_type request_uri; + token method; +} http_request; + + +/*! + * Represents a parsed HTTP_MESSAGE head_list is dynamically allocated + */ +typedef struct HTTP_MESSAGE { + http_status status; + http_request request; + http_header * header_list; + token content; +} http_message; +#endif + + +#if 0 +int transferHTTP( + char *request, + char *toSend, + int toSendSize, + char **out, + char *Url); + + +int transferHTTPRaw( + char *toSend, + int toSendSize, + char **out, + char *URL); + + +/*! + * \brief helper function. + */ +int transferHTTPparsedURL( + char *request, + char *toSend, + int toSendSize, + char **out, + uri_type *URL); + + +/*! + * \brief assumes that char * out has enough space ( 38 characters) + * outputs the current time in the following null terminated string: + * "DATE: Sun, Jul 06 2000 08:53:01 GMT\r\n" + */ +void currentTmToHttpDate( + char *out); + + +int parse_http_response( + char *in, + http_message *out, + int max_len); + + +int parse_http_request( + char *in, + http_message *out, + int max_len); + + +void print_http_message( + http_message *message); + + +int search_for_header( + http_message *in, + char *header, + token *out_value); + + +void print_status_line( + http_status *in); + + +void print_request_line( + http_request *in); + + +int parse_http_line( + char *in, + int max_size); + + +int parse_not_LWS( + char *in, + token *out, + int max_size); + + +int parse_LWS( + char *in, + int max_size); + + +size_t write_bytes( + int fd, + char *bytes, + size_t n, + int timeout); + + +void free_http_message( + http_message *message); + + +#endif #ifdef __cplusplus