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 cHandle, HCkString retval);
void CkHttpRequest_putCharset(HCkHttpRequest cHandle, 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_getContentType(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putContentType(HCkHttpRequest cHandle, const char *newVal);
To be documented soon...
void CkHttpRequest_getEntireHeader(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putEntireHeader(HCkHttpRequest cHandle, const char *newVal);
To be documented soon...
void CkHttpRequest_getHttpVerb(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putHttpVerb(HCkHttpRequest cHandle, const char *newVal);
To be documented soon...
void CkHttpRequest_getHttpVersion(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putHttpVersion(HCkHttpRequest cHandle, const char *newVal);
The HTTP version in the request header. Defaults to "1.1".
void CkHttpRequest_getLastErrorHtml(HCkHttpRequest cHandle, HCkString retval);
Error information in HTML format for the last method called.
void CkHttpRequest_getLastErrorText(HCkHttpRequest cHandle, HCkString retval);
Error information in plain-text format for the last method called.
void CkHttpRequest_getLastErrorXml(HCkHttpRequest cHandle, HCkString retval);
Error information in XML format for the last method called.
int CkHttpRequest_getNumHeaderFields(HCkHttpRequest cHandle);
Returns the number of request header fields.
int CkHttpRequest_getNumParams(HCkHttpRequest cHandle);
Returns the number of query parameters.
void CkHttpRequest_getPath(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putPath(HCkHttpRequest cHandle, const char *newVal);
The path of the resource requested. A path of "/" indicates the default document for a domain.
BOOL CkHttpRequest_getSendCharset(HCkHttpRequest cHandle);
void CkHttpRequest_putSendCharset(HCkHttpRequest cHandle, BOOL newVal);
Controls whether the charset is explicitly included in the content-type header field of the HTTP POST request.
BOOL CkHttpRequest_getUtf8(HCkHttpRequest cHandle);
void CkHttpRequest_putUtf8(HCkHttpRequest cHandle, 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_AddBytesForUpload(HCkHttpRequest cHandle, const char *name, const char *filename, HCkByteData byteData);
Adds a file to an upload request where the contents of the file come from an in-memory byte array. To create a file upload request, call UseUpload and then call AddBytesForUpload, AddStringForUpload, or AddFileForUpload for each file to be uploaded.
name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
remoteFileName is the name of the file to be created on the HTTP server.
byteData contains the contents (bytes) to be uploaded.
BOOL CkHttpRequest_AddBytesForUpload2(HCkHttpRequest cHandle, const char *name, const char *filename, HCkByteData byteData, const char *contentType);
Same as AddBytesForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the remoteFileName's file extension.)
BOOL CkHttpRequest_AddFileForUpload(HCkHttpRequest cHandle, 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, AddBytesForUpload, or AddStringForUpload for each file to be uploaded. This method does not read the file into memory. When the upload occurs, the data is streamed directly from the file, thus allowing for very large files to be uploaded without consuming large amounts of memory.
name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
filePath is the path to an existing file in the local filesystem.
BOOL CkHttpRequest_AddFileForUpload2(HCkHttpRequest cHandle, const char *name, const char *filename, const char *contentType);
Same as AddFileForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the file extension.)
name is an arbitrary name. (In HTML, it is the form field name of the input tag.)
filePath is the path to an existing file in the local filesystem.
void CkHttpRequest_AddHeader(HCkHttpRequest cHandle, 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 cHandle, 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.
BOOL CkHttpRequest_AddStringForUpload(HCkHttpRequest cHandle, const char *name, const char *filename, const char *strData, const char *charset);
Same as AddFileForUpload, but the upload data comes from an in-memory string instead of a file.
BOOL CkHttpRequest_AddStringForUpload2(HCkHttpRequest cHandle, const char *name, const char *filename, const char *strData, const char *charset, const char *contentType);
Same as AddStringForUpload, but allows the Content-Type header field to be directly specified. (Otherwise, the Content-Type header is automatically determined based on the ARG2's file extension.)
void CkHttpRequest_GenerateRequestText(HCkHttpRequest cHandle, HCkString outStr);
Returns the request text that would be sent if Http.SynchronousRequest was called.
BOOL CkHttpRequest_GetHeaderField(HCkHttpRequest cHandle, const char *name, HCkString outStr);
Returns the value of a request header field.
BOOL CkHttpRequest_GetHeaderName(HCkHttpRequest cHandle, int index, HCkString outStr);
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 cHandle, int index, HCkString outStr);
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 cHandle, const char *name, HCkString outStr);
Returns a request query parameter value by name.
BOOL CkHttpRequest_GetParamName(HCkHttpRequest cHandle, int index, HCkString outStr);
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 cHandle, int index, HCkString outStr);
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_GetUrlEncodedParams(HCkHttpRequest cHandle, HCkString outStr);
To be documented soon.
BOOL CkHttpRequest_LoadBodyFromBytes(HCkHttpRequest cHandle, HCkByteData binaryData);
The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of the byteData.
Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.
BOOL CkHttpRequest_LoadBodyFromFile(HCkHttpRequest cHandle, const char *filename);
The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of filePath.
Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.
BOOL CkHttpRequest_LoadBodyFromString(HCkHttpRequest cHandle, const char *bodyStr, const char *charset);
The HTTP protocol is such that all HTTP requests are MIME. For non-multipart requests, this method may be called to set the MIME body of the HTTP request to the exact contents of bodyStr.
Note: A non-multipart HTTP request consists of (1) the HTTP start line, (2) MIME header fields, and (3) the MIME body. This method sets the MIME body.
charset indicates the charset, such as "utf-8" or "iso-8859-1", to be used. The HTTP body will contain the bodyStr converted to this character encoding.
void CkHttpRequest_RemoveAllParams(HCkHttpRequest cHandle);
Removes all request parameters.
void CkHttpRequest_RemoveParam(HCkHttpRequest cHandle, const char *name);
Removes a single HTTP request parameter by name.
BOOL CkHttpRequest_SaveLastError(HCkHttpRequest cHandle, const char *filename);
Saves the last error information to an XML formatted file.
void CkHttpRequest_SetFromUrl(HCkHttpRequest cHandle, const char *url);
Parses a URL and sets the Path and query parameters (NumParams, GetParam, GetParamName, GetParamValue).
BOOL CkHttpRequest_StreamBodyFromFile(HCkHttpRequest cHandle, const char *filename);
To be documented soon...
void CkHttpRequest_UseGet(HCkHttpRequest cHandle);
Makes the HttpRequest a GET request.
void CkHttpRequest_UseHead(HCkHttpRequest cHandle);
Makes the HttpRequest a HEAD request.
void CkHttpRequest_UsePost(HCkHttpRequest cHandle);
Makes the HttpRequest a POST request that uses the "application/x-www-form-urlencoded" content type.
void CkHttpRequest_UsePostMultipartForm(HCkHttpRequest cHandle);
Makes the HttpRequest a POST request that uses the "multipart/form-data" content type.
void CkHttpRequest_UsePut(HCkHttpRequest cHandle);
Makes the HttpRequest a PUT request.
void CkHttpRequest_UseUpload(HCkHttpRequest cHandle);
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_UseUploadPut(HCkHttpRequest cHandle);
To be documented soon...
void CkHttpRequest_UseXmlHttp(HCkHttpRequest cHandle, const char *xmlBody);
Makes the HttpRequest a POST request using the "application/xml" content type. The request body is set to the XML string passed to this method.
const char *CkHttpRequest_charset(HCkHttpRequest cHandle);
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. Returns a null on failure
const char *CkHttpRequest_contentType(HCkHttpRequest cHandle);
To be documented soon...
const char *CkHttpRequest_entireHeader(HCkHttpRequest cHandle);
To be documented soon...
const char *CkHttpRequest_generateRequestText(HCkHttpRequest cHandle);
Returns the request text that would be sent if Http.SynchronousRequest was called. Returns a null on failure
const char *CkHttpRequest_getHeaderField(HCkHttpRequest cHandle, const char *name);
Returns the value of a request header field. Returns a null on failure
const char *CkHttpRequest_getHeaderName(HCkHttpRequest cHandle, 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. Returns a null on failure
const char *CkHttpRequest_getHeaderValue(HCkHttpRequest cHandle, 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. Returns a null on failure
const char *CkHttpRequest_getParam(HCkHttpRequest cHandle, const char *name);
Returns a request query parameter value by name. Returns a null on failure
const char *CkHttpRequest_getParamName(HCkHttpRequest cHandle, 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. Returns a null on failure
const char *CkHttpRequest_getParamValue(HCkHttpRequest cHandle, 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. Returns a null on failure
const char *CkHttpRequest_getUrlEncodedParams(HCkHttpRequest cHandle);
To be documented soon. Returns a null on failure
const char *CkHttpRequest_httpVerb(HCkHttpRequest cHandle);
To be documented soon...
const char *CkHttpRequest_httpVersion(HCkHttpRequest cHandle);
The HTTP version in the request header. Defaults to "1.1". Returns a null on failure
const char *CkHttpRequest_lastErrorHtml(HCkHttpRequest cHandle);
Error information in HTML format for the last method called.Returns a null on failure
const char *CkHttpRequest_lastErrorText(HCkHttpRequest cHandle);
Error information in plain-text format for the last method called.Returns a null on failure
const char *CkHttpRequest_lastErrorXml(HCkHttpRequest cHandle);
Error information in XML format for the last method called.Returns a null on failure
const char *CkHttpRequest_path(HCkHttpRequest cHandle);
The path of the resource requested. A path of "/" indicates the default document for a domain. Returns a null on failure
|