HttpRequest C Reference Documentation

HttpRequest

Current Version: 9.5.0.73

Represents a complete HTTP request.

Create/Dispose

HCkHttpRequest instance = CkHttpRequest_Create();
// ...
CkHttpRequest_Dispose(instance);
HCkHttpRequest CkHttpRequest_Create(void);

Creates an instance of the HCkHttpRequest object and returns a handle ("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. Also, any handle returned by a Chilkat "C" function must also be freed by the application by calling the appropriate Dispose method, such as CkHttpRequest_Dispose.

Properties

Boundary
void CkHttpRequest_getBoundary(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putBoundary(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_boundary(HCkHttpRequest cHandle);
Introduced in version 9.5.0.49

Sets an explicit boundary string to be used in multipart/form-data requests. If no Boundary is set, then a boundary string is automaticaly generated as needed during the sending of a request.

More Information and Examples
top
Charset
void CkHttpRequest_getCharset(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putCharset(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_charset(HCkHttpRequest cHandle);

Controls the character encoding used for HTTP request parameters for POST requests. The default value is the ANSI charset of the computer. The charset should match the charset expected by the form target.

The "charset" attribute is only included in the Content-Type header of the request if the SendCharset property is set to TRUE.

top
ContentType
void CkHttpRequest_getContentType(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putContentType(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_contentType(HCkHttpRequest cHandle);

The ContentType property sets the "Content-Type" header field, and identifies the content-type of the HTTP request body. Common values are:

application/x-www-form-urlencoded
multipart/form-data
application/json
application/xml
If ContentType is set equal to the empty string, then no Content-Type header is included in the HTTP request.

top
DebugLogFilePath
void CkHttpRequest_getDebugLogFilePath(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putDebugLogFilePath(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_debugLogFilePath(HCkHttpRequest cHandle);

If set to a file path, causes each Chilkat method or property call to automatically append it's LastErrorText to the specified log file. The information is appended such that if a hang or crash occurs, it is possible to see the context in which the problem occurred, as well as a history of all Chilkat calls up to the point of the problem. The VerboseLogging property can be set to provide more detailed information.

This property is typically used for debugging the rare cases where a Chilkat method call hangs or generates an exception that halts program execution (i.e. crashes). A hang or crash should generally never happen. The typical causes of a hang are:

  1. a timeout related property was set to 0 to explicitly indicate that an infinite timeout is desired,
  2. the hang is actually a hang within an event callback (i.e. it is a hang within the application code), or
  3. there is an internal problem (bug) in the Chilkat code that causes the hang.

top
EntireHeader
void CkHttpRequest_getEntireHeader(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putEntireHeader(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_entireHeader(HCkHttpRequest cHandle);

Composes and returns the entire MIME header of the HTTP request.

top
HttpVerb
void CkHttpRequest_getHttpVerb(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putHttpVerb(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_httpVerb(HCkHttpRequest cHandle);

The HttpVerb property should be set to the name of the HTTP method that appears on the "start line" of an HTTP request, such as GET, POST, PUT, DELETE, etc. It is also possible to use the various WebDav verbs such as PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, etc. In general, the HttpVerb may be set to anything, even custom verbs recognized by a custom server-side app.

top
HttpVersion
void CkHttpRequest_getHttpVersion(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putHttpVersion(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_httpVersion(HCkHttpRequest cHandle);

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

top
LastErrorHtml
void CkHttpRequest_getLastErrorHtml(HCkHttpRequest cHandle, HCkString retval);
const char *CkHttpRequest_lastErrorHtml(HCkHttpRequest cHandle);

Provides information in HTML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorText
void CkHttpRequest_getLastErrorText(HCkHttpRequest cHandle, HCkString retval);
const char *CkHttpRequest_lastErrorText(HCkHttpRequest cHandle);

Provides information in plain-text format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastErrorXml
void CkHttpRequest_getLastErrorXml(HCkHttpRequest cHandle, HCkString retval);
const char *CkHttpRequest_lastErrorXml(HCkHttpRequest cHandle);

Provides information in XML format about the last method/property called. If a method call returns a value indicating failure, or behaves unexpectedly, examine this property to get more information.

top
LastMethodSuccess
BOOL CkHttpRequest_getLastMethodSuccess(HCkHttpRequest cHandle);
void CkHttpRequest_putLastMethodSuccess(HCkHttpRequest cHandle, BOOL newVal);
Introduced in version 9.5.0.52

Indicate whether the last method call succeeded or failed. A value of TRUE indicates success, a value of FALSE indicates failure. This property is automatically set for method calls. It is not modified by property accesses. The property is automatically set to indicate success for the following types of method calls:

  • Any method that returns a string.
  • Any method returning a Chilkat object, binary bytes, or a date/time.
  • Any method returning a standard boolean status value where success = TRUE and failure = FALSE.
  • Any method returning an integer where failure is defined by a return value less than zero.

Note: Methods that do not fit the above requirements will always set this property equal to TRUE. For example, a method that returns no value (such as a "void" in C++) will technically always succeed.

top
NumHeaderFields
int CkHttpRequest_getNumHeaderFields(HCkHttpRequest cHandle);

Returns the number of request header fields.

top
NumParams
int CkHttpRequest_getNumParams(HCkHttpRequest cHandle);

Returns the number of query parameters.

More Information and Examples
top
Path
void CkHttpRequest_getPath(HCkHttpRequest cHandle, HCkString retval);
void CkHttpRequest_putPath(HCkHttpRequest cHandle, const char *newVal);
const char *CkHttpRequest_path(HCkHttpRequest cHandle);

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

More Information and Examples
top
SendCharset
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. The default value of this property is FALSE.

top
Utf8
BOOL CkHttpRequest_getUtf8(HCkHttpRequest cHandle);
void CkHttpRequest_putUtf8(HCkHttpRequest cHandle, BOOL newVal);

When set to TRUE, all "const char *" arguments are interpreted as utf-8 strings. If set to FALSE (the default), then "const char *" arguments are interpreted as ANSI strings. Also, when set to TRUE, and Chilkat method returning a "const char *" is returning the utf-8 representation. If set to FALSE, all "const char *" return values are ANSI strings.

top
VerboseLogging
BOOL CkHttpRequest_getVerboseLogging(HCkHttpRequest cHandle);
void CkHttpRequest_putVerboseLogging(HCkHttpRequest cHandle, BOOL newVal);

If set to TRUE, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is FALSE. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.

top
Version
void CkHttpRequest_getVersion(HCkHttpRequest cHandle, HCkString retval);
const char *CkHttpRequest_version(HCkHttpRequest cHandle);

Version of the component/library, such as "9.5.0.63"

top

Methods

AddBytesForUpload
BOOL CkHttpRequest_AddBytesForUpload(HCkHttpRequest cHandle, const char *name, const char *remoteFileName, 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.

Returns TRUE for success, FALSE for failure.

top
AddBytesForUpload2
BOOL CkHttpRequest_AddBytesForUpload2(HCkHttpRequest cHandle, const char *name, const char *remoteFileName, 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.)

Returns TRUE for success, FALSE for failure.

top
AddFileForUpload
BOOL CkHttpRequest_AddFileForUpload(HCkHttpRequest cHandle, const char *name, const char *filePath);

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.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
AddFileForUpload2
BOOL CkHttpRequest_AddFileForUpload2(HCkHttpRequest cHandle, const char *name, const char *filePath, 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.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
AddHeader
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.

Note: Never explicitly set the Content-Length header field. Chilkat will automatically compute the correct length and add the Content-Length header to all POST, PUT, or any other request where the Content-Length needs to be specified. (GET requests always have a 0 length body, and therefore never need a Content-Length header field.)

More Information and Examples
top
AddMwsSignature
BOOL CkHttpRequest_AddMwsSignature(HCkHttpRequest cHandle, const char *domain, const char *mwsSecretKey);
Introduced in version 9.5.0.66

Computes the Amazon MWS signature using the mwsSecretKey and adds the "Signature" parameter to the request. This method should be called for all Amazon Marketplace Web Service (Amazon MWS) HTTP requests. It should be called after all request parameters have been added.

The domain should be the domain of the request, such as one of the following:

  • mws.amazonservices.com
  • mws-eu.amazonservices.com
  • mws.amazonservices.in
  • mws.amazonservices.com.cn
  • mws.amazonservices.jp

Note: This method automatically adds or replaces the existing Timestamp parameter to the current system date/time.

Returns TRUE for success, FALSE for failure.

top
AddParam
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.

top
AddStringForUpload
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.

Returns TRUE for success, FALSE for failure.

top
AddStringForUpload2
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 filename's file extension.)

Returns TRUE for success, FALSE for failure.

top
AddSubHeader
BOOL CkHttpRequest_AddSubHeader(HCkHttpRequest cHandle, int index, const char *name, const char *value);
Introduced in version 9.5.0.55

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

Returns TRUE for success, FALSE for failure.

top
GenerateRequestFile
BOOL CkHttpRequest_GenerateRequestFile(HCkHttpRequest cHandle, const char *path);
Introduced in version 9.5.0.64

The same as GenerateRequestText, except the generated request is written to the file specified by path.

Returns TRUE for success, FALSE for failure.

top
GenerateRequestText
BOOL CkHttpRequest_GenerateRequestText(HCkHttpRequest cHandle, HCkString outStr);
const char *CkHttpRequest_generateRequestText(HCkHttpRequest cHandle);

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

Returns TRUE for success, FALSE for failure.

top
GetHeaderField
BOOL CkHttpRequest_GetHeaderField(HCkHttpRequest cHandle, const char *name, HCkString outStr);
const char *CkHttpRequest_getHeaderField(HCkHttpRequest cHandle, const char *name);

Returns the value of a request header field.

Returns TRUE for success, FALSE for failure.

top
GetHeaderName
BOOL CkHttpRequest_GetHeaderName(HCkHttpRequest cHandle, int index, HCkString outStr);
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 TRUE for success, FALSE for failure.

top
GetHeaderValue
BOOL CkHttpRequest_GetHeaderValue(HCkHttpRequest cHandle, int index, HCkString outStr);
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 TRUE for success, FALSE for failure.

top
GetParam
BOOL CkHttpRequest_GetParam(HCkHttpRequest cHandle, const char *name, HCkString outStr);
const char *CkHttpRequest_getParam(HCkHttpRequest cHandle, const char *name);

Returns a request query parameter value by name.

Returns TRUE for success, FALSE for failure.

top
GetParamName
BOOL CkHttpRequest_GetParamName(HCkHttpRequest cHandle, int index, HCkString outStr);
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 TRUE for success, FALSE for failure.

More Information and Examples
top
GetParamValue
BOOL CkHttpRequest_GetParamValue(HCkHttpRequest cHandle, int index, HCkString outStr);
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 TRUE for success, FALSE for failure.

More Information and Examples
top
GetUrlEncodedParams
BOOL CkHttpRequest_GetUrlEncodedParams(HCkHttpRequest cHandle, HCkString outStr);
const char *CkHttpRequest_getUrlEncodedParams(HCkHttpRequest cHandle);

Returns the request parameters in URL encoded form (i.e. in the exact form that would be sent if the ContentType property was application/x-www-form-urlencoded). For example, if a request has two params: param1="abc 123" and param2="abc-123", then GetUrlEncodedParams would return "abc+123

Returns TRUE for success, FALSE for failure.

top
LoadBodyFromBd
BOOL CkHttpRequest_LoadBodyFromBd(HCkHttpRequest cHandle, HCkBinData requestBody);
Introduced in version 9.5.0.67

Uses the contents of the requestBody as the HTTP request body.

Returns TRUE for success, FALSE for failure.

top
LoadBodyFromBytes
BOOL CkHttpRequest_LoadBodyFromBytes(HCkHttpRequest cHandle, HCkByteData byteData);

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.

Returns TRUE for success, FALSE for failure.

top
LoadBodyFromFile
BOOL CkHttpRequest_LoadBodyFromFile(HCkHttpRequest cHandle, const char *filePath);

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.

Returns TRUE for success, FALSE for failure.

top
LoadBodyFromSb
BOOL CkHttpRequest_LoadBodyFromSb(HCkHttpRequest cHandle, HCkStringBuilder requestBody, const char *charset);
Introduced in version 9.5.0.67

Uses the contents of the requestBody as the HTTP request body. The charset indicates the binary representation of the string, such as "utf-8", "utf-16", "iso-8859-*", "windows-125*", etc. Any of the character encodings supported at the link below are valid.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
LoadBodyFromString
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.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
RemoveAllParams
void CkHttpRequest_RemoveAllParams(HCkHttpRequest cHandle);

Removes all request parameters.

More Information and Examples
top
RemoveHeader
BOOL CkHttpRequest_RemoveHeader(HCkHttpRequest cHandle, const char *name);

Removes all occurrences of a HTTP request header field. Always returns TRUE.

Returns TRUE for success, FALSE for failure.

top
RemoveParam
void CkHttpRequest_RemoveParam(HCkHttpRequest cHandle, const char *name);

Removes a single HTTP request parameter by name.

More Information and Examples
top
SaveLastError
BOOL CkHttpRequest_SaveLastError(HCkHttpRequest cHandle, const char *path);

Saves the last-error information (the contents of LastErrorXml) to an XML formatted file.

Returns TRUE for success, FALSE for failure.

top
SetFromUrl
void CkHttpRequest_SetFromUrl(HCkHttpRequest cHandle, const char *url);

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

More Information and Examples
top
StreamBodyFromFile
BOOL CkHttpRequest_StreamBodyFromFile(HCkHttpRequest cHandle, const char *filePath);

Useful for sending HTTP requests where the body is a very large file. For example, to send an XML HttpRequest containing a very large XML document, one would set the HttpVerb = "POST", the ContentType = "text/xml", and then call StreamBodyFromFile to indicate that the XML body of the request is to be streamed directly from a file. When the HTTP request is actually sent, the body is streamed directly from the file, and thus the file never needs to be loaded in its entirety in memory.

Returns TRUE for success, FALSE for failure.

More Information and Examples
top
StreamChunkFromFile
BOOL CkHttpRequest_StreamChunkFromFile(HCkHttpRequest cHandle, const char *path, const char *offset, const char *numBytes);
Introduced in version 9.5.0.55

This method is the same as StreamBodyFromFile, but allows for an offset and number of bytes to be specified. The offset and numBytes are integers passed as strings.

Returns TRUE for success, FALSE for failure.

top
UseGet
void CkHttpRequest_UseGet(HCkHttpRequest cHandle);
This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a GET request.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "GET", and the ContentType equal to an empty string (because GET requests have no request body).

top
UseHead
void CkHttpRequest_UseHead(HCkHttpRequest cHandle);
This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a HEAD request.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "HEAD", and the ContentType equal to an empty string (because HEAD requests have no body).

top
UsePost
void CkHttpRequest_UsePost(HCkHttpRequest cHandle);
This method is deprecated. It will be removed in a future version.

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

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", and the ContentType equal to "application/x-www-form-urlencoded".

top
UsePostMultipartForm
void CkHttpRequest_UsePostMultipartForm(HCkHttpRequest cHandle);
This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a POST request that uses the "multipart/form-data" content type.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", and the ContentType equal to "multipart/form-data".

top
UsePut
void CkHttpRequest_UsePut(HCkHttpRequest cHandle);
This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a PUT request.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "PUT", and the ContentType equal to "application/x-www-form-urlencoded".

top
UseUpload
void CkHttpRequest_UseUpload(HCkHttpRequest cHandle);
This method is deprecated. It will be removed in a future version.

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.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", and the ContentType equal to "multipart/form-data".

top
UseUploadPut
void CkHttpRequest_UseUploadPut(HCkHttpRequest cHandle);
This method is deprecated. It will be removed in a future version.

Makes the HttpRequest a PUT request that uses the "multipart/form-data" content type. To create a file upload request (using the PUT verb), call UseUploadPut and then call AddFileForUpload for each file to be uploaded.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "PUT", and the ContentType equal to "multipart/form-data".

top
UseXmlHttp
void CkHttpRequest_UseXmlHttp(HCkHttpRequest cHandle, const char *xmlBody);
This method is deprecated. It will be removed in a future version.

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.

Important: This method is deprecated. An application should instead set the HttpVerb property equal to "POST", the ContentType equal to "text/xml", and the request body should contain the XML document text.

top