Overview of all UTM-HTTP functions

The functions of the UTM-HTTP program interface are divided into two groups, the kcHttpGet and the kcHttpPut functions. They can be called both by an HTTP exit program (see chapter "Event Exit HTTP") and - with exception of the functions kcHttpGetMputMsg, kcHttpPutMgetMsg, kcHttpPutRspMsgBody - by UTM program units.
Furthermore there are the two auxiliary functions kcHttpPercentDecode and kcHttpGetRc2String.

UTM program units may call these functions not before the KDCS call INIT. The kcHttpGet functions may only called in the first program unit run of a (not chained) service.
If a program unit calls the functions kcHttpPutHeader or kcHttpPutStatus, it also has to supply a message for the HTTP client with MPUT and has to finish the service, else the provided status or header information will be lost.
For use of these functions in the HTTP exit program see chapter "Event Exit HTTP"  .

Input parameters of the C functions that are of type char * must be passed by the caller as a null-terminated string. UTM also returns null-terminated strings in output parameters of type char *.

If the execution was not successful all functions except the help function  kcHttpGetRc2String  return negative number constants defined as C data type enum as function result. If the execution was successful, either the number constant 0 or a positive function value is returned.

The following functions are available:

Function	Description
kcHttpGetHeaderByIndex	returns name and value of the HTTP header field  with the specified index
kcHttpGetHeaderByName	returns the value of HTTP header field with the specified HTTP header name
kcHttpGetHeaderCount	returns the number of HTTP header fields of the HTTP request
kcHttpGetMethod	returns the HTTP method of the HTTP request
kcHttpGetMputMsg	returns the MPUT message created by the program unit
kcHttpGetPath	returns the normalized path of the HTTP request
kcHttpGetQuery	returns the normalized query of the HTTP request
kcHttpGetRc2String	Help function to convert a function result of type enum into a printable null-terminated string
kcHttpGetReqMsgBody	returns the message body of the HTTP request
kcHttpGetScheme	returns the scheme of the HTTP request
kcHttpGetVersion	returns the HTTP version of the HTTP request
kcHttpPercentDecode	converts characters in percent-decoding to their normal one-character representation
kcHttpPutHeader	passes an HTTP header field for the HTTP response
kcHttpPutMgetMsg	passes a message for the program unit which can be read with MGET
kcHttpPutRspMsgBody	passes a message for the message body of the HTTP response
kcHttpPutStatus	passes an HTTP status code for the HTTP response

The following returncodes are defined:

Returncodes

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;

In the description of the individual functions, the function parameters are identified as follows:

>>	Input parameter	Input value or an address containing an input value when the function is called.
<<	Output parameter	Address containing an arbitrary value when the function is called and an output value when the function returns.
<>	Input/Output parameter	Address containing an input value when the function is called and an output value when the function returns.

The individual functions are described in detail in the following chapters.