HttpRequest C Library Reference

HttpRequest

Represents a complete HTTP request.

Create/Dispose

HCkHttpRequest CkHttpRequest_Create(void);

Creates an instance of the CkHttpRequest object and returns a handle (i.e. a "void *" pointer). The handle is passed in the 1st argument for the functions listed on this page.

void CkHttpRequest_Dispose(HCkHttpRequest handle);

Objects created by calling CkHttpRequest_Create must be freed by calling this method. A memory leak occurs if a handle is not disposed by calling this function.

C "Properties"

void CkHttpRequest_getCharset(HCkHttpRequest handle, HCkString retval);
void CkHttpRequest_putCharset(HCkHttpRequest handle, const char *newVal);

Controls the character encoding used for HTTP request parameters for POST requests. The default value is "utf-8". The charset should match the charset expected by the form target.

void CkHttpRequest_getHttpVersion(HCkHttpRequest handle, HCkString retval);
void CkHttpRequest_putHttpVersion(HCkHttpRequest handle, const char *newVal);

The HTTP version in the request header. Defaults to "1.1".

void CkHttpRequest_getLastErrorHtml(HCkHttpRequest handle, HCkString retval);

Error information in HTML format for the last method called.

void CkHttpRequest_getLastErrorText(HCkHttpRequest handle, HCkString retval);

Error information in plain-text format for the last method called.

void CkHttpRequest_getLastErrorXml(HCkHttpRequest handle, HCkString retval);

Error information in XML format for the last method called.

int CkHttpRequest_getNumHeaderFields(HCkHttpRequest handle);

Returns the number of request header fields.

int CkHttpRequest_getNumParams(HCkHttpRequest handle);

Returns the number of query parameters.

void CkHttpRequest_getPath(HCkHttpRequest handle, HCkString retval);
void CkHttpRequest_putPath(HCkHttpRequest handle, const char *newVal);

The path of the resource requested. A path of "/" indicates the default document for a domain.

BOOL CkHttpRequest_getSendCharset(HCkHttpRequest handle);
void CkHttpRequest_putSendCharset(HCkHttpRequest handle, BOOL newVal);

Controls whether the charset is explicitly included in the content-type header field of the HTTP POST request.

BOOL CkHttpRequest_getUtf8(HCkHttpRequest handle);
void CkHttpRequest_putUtf8(HCkHttpRequest handle, BOOL newVal);

When set to true, all "const char *" arguments are expected to be utf-8 strings. If set to false, the "const char *" arguments are expected to be ANSI strings.

C "Methods"

BOOL CkHttpRequest_AddFileForUpload(HCkHttpRequest handle, const char *name, const char *filename);

Adds a file to an upload request. To create a file upload request, call UseUpload and then call AddFileForUpload for each file to be uploaded.

void CkHttpRequest_AddHeader(HCkHttpRequest handle, const char *name, const char *value);

Adds a request header to the HTTP request. If a header having the same field name is already present, this method replaces it.

void CkHttpRequest_AddParam(HCkHttpRequest handle, const char *name, const char *value);

Adds a request query parameter (name/value pair) to the HTTP request. The name and value strings passed to this method should not be URL encoded.

void CkHttpRequest_GenerateRequestText(HCkHttpRequest handle, HCkString str);

Returns the request text that would be sent if Http.SynchronousRequest was called.

BOOL CkHttpRequest_GetHeaderField(HCkHttpRequest handle, const char *name, HCkString str);

Returns the value of a request header field.

BOOL CkHttpRequest_GetHeaderName(HCkHttpRequest handle, int index, HCkString str);

Returns the Nth request header field name. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.

BOOL CkHttpRequest_GetHeaderValue(HCkHttpRequest handle, int index, HCkString str);

Returns the Nth request header field value. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.

BOOL CkHttpRequest_GetParam(HCkHttpRequest handle, const char *name, HCkString str);

