Die Funktionen der UTM-HTTP-Programmschnittstelle teilen sich in zwei Gruppen auf, die kcHttpGet- und die kcHttpPut-Funktionen. Sie können sowohl von einem HTTP-Exit-Programm (s. Kapitel „Event-Exit HTTP") als auch von UTM-Teilprogrammen aufgerufen werden. Eine Ausnahme bilden die Funktionen kcHttpGetMputMsg, kcHttpPutMgetMsg, kcHttpPutRspMsgBody, die nur in einem HTTP-Exit-Programm verwendet werden dürfen.
Außerdem gibt es die beiden Hilfsfunktionen kcHttpPercentDecode und kcHttpGetRc2String.
In UTM-Teilprogrammen dürfen die Funktionen erst nach dem KDCS-Aufruf INIT aufgerufen werden. Die im Teilprogramm erlaubten kcHttpGet-Funktionen dürfen nur im ersten Teilprogrammlauf eines (nicht geketteten) Vorgangs aufgerufen werden.
Wenn ein Teilprogramm die Funktionen kcHttpPutHeader und kcHttpPutStatus verwendet, so muss es auch mit MPUT eine Nachricht für den HTTP-Client bereitstellen und den Vorgang beenden, ansonsten gehen die übergebenen Header- bzw. Status-Informationen verloren.
Zur Verwendung der Funktionen im HTTP-Exit-Programm s. Kapitel „Event-Exit HTTP".
Eingabe-Parameter der C-Funktionen, die vom Typ char * sind, müssen vom Aufrufer als null-terminierter String übergeben werden. Ebenso gibt openUTM in Ausgabe-Parametern, die vom Typ
char * sind, null-terminierte Strings zurück.
Alle Funktionen bis auf die Hilfsfunktion kcHttpGetRc2String liefern bei nicht erfolgreicher Ausführung negative Zahlenkonstanten, die als C-Datentyp enum definiert sind, als Funktionsergebnis zurück.
Bei erfolgreicher Ausführung wird entweder die Zahlenkonstante 0 oder ein positiver Funktionswert zurückgeliefert.
Folgende Funktionen stehen zur Verfügung:
Funktion | Beschreibung |
|---|---|
kcHttpGetHeaderByIndex
| liefert den Namen und Wert des HTTP-Header-Feldes für den angegebenen Index zurück |
kcHttpGetHeaderByName
| liefert den Wert des über den Namen spezifizierten HTTP-Header-Feldes zurück |
kcHttpGetHeaderCount
| liefert die Anzahl der im HTTP-Request enthaltenen HTTP-Header-Felder zurück |
kcHttpGetMethod
| liefert die HTTP-Methode des HTTP-Requests zurück |
kcHttpGetMputMsg
| liefert die vom Teilprogramm erzeugte MPUT-Nachricht zurück |
kcHttpGetPath
| liefert den mit normierten Path des HTTP-Requests zurück |
kcHttpGetQuery
| liefert die mit normierte Query des HTTP-Requests zurück |
kcHttpGetRc2String
| Hilfsfunktion zur Umwandlung eines Funktionsergebnisses vom Typ enum in einen abdruckbaren null-terminierten String |
kcHttpGetReqMsgBody
| liefert den Message Body des HTTP-Requests zurück |
kcHttpGetScheme
| liefert das Scheme des HTTP-Requests zurück |
kcHttpGetVersion
| liefert die HTTP-Version des HTTP-Requests zurück |
kcHttpPercentDecode
| wandelt Zeichen in Prozent-Darstellung in ihre normale Ein-Zeichen-Darstellung um |
kcHttpPutHeader
| übergibt ein HTTP-Header-Feld für die HTTP-Response |
kcHttpPutMgetMsg
| übergibt eine Nachricht für das Teilprogramm, die mit MGET gelesen werden kann |
kcHttpPutRspMsgBody
| übergibt eine Nachricht für den Message Body der HTTP-Response |
kcHttpPutStatus
| übergibt einen HTTP-Statuscode für die HTTP-Response |
Folgende Returncodes sind definiert:
typedef enum
{ KC_HTTP_OK = 0
, KC_HTTP_RESULT_TRUNCATED = -1
, KC_HTTP_FUNCTION_CALL_NOT_ALLOWED = -2
, KC_HTTP_NO_HTTP_CLIENT = -3
, KC_HTTP_INVALID_INDEX = -4
, KC_HTTP_HEADER_NAME_NULL_OR_EMPTY = -5
, KC_HTTP_HEADER_VALUE_NULL_OR_EMPTY = -6
, KC_HTTP_HEADER_NAME_TOO_LONG = -7
, KC_HTTP_HEADER_VALUE_TOO_LONG = -8
, KC_HTTP_PARAM_VALUE_NULL = -9
, KC_HTTP_INVALID_LENGTH = -10
, KC_HTTP_INVALID_STATUS_CODE = -11
, KC_HTTP_STATUS_CODE_NOT_ALLOWED = -12
, KC_HTTP_HEADER_NOT_FOUND = -13
, KC_HTTP_HEADER_NOT_ALLOWED = -14
, KC_HTTP_REASON_PHRASE_TOO_LONG = -15
, KC_HTTP_MEMORY_INSUFFICIENT = -16
, KC_HTTP_NORMALIZATION_ERROR = -17
, KC_HTTP_MAX_HEADER_COUNT = -18
, KC_HTTP_MAX_HEADER_TOTAL_LENGTH = -19
, KC_HTTP_HEADER_NAME_NOT_PRINTABLE = -20
, KC_HTTP_HEADER_VALUE_NOT_PRINTABLE = -21
, KC_HTTP_REASON_PHRASE_NOT_PRINTABLE = -22
, KC_HTTP_PARAM_INVALID_URLSTRING = -23
} kc_http_retcode;
Bei der Beschreibung der einzelnen Funktionen werden die Funktionsparameter wie folgt gekennzeichnet:
| >> | Eingabeparameter | Eingabewert oder Adresse, die beim Funktionsaufruf einen Eingabewert enthält. |
| << | Ausgabeparameter | Adresse, die beim Funktionsaufruf einen beliebigen Wert und nach Rückkehr von der Funktion einen Ausgabewert enthält. |
| <> | Ein-/Ausgabeparameter | Adresse, die beim Funktionsaufruf einen Eingabewert und nach Rückkehr von der Funktion einen Ausgabewert enthält. |
In den folgenden Kapiteln werden die einzelnen Funktionen detailliert beschrieben.