Function kcHttpPercentDecode

The function kcHttpPercentDecode converts percent-encoded characters, which are contained in the given character strings, in their normal one-character representation.

In the URL of an HTTP request, individual characters can be contained in their percent-encoded representation. This mechanism is described in more detail in RFC 3986 "Uniform Resource Identifier". Certain US ASCII characters are represented in their sedecimal representation. Such a substitute representation is preceded by a percent sign ("%"); e.g. a space can be represented as %20 or the character tilde ("~") by the character string %7E.
The function kcHttpPercentDecode can be used to normalize the query of an HTTP request.

Function declaration kcHttpPercentDecode

typedef enum
   {  KC_HTTP_NORM_MINIMUM                                              =  1
    , KC_HTTP_NORM_SPACE_ONLY                                           =  2
    , KC_HTTP_NORM_UNRESERVED                                           =  4
    , KC_HTTP_NORM_RESERVED                                             =  8
    , KC_HTTP_NORM_ALL_BUT_PERCENT                                      = 16
    , KC_HTTP_NORM_ALL                                                  = 32
   } kc_http_norm;
 
kc_http_retcode kcHttpPercentDecode( kc_http_norm  normFlags,
                                     char *        bufferUrl,
                                     int           inputLth,
                                     int *         outputLth
                                   );

This function has following parameters:

>>	normFlags	Value from enum kc_http_norm which determines the scope of the requested decoding.
<>	bufferUrl	The pointer to a buffer in which the encoded string is passed and the decoded string is returned. The buffer must be at least inputLth bytes long.
>>	inputLth	The length of the encoded string.
<<	outputLth	The pointer to a variable in which the length of the decoded string is returned.

The parameter normFlags defines the scope of the requested decoding.

normFlags can have the following values:

KC_HTTP_NORM_MINIMUM

With this value, only "case normalization" is performed, i.e. the two letters following a % character are converted to capital letters..

KC_HTTP_NORM_SPACE_ONLY

With this value, in addition to KC_HTTP_NORM_MINIMUM, all "%20" encodings are replaced by spaces.

KC_HTTP_NORM_UNRESERVED

With this value, in addition to KC_HTTP_NORM_SPACE_ONLY, all percent-encoded Unreserved Characters are replaced by their "normal" one-character representation. For the definition of Unreserved Characters see RFC 3986 "Uniform Resource Identifier".

KC_HTTP_NORM_RESERVED

With this value, in addition to KC_HTTP_NORM_UNRESERVED, all percent-encoded Reserved Characters are replaced by their "normal" one-character representation. For the definition of Reserved Characters see RFC 3986 "Uniform Resource Identifier".

KC_HTTP_NORM_ALL_BUT_PERCENT

With this value, in addition to KC_HTTP_NORM_RESERVED, all percent-encoded characters except %25 ("%") are replaced by their "normal" one-character representation.

KC_HTTP_NORM_ALL

With this value, all percent-encoded characters are replaced by their "normal" one-character representation.

Meaning of returned value of function call:

KC_HTTP_OK

The function has successfully terminated.

KC_HTTP_PARAM_VALUE_NULL

The pointer to the buffer bufferUrl or the pointer to the length of the decoded string outputLth is NULL.

KC_HTTP_INVALID_LENGTH

The length of the encoded string inputLth is lower 0 or the encoded string contains a null byte (\0).

KC_HTTP_NORMALIZATION_ERROR

An invalid value was passed in parameter normFlags or an error occurred during normalization.

KC_HTTP_PARAM_INVALID_URLSTRING

The encoded string contains a percent sign ("%") but one of the next two characters is not a printable hexadecimal number.