Returns a request query parameter value by name.

BOOL CkHttpRequest_GetParamName(HCkHttpRequest handle, int index, HCkString str);

Returns the Nth request query parameter field name. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.

BOOL CkHttpRequest_GetParamValue(HCkHttpRequest handle, int index, HCkString str);

Returns the Nth request query parameter field value. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.

BOOL CkHttpRequest_LoadBodyFromBytes(HCkHttpRequest handle, HCkByteData binaryData);

To be documented soon...

BOOL CkHttpRequest_LoadBodyFromFile(HCkHttpRequest handle, const char *filename);

To be documented soon...

BOOL CkHttpRequest_LoadBodyFromString(HCkHttpRequest handle, const char *bodyStr);

To be documented soon...

void CkHttpRequest_RemoveAllParams(HCkHttpRequest handle);

Removes all request parameters.

void CkHttpRequest_RemoveParam(HCkHttpRequest handle, const char *name);

Removes a single HTTP request parameter by name.

BOOL CkHttpRequest_SaveLastError(HCkHttpRequest handle, const char *filename);

Saves the last error information to an XML formatted file.

void CkHttpRequest_SetFromUrl(HCkHttpRequest handle, const char *url);

Parses a URL and sets the Path and query parameters (NumParams, GetParam, GetParamName, GetParamValue).

void CkHttpRequest_UseGet(HCkHttpRequest handle);

Makes the HttpRequest a GET request.

void CkHttpRequest_UseHead(HCkHttpRequest handle);

Makes the HttpRequest a HEAD request.

void CkHttpRequest_UsePost(HCkHttpRequest handle);

Makes the HttpRequest a POST request that uses the "application/x-www-form-urlencoded" content type.

void CkHttpRequest_UseUpload(HCkHttpRequest handle);

Makes the HttpRequest a POST request that uses the "multipart/form-data" content type. To create a file upload request, call UseUpload and then call AddFileForUpload for each file to be uploaded.

void CkHttpRequest_UseXmlHttp(HCkHttpRequest handle, const char *xmlBody);

Makes the HttpRequest a POST request using the "text/xml" content type. The request body is set to the XML string passed to this method.

const char *CkHttpRequest_charset(HCkHttpRequest handle);

Controls the character encoding used for HTTP request parameters for POST requests. The default value is "utf-8". The charset should match the charset expected by the form target.

const char *CkHttpRequest_getHeaderField(HCkHttpRequest handle, const char *name);

Returns the value of a request header field.

const char *CkHttpRequest_getHeaderName(HCkHttpRequest handle, int index);

Returns the Nth request header field name. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.

const char *CkHttpRequest_getHeaderValue(HCkHttpRequest handle, int index);

Returns the Nth request header field value. Indexing begins at 0, and the number of request header fields is specified by the NumHeaderFields property.

const char *CkHttpRequest_getParam(HCkHttpRequest handle, const char *name);

Returns a request query parameter value by name.

const char *CkHttpRequest_getParamName(HCkHttpRequest handle, int index);

Returns the Nth request query parameter field name. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.

const char *CkHttpRequest_getParamValue(HCkHttpRequest handle, int index);

Returns the Nth request query parameter field value. Indexing begins at 0, and the number of request query parameter fields is specified by the NumParams property.

const char *CkHttpRequest_httpVersion(HCkHttpRequest handle);

The HTTP version in the request header. Defaults to "1.1".

const char *CkHttpRequest_lastErrorHtml(HCkHttpRequest handle);

Error information in HTML format for the last method called.

const char *CkHttpRequest_lastErrorText(HCkHttpRequest handle);

Error information in plain-text format for the last method called.

const char *CkHttpRequest_lastErrorXml(HCkHttpRequest handle);

Error information in XML format for the last method called.

const char *CkHttpRequest_path(HCkHttpRequest handle);

The path of the resource requested. A path of "/" indicates the default document for a domain.