Die Funktion kcHttpPercentDecode wandelt Zeichen in Prozent-Darstellung, die in der übergebenen Zeichenfolgen enthalten sind, in ihre normale Ein-Zeichen-Darstellung um.
In der URL eines HTTP-Requests können einzelne Zeichen in ihrer %-Darstellung enthalten sein. Dieser Mechanismus ist in RFC 3986 "Uniform Resource Identifier" näher beschrieben. Dabei werden bestimmte US-ASCII Zeichen in ihrer Sedezimal-Darstellung wiedergegeben. Eine solche Prozent-Darstellung wird durch ein vorangestelltes Prozentzeichen ("%") gekennzeichnet; z.B. kann ein Leerzeichen als %20 dargestellt werden oder das Zeichen Tilde ("~") durch die Zeichenfolge %7E.
Die Funktion kcHttpPercentDecode kann insbesondere zur Normalisierung der Query eines HTTP-Requests sinnvoll eingesetzt werden.
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
);
Diese Funktion hat folgende Funktionsparameter:
| >> | normFlags | Wert aus enum kc_http_norm, mit dem der Umfang der gewünschten Umsetzung festgelegt wird. |
| <> | bufferUrl | Adresse des Puffers, in dem die umzusetzende Zeichenfolge übergeben und die umgesetzte Zeichenfolge zurückgegeben wird. Der Puffer muss mindestens inputLth Bytes lang sein. |
| >> | inputLth | Länge der umzusetzenden Zeichenfolge. |
| << | outputLth | Adresse einer Variablen, in der die Länge der umgesetzten Zeichenfolge zurückgegeben wird. |
Mit dem Parameter normFlags wird der Umfang der gewünschten Umsetzungen festgelegt.
normFlags
KC_HTTP_NORM_MINIMUM
Bei diesem Wert wird nur eine "case normalization" durchgeführt, d.h. die beiden Buchstaben, die einem %-Zeichen folgen, werden in Großbuchstaben umgesetzt.
KC_HTTP_NORM_SPACE_ONLY
Bei diesem Wert werden zusätzlich zu KC_HTTP_NORM_MINIMUM alle "%20" Codierungen durch Leerzeichen ersetzt.
KC_HTTP_NORM_UNRESERVED
Bei diesem Wert werden zusätzlich zu KC_HTTP_NORM_SPACE_ONLY alle Prozent-Darstellungen von Unreserved Characters durch ihre "normale" Ein-Zeichen Darstellung ersetzt. Zur Definition von Unreserved Characters siehe RFC 3986 "Uniform Resource Identifier".
KC_HTTP_NORM_RESERVED
Bei diesem Wert werden zusätzlich zu KC_HTTP_NORM_UNRESERVED alle Prozent-Darstellungen von Reserved Characters durch ihre "normale" Ein-Zeichen Darstellung ersetzt. Bzgl. der Definition von Reserved Characters siehe RFC 3986 "Uniform Resource Identifier".
KC_HTTP_NORM_ALL_BUT_PERCENT
Bei diesem Wert werden zusätzlich zu KC_HTTP_NORM_RESERVED alle Prozent-Darstellungen außer %25 ("%") durch ihre "normale" Ein-Zeichen Darstellung ersetzt.
KC_HTTP_NORM_ALL
Bei diesem Wert werden alle Prozent-Darstellungen durch ihre "normale" Ein-Zeichen Darstellung ersetzt.
Der zurückgelieferte Funktionswert hat folgende Bedeutung:
KC_HTTP_OK
Die Funktion wurde erfolgreich ausgeführt.
KC_HTTP_PARAM_VALUE_NULL
Die Adresse des Puffers bufferUrl oder die Adresse für die Länge der umgesetzten Zeichenfolge outputLth ist NULL.
KC_HTTP_INVALID_LENGTH
Die Länge der umzusetzenden Zeichenfolge inputLth ist negativ oder die umzusetzende Zeichenfolge enthält ein Nullzeichen (\0).
KC_HTTP_NORMALIZATION_ERROR
Im Parameter normFlags wurde ein ungültiger Wert übergeben oder bei der Normalisierung trat ein Fehler auf.
KC_HTTP_PARAM_INVALID_URLSTRING
Die umzusetzende Zeichenfolge enthält ein Prozentzeichen ("%"), aber eines der nächsten beiden Zeichen ist keine abdruckbare Hexadezimal-Zahl.