CkHttp Perl Reference Documentation

CkHttp

Class for sending HTTP requests and receiving server responses.

  • Supports GET, POST, HEAD, PUT, DELETE, WebDav, and custom HTTP request methods.
  • HTTP Authentication: Basic, NTLM, Digest, Negotiate
  • HTTPS (SSL/TLS) with client-side certificate capabilities.
  • Cookie caching, auto-resend, persisting to XML files.
  • Content caching.
  • Supports HTTP proxies
  • Auto-follow redirects if desired.
  • Amazon S3 methods.
  • XML HTTP Request
  • HTTP file upload capabilities
  • Asynchronous features -- putting HTTP requests in background threads.
  • Supports SOCK5/SOCKS4 proxies.
  • IPv6 capable.

Object Creation

$obj = new chilkat::CkHttp();

Properties

# $strVal is a string
# $ckStr is a CkString
$http->get_Accept($ckStr);
$strVal = $http->accept();
$http->put_Accept($strVal);

The Accept header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "*/*".

# $strVal is a string
# $ckStr is a CkString
$http->get_AcceptCharset($ckStr);
$strVal = $http->acceptCharset();
$http->put_AcceptCharset($strVal);

The AcceptCharset header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "ISO-8859-1,utf-8;q=0.7,*;q=0.7".

# $strVal is a string
# $ckStr is a CkString
$http->get_AcceptLanguage($ckStr);
$strVal = $http->acceptLanguage();
$http->put_AcceptLanguage($strVal);

The AcceptLanguage header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "en-us,en;q=0.5".

# $boolVal is an boolean
$boolVal = $http->get_AllowGzip();
$http->put_AllowGzip($boolVal);

Controls whether the "Accept-Encoding: gzip" header is added to HTTP requests sent via any method that sends an HTTP request without using the HttpRequest object (such as QuickGetStr). If 0, then the empty Accept-Encoding header is added which means the server response should contain the uncompressed content. The default value is 1, which means the server, if it chooses, may send a gzipped response.

# $boolVal is an boolean
$boolVal = $http->get_AutoAddHostHeader();
$http->put_AutoAddHostHeader($boolVal);

If set to true, the "Host" header field will automatically be added to the request header for any QuickGet or QuickGetStr method calls. The value of the Host header field is taken from the hostname part of the URL passed to QuickGet/QuickGetStr.

# $strVal is a string
# $ckStr is a CkString
$http->get_AwsAccessKey($ckStr);
$strVal = $http->awsAccessKey();
$http->put_AwsAccessKey($strVal);

The AWS Access Key to be used with the Amazon S3 methods listed below.

# $strVal is a string
# $ckStr is a CkString
$http->get_AwsEndpoint($ckStr);
$strVal = $http->awsEndpoint();
$http->put_AwsEndpoint($strVal);

The regional endpoint (domain) to be used for Amazon S3 method calls. The default value is "s3.amazonaws.com". This can be set to any valid Amazon S3 endpoint, such as "s3-eu-west-1.amazonaws.com", or the endpoints for S3-API compatible services from other different providers.

# $strVal is a string
# $ckStr is a CkString
$http->get_AwsSecretKey($ckStr);
$strVal = $http->awsSecretKey();
$http->put_AwsSecretKey($strVal);

The AWS Secret Key to be used with the Amazon S3 methods listed below.

# $strVal is a string
# $ckStr is a CkString
$http->get_AwsSubResources($ckStr);
$strVal = $http->awsSubResources();
$http->put_AwsSubResources($strVal);

The AWS sub-resources to be used with the Amazon S3 methods listed below.

If the S3 request needs to address a sub-resource, like ?versioning, ?policy, ?location, ?acl, or ?torrent, or ?versionid append the sub-resource and its value if it has one. Note that in case of multiple sub-resources, sub-resources must be lexicographically sorted by sub-resource name and separated by '&'. e.g. "acl&versionId=value"

The list of sub-resources that can be included are: acl, location, logging, notification, partNumber, policy, requestPayment, torrent, uploadId, uploads, versionId, versioning, versions and website.

# $boolVal is an boolean
$boolVal = $http->get_BasicAuth();
$http->put_BasicAuth($boolVal);

If HTTP basic authentication is needed, this property must be set to 1. The HTTP protocol allows for several different types of authentication schemes, such as NTLM, Digest, OAuth1, etc. A given server will support (or allow) certain authentication schemes (also known as authentication methods). Except for the "Basic" authentication method, the other forms of authentication do not involve sending the login and password in plain unencrypted text over the connection. The Basic authentication method is insecure in that it sends the login/password for all to see. If the connection is SSL/TLS, then this might be considered OK. Chilkat takes the safe approach and will not allow Basic authentication unless this property has been explicitly set to 1. The default value of this property is 0.

Note: It is not required to know the authentication methods accepted by the server beforehand (except for the case of Basic authentication). When authentication is required, Chilkat will first send the request without the Authorization header, receive back the 401 Authorization Required response along with information about what authentication methods are accepted, and then re-send with an accepted authentication method. If the authentication method is known in advance, then an application may set the appropriate property, such as NtlmAuth to 1 so that the extra (internal) round-trip is not required.

# $strVal is a string
# $ckStr is a CkString
$http->get_BgLastErrorText($ckStr);
$strVal = $http->bgLastErrorText();

When a background-enabled method is run asynchronously in a background thread, the last-error information is saved here and not in the LastErrorText property. If the background method fails, this will contain information about what transpired. (This property also contains information when the background method succeeds.)

More information on background enabling HTTP communications.

Example for background thread HTTP Download.

# $intVal is an integer
$intVal = $http->get_BgPercentDone();

The integer percent completed for a background HTTP method call. The value will be between 0 and 100 while a background method call is in progress. Otherwise, the value is meaningless. The BgPercentDone only applies in cases where it is possible to track completion by a percentage. If an HTTP response is chunked, then there is no way of knowing how much response data is forthcoming, and therefore it is not possible to track the percentage completed.

# $byteData is a CkByteData
# $ckBytes is a CkByteData
$http->get_BgResultData($ckBytes);

If a backgrounded method returns a byte array, the returned data is found here.

# $intVal is an integer
$intVal = $http->get_BgResultInt();

If a backgrounded method returns an integer, the return value is found here.

# $strVal is a string
# $ckStr is a CkString
$http->get_BgResultString($ckStr);
$strVal = $http->bgResultString();

If a backgrounded method returns a string, the return value is found here.

# $boolVal is an boolean
$boolVal = $http->get_BgTaskFinished();

Becomes 1 when the background method completes. Your application would periodically check for this condition.

More information on background enabling HTTP communications.

Example for background thread HTTP Download.

# $boolVal is an boolean
$boolVal = $http->get_BgTaskRunning();

If 1 then the object instance already has a backgrounded method running. Another backgrounded method cannot be started until the 1st completes. (Multiple simultaneous background methods may run by using multiple object instances.)

If 0, then no method is currently running in a background thread.

More information on background enabling HTTP communications.

Example for background thread HTTP Download.

# $boolVal is an boolean
$boolVal = $http->get_BgTaskSuccess();

This property's value is only meaningful (1 or 0) after a backgrounded method completes.

More information on background enabling HTTP communications.

Example for background thread HTTP Download.

# $strVal is a string
# $ckStr is a CkString
$http->get_ClientIpAddress($ckStr);
$strVal = $http->clientIpAddress();
$http->put_ClientIpAddress($strVal);

The IP address to use for computers with multiple network interfaces or IP addresses. For computers with a single network interface (i.e. most computers), this property should not be set. For multihoming computers, the default IP address is automatically used if this property is not set.

The IP address is a string such as in dotted notation using numbers, not domain names, such as "165.164.55.124".

Important Bind to Adapter Notes for Windows

# $intVal is an integer
$intVal = $http->get_ConnectTimeout();
$http->put_ConnectTimeout($intVal);

The amount of time in seconds to wait before timing out when connecting to an HTTP server.

# $strVal is a string
# $ckStr is a CkString
$http->get_Connection($ckStr);
$strVal = $http->connection();
$http->put_Connection($strVal);

The Connection header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "Keep-Alive". To prevent the Connection header from being added to the HTTP header, set this property to the empty string.

# $strVal is a string
# $ckStr is a CkString
$http->get_CookieDir($ckStr);
$strVal = $http->cookieDir();
$http->put_CookieDir($strVal);

Specifies a directory where cookies are automatically persisted if the Http.SaveCookies property is turned on. Cookies are stored in XML formatted files, one per domain, to main it easy for other programs to understand and parse. May be set to the string "memory" to cache cookies in memory.

Saving Cookies to XML Files

Caching cookies in-memory.

# $strVal is a string
# $ckStr is a CkString
$http->get_DebugLogFilePath($ckStr);
$strVal = $http->debugLogFilePath();
$http->put_DebugLogFilePath($strVal);

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.

# $intVal is an integer
$intVal = $http->get_DefaultFreshPeriod();
$http->put_DefaultFreshPeriod($intVal);

The default freshness period (in minutes) for cached documents when the FreshnessAlgorithm property is set to 0. The default value is 10080 (1 week).

# $boolVal is an boolean
$boolVal = $http->get_DigestAuth();
$http->put_DigestAuth($boolVal);

Setting this property to 1 causes the HTTP component to use digest authentication. The default value is 0.

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

# $intVal is an integer
$intVal = $http->get_EventLogCount();

If the KeepEventLog property is set to 1, then this property will contain the number of events that have accumulated in the in-memory event log. The events are indexed from 0 to EventLogCount-1. The ClearEventLog method may be called to clear the event log. The name and value of each event can be retrieved via the EventLogName and EventLogValue methods.

# $boolVal is an boolean
$boolVal = $http->get_FetchFromCache();
$http->put_FetchFromCache($boolVal);

Set to true if pages should be fetched from cache when possible. Only HTTP GET requests are cached. HTTP responses that include Set-Cookie headers are not cached. A page is fetched from the disk cache if it is present and it is "fresh" according to the FreshnessAlgorithm property. If a page exists in cache but is not fresh, the HTTP component will issue a revalidate request and update the cache appropriately according to the response.

# $strVal is a string
# $ckStr is a CkString
$http->get_FinalRedirectUrl($ckStr);
$strVal = $http->finalRedirectUrl();

If an HTTP GET was redirected (as indicated by the WasRedirected property), this property will contain the final redirect URL, assuming the FollowRedirects property is true.

Tracing HTTP Redirects

# $boolVal is an boolean
$boolVal = $http->get_FollowRedirects();
$http->put_FollowRedirects($boolVal);

If true, then 301 and 302 redirects are automatically followed when calling QuickGet and QuickGetStr. FollowRedirects is true by default.

# $intVal is an integer
$intVal = $http->get_FreshnessAlgorithm();
$http->put_FreshnessAlgorithm($intVal);

The freshness algorithm to use when determining the freshness of a cached HTTP GET response. A value of 1 causes an LM-factor algorithm to be used. This is the default. The LMFactor property is a value between 1 and 100 indicating the percentage of time based on the last-modified date of the HTML page. For example, if the LMFactor is 50, and an HTML page was modified 10 days ago, then the page will expire (i.e. no longer be fresh) in 5 days (50% of 10 days). This only applies to HTTP responses that do not have page expiration information. If the FreshnessAlgorithm = 0, then a constant expire time period determined by the DefaultFreshPeriod property is used.

# $boolVal is an boolean
$boolVal = $http->get_IgnoreMustRevalidate();
$http->put_IgnoreMustRevalidate($boolVal);

Some HTTP responses contain a "Cache-Control: must-revalidate" header. If this is present, the server is requesting that the client always issue a revalidate HTTP request instead of serving the page directly from cache. If IgnoreMustRevalidate is set to 1, then Chilkat HTTP will serve the page directly from cache without revalidating until the page is no longer fresh.

The default value of this property is 0.

# $boolVal is an boolean
$boolVal = $http->get_IgnoreNoCache();
$http->put_IgnoreNoCache($boolVal);

Some HTTP responses contain headers of various types that indicate that the page should not be cached. Chilkat HTTP will adhere to this unless this property is set to 1.

The default value of this property is 0.

# $boolVal is an boolean
$boolVal = $http->get_KeepEventLog();
$http->put_KeepEventLog($boolVal);

If 1, an in-memory event log is kept for any method that communicates with an HTTP server (such as Download, PostUrlEncoded, QuickGetStr, SynchronousRequest, etc.). When HTTP methods are called asynchronously, the event log can be checked while the HTTP operation is in in progress. This is done by examining the EventLogCount property and then fetching each event's name and value via the EventLogName and EventLogValue methods. See this example: Asynchronous HTTP.

The ClearBgEventLog method may be called to clear the in-memory event log.

Important: If event logging is enabled, make sure to clear the event log after each HTTP method call. Otherwise the log will continue to grow without bounds.

The default value of this property is 0.

The following items may be found in the event log:

NameValue
SocketConnecthostname:port, called when initiating a connection.
SocketConnectedhostname:port, called after successfully connected.
HttpProxyConnecthostname:port
SslHandshake "Starting"/"Finished"
HttpGetBeginURL
HttpCacheHit"Returning page from cache."
HttpInfovarious conditions...
"Begin reading response" -- called when beginning to read the response.
"Finished reading response"
"Existing connection with HTTP server no longer open, restarting GET with new connection."
"Reading chunked response."
"UnGzipping response data"
"Connection:close header is present"
GetRequestthe full HTTP GET request to be sent to the server.
ResponseHeaderthe header of the HTTP response.
HttpStatusCodeHTTP response status code (integer)
ChunkSizeSize (in bytes) of next chunk in response.
ResponseContentLengthNon-chunked response size in bytes.
UnGzippedLengthIf the response was gzip compressed, this is the uncompressed size.
HostnameResolvehostname, Called when starting to resolve a hostname (to an IP address)
ResolvedToIpdotted IP address, called after hostname is resolved.
HttpAuthone of the following strings:
"Starting Negotiate Authentication"
"Starting NTLM Authentication"
"Adding Basic Authentication Header"
"Adding Proxy Authentication Header"
"Starting Proxy NTLM Authentication"
"Starting Digest Authentication"
CookieToSendValue of a Set-Cookie header field to be added to the outgoing request.
SavingCookie XML of cookie being persisted.
HttpRedirectRedirect URL
Socks4Connectdomain:port
Socks5Connectdomain:port
HttpRequestBeginVerb (such as POST, GET, PUT), domain:port/path
RequestHeaderThe full HTTP request header to be sent.
StartSendingRequestSize of entire request, including header, in number of bytes. (Not called for QuickGet) For uploads, this is the size of the entire upload (headers and all files combined)
SubPartHeaderThe header for one of the parts within a multipart request.
UploadFilenameThe file about to be uploaded (streamed from file to socket..)

# $intVal is an integer
$intVal = $http->get_LMFactor();
$http->put_LMFactor($intVal);

An integer between 1 and 100 that indicates the percentage of time from the HTTP page's last-modified date that will be used for the freshness period. The default value is 25. For example, if a page is fetched with a last-modified date of 4 weeks ago, and the LMFactor = 25, then the page will be considered fresh in the cache for 1 week (25% of 4 weeks).

# $strVal is a string
# $ckStr is a CkString
$http->get_LastContentType($ckStr);
$strVal = $http->lastContentType();

The content-type of the last HTTP response received by the HTTP component.

# $strVal is a string
# $ckStr is a CkString
$http->get_LastErrorHtml($ckStr);
$strVal = $http->lastErrorHtml();

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.

# $strVal is a string
# $ckStr is a CkString
$http->get_LastErrorText($ckStr);
$strVal = $http->lastErrorText();

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.

Concept of LastErrorText

LastErrorText Standard Information

# $strVal is a string
# $ckStr is a CkString
$http->get_LastErrorXml($ckStr);
$strVal = $http->lastErrorXml();

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.

# $strVal is a string
# $ckStr is a CkString
$http->get_LastHeader($ckStr);
$strVal = $http->lastHeader();

The text of the last HTTP header sent by any of this class's methods. The purpose of this property is to allow the developer to examine the exact HTTP header for debugging purposes.

# $strVal is a string
# $ckStr is a CkString
$http->get_LastModDate($ckStr);
$strVal = $http->lastModDate();

The value of the Last-Modified header in the last HTTP response received by the HTTP component.

# $strVal is a string
# $ckStr is a CkString
$http->get_LastResponseHeader($ckStr);
$strVal = $http->lastResponseHeader();

The entire last response header for the last HTTP response received by the HTTP component.

# $intVal is an integer
$intVal = $http->get_LastStatus();

The last HTTP status value received by the HTTP component. This only applies to methods that do not return an HTTP response object. For methods that return an HTTP response object, such as SynchronousRequest, the status code is found in the StatusCode property of the response object.

# $strVal is a string
# $ckStr is a CkString
$http->get_Login($ckStr);
$strVal = $http->login();
$http->put_Login($strVal);

The HTTP login for pages requiring a login/password. Chilkat HTTP can do Basic, Digest, and NTLM HTTP authentication. (NTLM is also known as SPA (or Windows Integrated Authentication). To use Basic authentication, the BasicAuth property must be set equal to 1. It is not necessary to set the NtlmAuth or DigestAuth properties beforehand if NTLM or Digest authentication is needed. However, it is most efficient to pre-set these properties when the type of authentication is known in advance.

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

# $strVal is a string
# $ckStr is a CkString
$http->get_LoginDomain($ckStr);
$strVal = $http->loginDomain();
$http->put_LoginDomain($strVal);

The optional domain name to be used with NTLM / Kerberos / Negotiate authentication.

# $intVal is an integer
$intVal = $http->get_MaxConnections();
$http->put_MaxConnections($intVal);

The maximum number of simultaneous open HTTP connections managed by the HTTP component. The Chilkat HTTP component automatically manages HTTP connections. If the number of open HTTP connections is about to be exceeded, the connection with the least recent activity is automatically closed.

# $intVal is an integer
$intVal = $http->get_MaxFreshPeriod();
$http->put_MaxFreshPeriod($intVal);

Limits the amount of time a document can be kept "fresh" in the cache. The MaxFreshPeriod is specified in minutes, and the default value is 525600 which is equal to 1 year.

# $intVal is an integer
$intVal = $http->get_MaxResponseSize();
$http->put_MaxResponseSize($intVal);

The maximum HTTP response size to be accepted by the calling program. A value of 0 (the default) indicates that there is no maximum value.

# $intVal is an integer
$intVal = $http->get_MaxUrlLen();
$http->put_MaxUrlLen($intVal);

The Http class will automatically fail any URL longer than this length. The default MaxUrlLen is 800 characters.

# $boolVal is an boolean
$boolVal = $http->get_MimicFireFox();
$http->put_MimicFireFox($boolVal);

If set to 1, then the appropriate headers to mimic Mozilla/FireFox are automatically added to requests sent via the QuickGet and QuickGetStr methods.

# $boolVal is an boolean
$boolVal = $http->get_MimicIE();
$http->put_MimicIE($boolVal);

If set to 1, then the appropriate headers to mimic Internet Explorer are automatically added to requests sent via the QuickGet and QuickGetStr methods.

# $intVal is an integer
$intVal = $http->get_MinFreshPeriod();
$http->put_MinFreshPeriod($intVal);

The freshness period for a document in cache will not be less than this value (in minutes). The default value is 30.

# $boolVal is an boolean
$boolVal = $http->get_NegotiateAuth();
$http->put_NegotiateAuth($boolVal);

Set this property equal to 1 for Negotiate authentication. Negotiate authentication will dynamically select Kerberos or NTLM authentication depending on what the server requires.

Note: The NegotiateAuth property is only available for the Microsoft Windows operating system.

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

# $boolVal is an boolean
$boolVal = $http->get_NtlmAuth();
$http->put_NtlmAuth($boolVal);

Setting this property to 1 causes the HTTP component to use NTLM authentication (also known as IWA -- or Integrated Windows Authentication) when authentication with an HTTP server. The default value is 0.

HTTP Authentication (Basic, NTLM, Digest, Negotiate/Kerberos)

# $intVal is an integer
$intVal = $http->get_NumCacheLevels();
$http->put_NumCacheLevels($intVal);

The number of directory levels to be used under each cache root. The default is 0, meaning that each cached HTML page is stored in a cache root directory. A value of 1 causes each cached page to be stored in one of 255 subdirectories named "0","1", "2", ..."255" under a cache root. A value of 2 causes two levels of subdirectories ("0..255/0..255") under each cache root. The HTTP control automatically creates subdirectories as needed. The reason for mutliple levels is to alleviate problems that may arise with unrelated software when huge numbers of files are stored in a single directory. For example, Windows Explorer does not behave well when trying to display the contents of directories with thousands of files.

# $intVal is an integer
$intVal = $http->get_NumCacheRoots();

The number of cache roots to be used for the HTTP cache. This allows the disk cache spread out over multiple disk drives. Each cache root is a string indicating the drive letter and directory path. For example, "E:\Cache". An example of a very large low-cost cache might be four USB external drives. To create a cache with four roots, call AddCacheRoot once for each directory root.

# $boolVal is an boolean
$boolVal = $http->get_OAuth1();
$http->put_OAuth1($boolVal);

If 1 then causes an OAuth Authorization header to be added to any request sent by the HTTP object. For example:

Authorization: OAuth realm="http://sp.example.com/",
                oauth_consumer_key="0685bd9184jfhq22",
                oauth_token="ad180jjd733klru7",
                oauth_signature_method="HMAC-SHA1",
                oauth_signature="wOJIO9A2W5mFwDgiDvZbTSMK%2FPY%3D",
                oauth_timestamp="137131200",
                oauth_nonce="4572616e48616d6d65724c61686176",
                oauth_version="1.0"
The information used to compute the OAuth Authorization header is obtained from the other OAuth* properties, such as OAuthConsumerKey, OAuthConsumerSecret, OAuthRealm, etc.

Twitter OAuth -- Tweet to Your Own Account

# $strVal is a string
# $ckStr is a CkString
$http->get_OAuthConsumerKey($ckStr);
$strVal = $http->oAuthConsumerKey();
$http->put_OAuthConsumerKey($strVal);

The OAuth consumer key to be used in the Authorization header.

# $strVal is a string
# $ckStr is a CkString
$http->get_OAuthConsumerSecret($ckStr);
$strVal = $http->oAuthConsumerSecret();
$http->put_OAuthConsumerSecret($strVal);

The OAuth consumer secret to be used in computing the contents of the Authorization header.

# $strVal is a string
# $ckStr is a CkString
$http->get_OAuthRealm($ckStr);
$strVal = $http->oAuthRealm();
$http->put_OAuthRealm($strVal);

The OAuth realm to be used in the Authorization header.

# $strVal is a string
# $ckStr is a CkString
$http->get_OAuthSigMethod($ckStr);
$strVal = $http->oAuthSigMethod();
$http->put_OAuthSigMethod($strVal);

The OAuth signature method, such as "HMAC-SHA1" to be used in the Authorization header. The default is "HMAC-SHA1". It is also possible to choose "RSA-SHA1", in which case the RSA private key would need to be provided via the SetOAuthRsaKey method.

# $strVal is a string
# $ckStr is a CkString
$http->get_OAuthToken($ckStr);
$strVal = $http->oAuthToken();
$http->put_OAuthToken($strVal);

The OAuth token to be used in the Authorization header.

Twitter OAuth -- Tweet to Your Own Account

# $strVal is a string
# $ckStr is a CkString
$http->get_OAuthTokenSecret($ckStr);
$strVal = $http->oAuthTokenSecret();
$http->put_OAuthTokenSecret($strVal);

The OAuth token secret to be used in computing the Authorization header.

# $strVal is a string
# $ckStr is a CkString
$http->get_OAuthVerifier($ckStr);
$strVal = $http->oAuthVerifier();
$http->put_OAuthVerifier($strVal);

The OAuth verifier to be used in the Authorization header.

# $strVal is a string
# $ckStr is a CkString
$http->get_Password($ckStr);
$strVal = $http->password();
$http->put_Password($strVal);

The HTTP password for pages requiring a login/password. Chilkat HTTP can do Basic, Digest, and NTLM HTTP authentication. (NTLM is also known as SPA (or Windows Integrated Authentication). To use Basic authentication, the BasicAuth property must be set equal to 1. It is not necessary to set the NtlmAuth or DigestAuth properties beforehand if NTLM or Digest authentication is needed. However, it is most efficient to pre-set these properties when the type of authentication is known in advance.

# $boolVal is an boolean
$boolVal = $http->get_PreferIpv6();
$http->put_PreferIpv6($boolVal);

If 1, then use IPv6 over IPv4 when both are supported for a particular domain. The default value of this property is 0, which will choose IPv4 over IPv6.

# $strVal is a string
# $ckStr is a CkString
$http->get_ProxyAuthMethod($ckStr);
$strVal = $http->proxyAuthMethod();
$http->put_ProxyAuthMethod($strVal);

Set this to "basic" if you know in advance that Basic authentication is to be used for the HTTP proxy. Otherwise leave this property unset. Note: It is not necessary to set this property. The HTTP component will automatically handle proxy authentication for any of the supported authentication methods: NTLM, Digest, or Basic. Setting this property equal to "basic" prevents the 407 response which is automatically handled internal to Chilkat and never seen by your application.

# $strVal is a string
# $ckStr is a CkString
$http->get_ProxyDomain($ckStr);
$strVal = $http->proxyDomain();
$http->put_ProxyDomain($strVal);

The domain name of a proxy host if an HTTP proxy is used.

# $strVal is a string
# $ckStr is a CkString
$http->get_ProxyLogin($ckStr);
$strVal = $http->proxyLogin();
$http->put_ProxyLogin($strVal);

If an HTTP proxy is used and it requires authentication, this property specifies the HTTP proxy login.

# $strVal is a string
# $ckStr is a CkString
$http->get_ProxyLoginDomain($ckStr);
$strVal = $http->proxyLoginDomain();
$http->put_ProxyLoginDomain($strVal);

The NTLM authentication domain (optional) if NTLM authentication is used.

# $strVal is a string
# $ckStr is a CkString
$http->get_ProxyPassword($ckStr);
$strVal = $http->proxyPassword();
$http->put_ProxyPassword($strVal);

If an HTTP proxy is used and it requires authentication, this property specifies the HTTP proxy password.

# $intVal is an integer
$intVal = $http->get_ProxyPort();
$http->put_ProxyPort($intVal);

The port number of a proxy server if an HTTP proxy is used.

# $intVal is an integer
$intVal = $http->get_ReadTimeout();
$http->put_ReadTimeout($intVal);

The amount of time in seconds to wait before timing out when reading from an HTTP server. The ReadTimeout is the amount of time that needs to elapse while no additional data is forthcoming. During a long download, if the data stream halts for more than this amount, it will timeout. Otherwise, there is no limit on the length of time for the entire download.

# $strVal is a string
# $ckStr is a CkString
$http->get_RedirectVerb($ckStr);
$strVal = $http->redirectVerb();
$http->put_RedirectVerb($strVal);

Indicates the HTTP verb, such as GET, POST, PUT, etc. to be used for a redirect when the FollowRedirects property is set to 1. The default value of this property is "GET". This will produce the same behavior as a web browser (such as FireFox). If this property is set to the empty string, then it will cause the same verb as the original HTTP request to be used.

Note: Prior to version 9.5.0.44, the default value of this property was the empty string.

# $strVal is a string
# $ckStr is a CkString
$http->get_Referer($ckStr);
$strVal = $http->referer();
$http->put_Referer($strVal);

The Referer header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is the empty string which causes the Referer field to be omitted from the request header.

# $boolVal is an boolean
$boolVal = $http->get_RequireSslCertVerify();
$http->put_RequireSslCertVerify($boolVal);

If 1, then the HTTP client will verify the server's SSL certificate. The certificate is expired, or if the cert's signature is invalid, the connection is not allowed. The default value of this property is 0.

# $strVal is a string
# $ckStr is a CkString
$http->get_RequiredContentType($ckStr);
$strVal = $http->requiredContentType();
$http->put_RequiredContentType($strVal);

If set, then any HTTP response to any POST or GET, including downloads, will be rejected if the content-type in the response header does not match this setting. If the content-type does not match, only the header of the HTTP response is read, the connection to the HTTP server is closed, and the remainder of the response is never read.

This property is empty (zero-length string) by default.

Some typical content-types are "text/html", "text/xml", "image/gif", "image/jpeg", "application/zip", "application/msword", "application/pdf", etc.

# $boolVal is an boolean
$boolVal = $http->get_S3Ssl();
$http->put_S3Ssl($boolVal);

If 1, then all S3_* methods will use a secure SSL/TLS connection for communications. The default value is 0.

# $boolVal is an boolean
$boolVal = $http->get_SaveCookies();
$http->put_SaveCookies($boolVal);

If this property is 1, cookies are automatically persisted to XML files in the directory specified by the CookiesDir property (or in memory if CookieDir = "memory"). Both CookiesDir and SaveCookies must be set for cookies to be persisted.

Saving Cookies to XML Files

Caching cookies in-memory.

# $intVal is an integer
$intVal = $http->get_SendBufferSize();
$http->put_SendBufferSize($intVal);

The buffer size to be used with the underlying TCP/IP socket for sending. The default value is 65535.

# $boolVal is an boolean
$boolVal = $http->get_SendCookies();
$http->put_SendCookies($boolVal);

If 1, then cookies previously persisted to the CookiesDir are automatically added to all HTTP requests. Only cookies matching the domain and path are added.

Caching cookies in-memory.

# $strVal is a string
# $ckStr is a CkString
$http->get_SessionLogFilename($ckStr);
$strVal = $http->sessionLogFilename();
$http->put_SessionLogFilename($strVal);

Enables file-based session logging. If set to a filename (or relative/absolute filepath), then the exact HTTP requests and responses are logged to a file. The file is created if it does not already exist, otherwise it is appended.

Debugging HTTP

HTTP Session Logging

# $intVal is an integer
$intVal = $http->get_SoRcvBuf();
$http->put_SoRcvBuf($intVal);

Sets the receive buffer size socket option. Normally, this property should be left unchanged. The default value is 0, which indicates that the receive buffer size socket option should not be explicitly set (i.e. the system default value, which may vary from system to system, should be used).

This property can be changed if download performance seems slow. It is recommended to be a multiple of 4096. To see the current system's default receive buffer size, examine the LastErrorText property after calling any method that establishes a connection. It should be reported under the heading "SO_RCVBUF". To boost performance, try setting it equal to 2, 3, or 4 times the default value.

More Information about TCP performance and Buffer Sizes

# $intVal is an integer
$intVal = $http->get_SoSndBuf();
$http->put_SoSndBuf($intVal);

Sets the send buffer size socket option. Normally, this property should be left unchanged. The default value is 0, which indicates that the send buffer size socket option should not be explicitly set (i.e. the system default value, which may vary from system to system, should be used).

This property can be changed if upload performance seems slow. It is recommended to be a multiple of 4096. To see the current system's default send buffer size, examine the LastErrorText property after calling any method that establishes a connection. It should be reported under the heading "SO_SNDBUF". To boost performance, try setting it equal to 2, 3, or 4 times the default value.

More Information about TCP performance and Buffer Sizes

# $strVal is a string
# $ckStr is a CkString
$http->get_SocksHostname($ckStr);
$strVal = $http->socksHostname();
$http->put_SocksHostname($strVal);

The SOCKS4/SOCKS5 hostname or IPv4 address (in dotted decimal notation). This property is only used if the SocksVersion property is set to 4 or 5).

# $strVal is a string
# $ckStr is a CkString
$http->get_SocksPassword($ckStr);
$strVal = $http->socksPassword();
$http->put_SocksPassword($strVal);

The SOCKS5 password (if required). The SOCKS4 protocol does not include the use of a password, so this does not apply to SOCKS4.

# $intVal is an integer
$intVal = $http->get_SocksPort();
$http->put_SocksPort($intVal);

The SOCKS4/SOCKS5 proxy port. The default value is 1080. This property only applies if a SOCKS proxy is used (if the SocksVersion property is set to 4 or 5).

# $strVal is a string
# $ckStr is a CkString
$http->get_SocksUsername($ckStr);
$strVal = $http->socksUsername();
$http->put_SocksUsername($strVal);

The SOCKS4/SOCKS5 proxy username. This property is only used if the SocksVersion property is set to 4 or 5).

# $intVal is an integer
$intVal = $http->get_SocksVersion();
$http->put_SocksVersion($intVal);

SocksVersion May be set to one of the following integer values:

0 - No SOCKS proxy is used. This is the default.
4 - Connect via a SOCKS4 proxy.
5 - Connect via a SOCKS5 proxy.

# $strVal is a string
# $ckStr is a CkString
$http->get_SslProtocol($ckStr);
$strVal = $http->sslProtocol();
$http->put_SslProtocol($strVal);

Selects the secure protocol to be used for secure (SSL/TLS) connections. Possible values are:

default
TLS 1.2
TLS 1.1
TLS 1.0
SSL 3.0
TLS 1.2 or higher
TLS 1.1 or higher
TLS 1.0 or higher
The default value is "default" which will choose the, which allows for the protocol to be selected dynamically at runtime based on the requirements of the server. Choosing an exact protocol will cause the connection to fail unless that exact protocol is negotiated. It is better to choose "X or higher" than an exact protocol. The "default" is effectively "SSL 3.0 or higher".

# $boolVal is an boolean
$boolVal = $http->get_UpdateCache();
$http->put_UpdateCache($boolVal);

Controls whether the cache is automatically updated with the responses from HTTP GET requests.

# $boolVal is an boolean
$boolVal = $http->get_UseBgThread();
$http->put_UseBgThread($boolVal);

If 1, then background-enabled methods will run in a background thread. Normally, a method will return after its work is completed. However, when UseBgThread is true, the method will return immediately and a background thread is started to carry out the method's task.

Background-enabled HTTP methods are:

# $boolVal is an boolean
$boolVal = $http->get_UseIEProxy();
$http->put_UseIEProxy($boolVal);

If 1, the proxy host/port used by Internet Explorer will also be used by Chilkat HTTP.

# $strVal is a string
# $ckStr is a CkString
$http->get_UserAgent($ckStr);
$strVal = $http->userAgent();
$http->put_UserAgent($strVal);

The UserAgent header field to be automatically included with GET requests issued by QuickGet or QuickGetStr. The default value is "Chilkat/1.0.0 (+http://www.chilkatsoft.com/ChilkatHttpUA.asp)" which indicates that the software used to issue the HTTP request was the Chilkat HTTP component.

# $boolVal is an boolean
$boolVal = $http->get_VerboseLogging();
$http->put_VerboseLogging($boolVal);

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

# $strVal is a string
# $ckStr is a CkString
$http->get_Version($ckStr);
$strVal = $http->version();

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

# $boolVal is an boolean
$boolVal = $http->get_WasRedirected();

Indicates whether the last HTTP GET was redirected.

Methods

# $dir is a string
$$http->AddCacheRoot($dir);

This method must be called at least once if disk caching is to be used. The file path (including drive letter) such as "E:\MyHttpCache\" is passed to AddCacheRoot to specify the root directory. The cache can be spread across multiple disk drives by calling AddCacheRoot multiple times, each with a directory path on a separate disk drive.

# $headerFieldName is a string
# $headerFieldValue is a string
$status = $http->AddQuickHeader($headerFieldName, $headerFieldValue);

Adds a custom header field to any HTTP request sent by a method that does not use the HTTP request object. These methods include Download, DownloadAppend, GetHead, PostBinary, PostMime, PostXml, PutBinary, PutText, QuickDeleteStr, QuickGet, QuickGetObj, QuickGetStr, QuickPutStr, XmlRpc, and XmlRpcPut.

Cookies may be explictly added by calling this method passing "Cookie" for the headerFieldName.

The RemoveQuickHeader method can be called to remove a custom header.

* Note: This method is deprecated. It is identical to theSetRequestHeader method. The SetRequestHeader method should be called instead because AddQuickHeader will be removed in a future version.

Returns 1 for success, 0 for failure.

Adding Cookies to an HTTP Request

$retval = $http->BgResponseObject();

If a backgrounded method returns an Http response object, it may be retrieved by calling this method.

$$http->BgTaskAbort();

Call this to force the currently running backgrounded method to abort.

$$http->ClearBgEventLog();

Clears the in-memory event log (which is enabled by setting the KeepEventLog property = 1).

$$http->ClearInMemoryCookies();

Clears all cookies cached in memory. Calling this only makes sense if the CookieDir property is set to the string "memory".

$status = $http->CloseAllConnections();

Closes all connections still open from previous HTTP requests.

An HTTP object instance will maintain up to 10 connections. If the HTTP server's response does not include a "Connection: Close" header, the connection will remain open and will be re-used if possible for the next HTTP request to the same hostname:port. (It uses the IP address (in string form) or the domain name, whichever is used in the URL provided by the application.) If 10 connections are already open and another is needed, the object will close the least recently used connection.

Returns 1 for success, 0 for failure.

$$http->DnsCacheClear();

Introduced in version 9.5.0.38

Clears the Chilkat-wide in-memory hostname-to-IP address DNS cache. Chilkat automatically maintains this in-memory cache to prevent redundant DNS lookups. If the TTL on the DNS A records being accessed are short and/or these DNS records change frequently, then this method can be called clear the internal cache. Note: The DNS cache is used/shared among all Chilkat objects in a program, and clearing the cache affects all Chilkat objects.

# $url is a string
# $localFilePath is a string
$status = $http->Download($url, $localFilePath);

Retrieves the content at a URL and saves to a file. All content is saved in streaming mode such that the memory footprint is small and steady. HTTPS is fully supported, as it is with all the methods of this class.

Returns 1 for success, 0 for failure.

HTTP Download any Type of File (binary or text)

Debugging HTTP

# $url is a string
# $filename is a string
$status = $http->DownloadAppend($url, $filename);

Same as the Download method, but the output file is open for append.

Returns 1 for success, 0 for failure.

# $url is a string
# $hashAlgorithm is a string
# $encoding is a string
# $outStr is a CkString (output)
$status = $http->DownloadHash($url, $hashAlgorithm, $encoding, $outStr);
$retStr = $http->downloadHash($url, $hashAlgorithm, $encoding);

Retrieves the content at a URL and computes and returns a hash of the content. The hash is returned as an encoded string according to the encoding, which may be "Base64", "modBase64", "Base32", "UU", "QP" (for quoted-printable), "URL" (for url-encoding), "Hex", "Q", "B", "url_oath", "url_rfc1738", "url_rfc2396", and "url_rfc3986". The hashAlgorithm may be "sha1", "sha256", "sha384", "sha512", "md2", "md5", "haval", "ripemd128", "ripemd160","ripemd256", or "ripemd320".

Returns 1 for success, 0 for failure.

# $index is an integer
# $outStr is a CkString (output)
$status = $http->EventLogName($index, $outStr);
$retStr = $http->eventLogName($index);

Returns the name of the Nth event in the in-memory event log. Refer to the documentation for the KeepEventLog property for the full list of event names. Indexing is from 0 to EventLogCount-1.

Returns 1 for success, 0 for failure.

# $index is an integer
# $outStr is a CkString (output)
$status = $http->EventLogValue($index, $outStr);
$retStr = $http->eventLogValue($index);

Returns the value of the Nth event in the in-memory event log. Indexing is from 0 to EventLogCount-1.

Returns 1 for success, 0 for failure.

# $htmlContent is a string
# $outStr is a CkString (output)
$status = $http->ExtractMetaRefreshUrl($htmlContent, $outStr);
$retStr = $http->extractMetaRefreshUrl($htmlContent);

Convenience method for extracting the META refresh URL from HTML. For example, if the htmlContent contains a META refresh tag, such as:

<meta http-equiv="refresh" content="5;URL='http://example.com/'">
Then the return value of this method would be "http://example.com/".

Returns 1 for success, 0 for failure.

# $iss is a string
# $scope is a string
# $subEmail is a string
# $numSec is an integer
# $cert is a CkCert
# $outStr is a CkString (output)
$status = $http->G_SvcOauthAccessToken($iss, $scope, $subEmail, $numSec, $cert, $outStr);
$retStr = $http->g_SvcOauthAccessToken($iss, $scope, $subEmail, $numSec, $cert);

Introduced in version 9.5.0.44

Makes an access token request to obtain a Google API OAuth2 access token for a service account. Access tokens issued by the Google OAuth 2.0 Authorization Server expire one hour after they are issued. When an access token expires, then the application should generate another JWT, sign it, and request another access token. The subEmail is the email address of the user for which the application is requesting delegated access. The iss is the email address of the client_id of the application making the access token request. The scope is a space-delimited list of the permissions that the application requests. (See https://developers.google.com/accounts/docs/OAuth2ServiceAccount )

Returns 1 for success, 0 for failure.

Get XOAUTH2 Access Token from Google OAuth 2.0 Authorization Server

# $outStr is a CkString (output)
$status = $http->GenTimeStamp($outStr);
$retStr = $http->genTimeStamp();

Returns the current GMT (also known as UTC) date/time in a string that is compliant with RFC 2616 format.

Returns 1 for success, 0 for failure.

# $index is an integer
# $outStr is a CkString (output)
$status = $http->GetCacheRoot($index, $outStr);
$retStr = $http->getCacheRoot($index);

Returns the Nth cache root (indexing begins at 0). Cache roots are set by calling AddCacheRoot one or more times.

Returns 1 for success, 0 for failure.

# $domain is a string
# $outStr is a CkString (output)
$status = $http->GetCookieXml($domain, $outStr);
$retStr = $http->getCookieXml($domain);

Returns the cookies in XML format for a specific domain. Cookies are only persisted if the SaveCookies property is set to 1. If the CookieDir property is set to the keyword "memory", then cookies are saved in-memory.

Returns 1 for success, 0 for failure.

# $url is a string
# $outStr is a CkString (output)
$status = $http->GetDomain($url, $outStr);
$retStr = $http->getDomain($url);

Utility method for extracting the domain name from a full URL. For example, if "http://www.chilkatsoft.com/default.asp" is the URL passed in, then "www.chilkatsoft.com" is returned.

Returns 1 for success, 0 for failure.

# $url is a string
$retval = $http->GetHead($url);

Sends an HTTP HEAD request for a URL and returns a response object.

# $name is a string
# $outStr is a CkString (output)
$status = $http->GetRequestHeader($name, $outStr);
$retStr = $http->getRequestHeader($name);

Returns the value of a header field that has been pre-defined to be sent with all HTTP GET requests issued by the QuickGet and QuickGetStr methods. By default, this includes header fields such as Accept, AcceptCharset, AcceptLanguage, Connection, UserAgent, etc.

Returns 1 for success, 0 for failure.

# $domain is a string
# $port is an integer
$retval = $http->GetServerSslCert($domain, $port);

Establishes an SSL/TLS connection with a web server for the purpose of retrieving the server's SSL certificate (public-key only of course...). Nothing is retrieved from the web server. This method simply makes a connection, gets the certificate information, and closes the connection.

# $url is a string
# $outStr is a CkString (output)
$status = $http->GetUrlPath($url, $outStr);
$retStr = $http->getUrlPath($url);

Returns the path part of a URL. The syntax of a URL is ://:@:/;?#. This method returns the "path" part.

Returns 1 for success, 0 for failure.

# $name is a string
$retBool = $http->HasRequestHeader($name);

Returns true if the specified header field is defined such that it will be sent with all GET requests issued by the QuickGet and QuickGetStr methods.

$retBool = $http->IsUnlocked();

Returns true if the Http class has been unlocked. It is necessary to call Http.UnlockComponent before calling any other methods. Passing any string to UnlockComponent will automatically activate a 30-day trial period.

# $verb is a string
# $url is a string
# $byteData is a CkByteData
# $contentType is a string
# $md5 is a bool
# $gzip is a bool
$retval = $http->PBinary($verb, $url, $byteData, $contentType, $md5, $gzip);

Introduced in version 9.5.0.45

Sends an HTTP request to the url. The verb can be "POST" or "PUT". The body of the HTTP request contains the bytes passed in byteData. The contentType is a content type such as "image/gif", "application/pdf", etc. If md5 is 1, then a Content-MD5 header is added with the base64 MD5 hash of the byteData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is 1, the byteData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

# $verb is a string
# $url is a string
# $textData is a string
# $charset is a string
# $contentType is a string
# $md5 is a bool
# $gzip is a bool
$retval = $http->PText($verb, $url, $textData, $charset, $contentType, $md5, $gzip);

Introduced in version 9.5.0.46

Sends an HTTP request to the url. The verb can be "POST" or "PUT". The body of the HTTP request contains the text passed in textData. The contentType is a content type such as "text/xml", "application/json", etc. If md5 is 1, then a Content-MD5 header is added with the base64 MD5 hash of the textData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is 1, the contentType is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

# $url is a string
# $byteData is a CkByteData
# $contentType is a string
# $md5 is a bool
# $gzip is a bool
# $outStr is a CkString (output)
$status = $http->PostBinary($url, $byteData, $contentType, $md5, $gzip, $outStr);
$retStr = $http->postBinary($url, $byteData, $contentType, $md5, $gzip);

Sends an HTTP POST request to the url. The body of the HTTP request contains the bytes passed in byteData. The contentType is a content type such as "image/gif", "application/pdf", etc. If md5 is 1, then a Content-MD5 header is added with the base64 MD5 hash of the byteData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is 1, the byteData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns the text body of the HTTP response if the HTTP response has a success status code. Otherwise the method is considered to have failed. If more details of the HTTP response are required, call PBinary instead (which returns the HTTP response object).

Returns 1 for success, 0 for failure.

# $url is a string
# $jsonText is a string
$retval = $http->PostJson($url, $jsonText);

A simplified way of sending a JSON POST and receiving the JSON response. The HTTP response is returned in an HTTP response object. The content type of the HTTP request is "applicatoin/jsonrequest". To send a JSON POST using "application/json", call the PostJson2 method where the content type can be explicitly provided.

HTTP POST JSON

# $url is a string
# $contentType is a string
# $jsonText is a string
$retval = $http->PostJson2($url, $contentType, $jsonText);

The same as PostJson,except it allows for the content type to be explicitly provided. The PostJson method automatically uses "application/jsonrequest". If the application needs for the content type to be "application/json", or some other content type, then PostJson2 provides the means.

# $url is a string
# $req is a CkHttpRequest
$retval = $http->PostUrlEncoded($url, $req);

Sends a simple URL encoded POST. The form parameters are sent in the body of the HTTP request in x-www-form-urlencoded format. The content-type is "application/x-www-form-urlencoded".

Duplicating a Simple HTML Form Submission (POST)

HTTP POST x-www-form-urlencoded

Debugging HTTP

# $endpointUrl is a string
# $xmlContent is a string
# $xmlCharset is a string
$retval = $http->PostXml($endpointUrl, $xmlContent, $xmlCharset);

A simplified way of posting XML content to a web server. This method is good for making SOAP calls using HTTP POST. The xmlCharset should match the character encoding used in the xmlContent, which is typically "utf-8". The HTTP response is returned in an HTTP response object.

Send XMLHttpRequest and Get Response

Calling a SOAP Web Service using PostXml

Debugging HTTP

# $url is a string
# $byteData is a CkByteData
# $contentType is a string
# $md5 is a bool
# $gzip is a bool
# $outStr is a CkString (output)
$status = $http->PutBinary($url, $byteData, $contentType, $md5, $gzip, $outStr);
$retStr = $http->putBinary($url, $byteData, $contentType, $md5, $gzip);

Sends an HTTP PUT request to the url. The body of the HTTP request is byteData. The contentType is a content type such as "image/gif", "application/pdf", etc. If md5 is 1, then a Content-MD5 header is added with the base64 MD5 hash of the byteData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is 1, the byteData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns the text body of the HTTP response if the HTTP response has a success status code. Otherwise the method is considered to have failed. If more details of the HTTP response are required, call PBinary instead (which returns the HTTP response object).

Returns 1 for success, 0 for failure.

# $url is a string
# $textData is a string
# $charset is a string
# $contentType is a string
# $md5 is a bool
# $gzip is a bool
# $outStr is a CkString (output)
$status = $http->PutText($url, $textData, $charset, $contentType, $md5, $gzip, $outStr);
$retStr = $http->putText($url, $textData, $charset, $contentType, $md5, $gzip);

Sends an HTTP PUT request to the url. The body of the HTTP request is textData. The charset should be set to a charset name such as "iso-8859-1", "windows-1252", "Shift_JIS", "utf-8", etc. The string "ansi" may also be used as a charset name. The contentType is a content type such as "text/plain", "text/xml", etc. If md5 is 1, then a Content-MD5 header is added with the base64 MD5 hash of the textData. Servers aware of the Content-MD5 header will perform a message integrity check to ensure that the data has not been corrupted. If gzip is 1, the textData is compressed using the gzip algorithm. The HTTP request body will contain the GZIP compressed data, and a "Content-Encoding: gzip" header is automatically added to indicate that the request data needs to be ungzipped when received (at the server).

Returns the text body of the HTTP response if the HTTP response has a success status code. Otherwise the method is considered to have failed. If more details of the HTTP response are required, call PText instead (which returns the HTTP response object).

Returns 1 for success, 0 for failure.

HTTP PUT JSON

# $url is a string
# $outStr is a CkString (output)
$status = $http->QuickDeleteStr($url, $outStr);
$retStr = $http->quickDeleteStr($url);

Same as QuickGetStr, but uses the HTTP DELETE method instead of the GET method.

Returns 1 for success, 0 for failure.

Debugging HTTP

# $url is a string
# $outData is a CkByteData (output)
$status = $http->QuickGet($url, $outData);

Sends an HTTP GET request for a URL and returns the response body as a byte array. The URL may contain query parameters. If the SendCookies property is true, matching cookies previously persisted to the CookiesDir are automatically included in the request. If the FetchFromCache property is true, the page may be fetched directly from cache. Because the URL can specify any type of resource (HTML page, GIF image, etc.) the return value is a byte array. If the resource is known to be a string, such as with an HTML page, you may call QuickGetStr instead. If the HTTP request fails, a zero-length byte array is returned and error information can be found in the LastErrorText, LastErrorXml, or LastErrorHtml properties.

Returns 1 for success, 0 for failure.

# $url is a string
$retval = $http->QuickGetObj($url);

Sends an HTTP GET request for a URL and returns the response object. If the SendCookies property is 1, matching cookies previously persisted to the CookiesDir are automatically included in the request. If the FetchFromCache property is 1, the page could be fetched directly from cache.

# $url is a string
# $outStr is a CkString (output)
$status = $http->QuickGetStr($url, $outStr);
$retStr = $http->quickGetStr($url);

Sends an HTTP GET request for a URL and returns the response body as a string. The URL may contain query parameters. If the SendCookies property is 1, matching cookies previously persisted to the CookiesDir are automatically included in the request. If the FetchFromCache property is 1, the page could be fetched directly from cache. If the HTTP request fails, a NULL value is returned and error information can be found in the LastErrorText, LastErrorXml, or LastErrorHtml properties.

Returns 1 for success, 0 for failure.

HTTP GET - Download HTML or any Text Content to a String

HTTPS GET using SSL/TLS

# $url is a string
# $outStr is a CkString (output)
$status = $http->QuickPutStr($url, $outStr);
$retStr = $http->quickPutStr($url);

Same as QuickGetStr, but uses the HTTP PUT method instead of the GET method.

Returns 1 for success, 0 for failure.

Debugging HTTP

# $headerFieldName is a string
$status = $http->RemoveQuickHeader($headerFieldName);

Removes a header from the internal list of custom header field name/value pairs to be automatically added when HTTP requests are sent via methods that do not use the HTTP request object. (The AddQuickHeader method is called to add custom header fields.)

* Note: This method is deprecated. It is identical to the RemoveRequestHeader method. The RemoveRequestHeader method should be called instead because this method will be removed in a future version.

Returns 1 for success, 0 for failure.

# $name is a string
$$http->RemoveRequestHeader($name);

Removes a header from the internal list of custom header field name/value pairs to be automatically added when HTTP requests are sent via methods that do not use the HTTP request object. (The SetRequestHeader method is called to add custom header fields.)

# $url is a string
# $outStr is a CkString (output)
$status = $http->RenderGet($url, $outStr);
$retStr = $http->renderGet($url);

Same as QuickGet, but does not send the HTTP GET. Instead, it builds the HTTP request that would've been sent and returns it.

Returns 1 for success, 0 for failure.

# $url is a string
# $targetFilename is a string
$status = $http->ResumeDownload($url, $targetFilename);

Same as the Download method, except a failed download may be resumed. The targetFilename is automatically checked and if it exists, the download will resume at the point where it previously failed. ResumeDownload may be called any number of times until the full download is complete.

Returns 1 for success, 0 for failure.

# $bucketPath is a string
$status = $http->S3_CreateBucket($bucketPath);

Creates a new Amazon S3 bucket.

Note: x-amz-* headers, including metadata, can be added to any S3 request by adding each header with a call to SetRequestHeader. This applies to all S3 methods, even if not explicitly stated.

Returns 1 for success, 0 for failure.

S3 Create Bucket Example

# $bucketPath is a string
$status = $http->S3_DeleteBucket($bucketPath);

Deletes an Amazon S3 bucket.

Returns 1 for success, 0 for failure.

S3 Delete Bucket

# $bucketPath is a string
# $objectName is a string
$status = $http->S3_DeleteObject($bucketPath, $objectName);

Deletes a remote file (object) on the Amazon S3 service.

Returns 1 for success, 0 for failure.

S3 Delete File

# $bucketPath is a string
# $objectName is a string
# $outBytes is a CkByteData (output)
$status = $http->S3_DownloadBytes($bucketPath, $objectName, $outBytes);

The same as DownloadFile, except the file data is returned directly in-memory instead of being written to a local file.

Returns 1 for success, 0 for failure.

# $bucketPath is a string
# $objectName is a string
# $localFilePath is a string
$status = $http->S3_DownloadFile($bucketPath, $objectName, $localFilePath);

Downloads a file from the Amazon S3 service.

Returns 1 for success, 0 for failure.

S3 Download File Example

# $bucketPath is a string
# $objectName is a string
# $charset is a string
# $outStr is a CkString (output)
$status = $http->S3_DownloadString($bucketPath, $objectName, $charset, $outStr);
$retStr = $http->s3_DownloadString($bucketPath, $objectName, $charset);

Downloads a text file (object) from the Amazon S3 service directly into a string variable. The charset specifies the character encoding, such as "utf-8", of the remote text object.

Returns 1 for success, 0 for failure.

S3 Download String Object

# $bucketPath is a string
# $objectName is a string
$retInt = $http->S3_FileExists($bucketPath, $objectName);

Determines if a remote object (file) exists. Returns 1 if the file exists, 0 if it does not exist, -1 if there was a failure in checking, or 2 if using in asynchronous mode to indicate that the background task was successfully started.

# $bucket is a string
# $path is a string
# $expire is a CkDateTime
# $outStr is a CkString (output)
$status = $http->S3_GenerateUrl($bucket, $path, $expire, $outStr);
$retStr = $http->s3_GenerateUrl($bucket, $path, $expire);

Introduced in version 9.5.0.46

Generates a temporary pre-signed URL for Amazon S3. Requires that the AwsSecretKey and AwsAccessKey be set to valid values prior to calling this method.

Returns 1 for success, 0 for failure.

Generate S3 Signed URL

# $bucketPath is a string
# $outStr is a CkString (output)
$status = $http->S3_ListBucketObjects($bucketPath, $outStr);
$retStr = $http->s3_ListBucketObjects($bucketPath);

Retrieves the XML listing of the objects contained within an Amazon S3 bucket. (This is like a directory listing, but in XML format.)

The bucketPath name may be qualified with URL-encoded params. For example, to list the objects in a bucket named "ChilkatABC" with max-keys = 2000 and marker = "xyz", call S3_ListBucketObject passing the following string for bucketPath: "ChilkatABC?max-keys=2000&marker=xyz"

The S3_ListBucketObjects method recognized all params listed in the AWS documentation for listing objects in a bucket: delimiter, marker, max-keys, and prefix. See Amazon's AWS online documentation for more information.

Returns 1 for success, 0 for failure.

S3 List Objects in Bucket

# $outStr is a CkString (output)
$status = $http->S3_ListBuckets($outStr);
$retStr = $http->s3_ListBuckets();

Retrieves the XML listing of the buckets for an Amazon S3 account.

Returns 1 for success, 0 for failure.

S3 List Buckets Example

# $contentBytes is a CkByteData
# $contentType is a string
# $bucketPath is a string
# $objectName is a string
$status = $http->S3_UploadBytes($contentBytes, $contentType, $bucketPath, $objectName);

The same as S3_UploadFile, except the contents of the file come from contentBytes instead of a local file.

Note: x-amz-* headers, including metadata, can be added to any S3 request by adding each header with a call to SetRequestHeader. This applies to all S3 methods, even if not explicitly stated.

Returns 1 for success, 0 for failure.

# $localFilePath is a string
# $contentType is a string
# $bucketPath is a string
# $objectName is a string
$status = $http->S3_UploadFile($localFilePath, $contentType, $bucketPath, $objectName);

Uploads a file to the Amazon S3 service.

Note: x-amz-* headers, including metadata, can be added to any S3 request by adding each header with a call to SetRequestHeader. This applies to all S3 methods, even if not explicitly stated.

Returns 1 for success, 0 for failure.

S3 Upload File

# $objectContent is a string
# $charset is a string
# $contentType is a string
# $bucketPath is a string
# $objectName is a string
$status = $http->S3_UploadString($objectContent, $charset, $contentType, $bucketPath, $objectName);

Uploads an in-memory string to the Amazon S3 service. This is the same as UploadFile, except that the file contents are from an in-memory string instead of a local file. Internal to this method, the objectContent is converted to the character encoding specified by charset prior to uploading.

Note: x-amz-* headers, including metadata, can be added to any S3 request by adding each header with a call to SetRequestHeader. This applies to all S3 methods, even if not explicitly stated.

Returns 1 for success, 0 for failure.

S3 Upload String

# $path is a string
$status = $http->SaveLastError($path);

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

Returns 1 for success, 0 for failure.

# $domain is a string
# $cookieXml is a string
$status = $http->SetCookieXml($domain, $cookieXml);

Restores cookies for a particular domain. It is assumed that the cookie XML was previously retrieved via the GetCookieXml method, and saved to some sort of persistent storage, such as within a database table. It is then possible for an application to restore the cookies by calling this method.

Returns 1 for success, 0 for failure.

# $privKey is a CkPrivateKey
$status = $http->SetOAuthRsaKey($privKey);

Introduced in version 9.5.0.39

Sets the RSA key to be used with OAuth authentication when the RSA-SHA1 OAuth signature method is used (see the OAuthSigMethod property).

Returns 1 for success, 0 for failure.

# $headerFieldName is a string
# $headerFieldValue is a string
$$http->SetRequestHeader($headerFieldName, $headerFieldValue);

Adds a custom header field to any HTTP request sent by a method that does not use the HTTP request object. These methods include Download, DownloadAppend, GetHead, PostBinary, PostMime, PostXml, PutBinary, PutText, QuickDeleteStr, QuickGet, QuickGetObj, QuickGetStr, QuickPutStr, XmlRpc, and XmlRpcPut.

Cookies may be explictly added by calling this method passing "Cookie" for the headerFieldName.

The RemoveRequestHeader method can be called to remove a custom header.

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.)

# $cert is a CkCert
$status = $http->SetSslClientCert($cert);

Allows for a client-side certificate to be used for an SSL connection.

Returns 1 for success, 0 for failure.

# $pemDataOrPath is a string
# $pemPassword is a string
$status = $http->SetSslClientCertPem($pemDataOrPath, $pemPassword);

Allows for a client-side certificate + private key to be used for the SSL / TLS connection (often called 2-way SSL).

Returns 1 for success, 0 for failure.

How to Create a PEM that Contains Certificates and a Private Key

# $pfxPath is a string
# $pfxPassword is a string
$status = $http->SetSslClientCertPfx($pfxPath, $pfxPassword);

Allows for a client-side certificate + private key to be used for the SSL / TLS connection (often called 2-way SSL).

Returns 1 for success, 0 for failure.

# $millisec is an integer
$$http->SleepMs($millisec);

Convenience method to force the calling process to sleep for a number of milliseconds.

# $domain is a string
# $port is an integer
# $ssl is a bool
# $req is a CkHttpRequest
$retval = $http->SynchronousRequest($domain, $port, $ssl, $req);

Sends an explicit HttpRequest to an HTTP server and returns an HttpResponse object. The HttpResponse object provides full access to the response including all headers and the response body. This method may be used to send POST requests, as well as GET, HEAD, file uploads, and XMLHTTP.

How URL Syntax Relates to SynchronousRequest

WebDAV PROPFIND using SynchronousRequest

Simple HTTP POST

Debugging HTTP

Send XMLHttpRequest using PUT, GET, DELETE, or any HTTP Request Method

Adding Cookies to an HTTP Request

# $unlockCode is a string
$status = $http->UnlockComponent($unlockCode);

Unlocks the Http class/component. It is necessary to call Http.UnlockComponent before calling any other methods. Passing any string to UnlockComponent will automatically activate a 30-day trial period.

Returns 1 for success, 0 for failure.

Diagnosing UnlockComponent Problems

UnlockComponent LastErrorText shows exact string passed to it.

Verify UnlockComponent Success w/ Permanent Unlock Code

LastErrorText Standard Information

# $str is a string
# $outStr is a CkString (output)
$status = $http->UrlDecode($str, $outStr);
$retStr = $http->urlDecode($str);

URL decodes a string.

Returns 1 for success, 0 for failure.

# $str is a string
# $outStr is a CkString (output)
$status = $http->UrlEncode($str, $outStr);
$retStr = $http->urlEncode($str);

URL encodes a string.

Returns 1 for success, 0 for failure.

# $urlEndpoint is a string
# $xmlIn is a string
# $outStr is a CkString (output)
$status = $http->XmlRpc($urlEndpoint, $xmlIn, $outStr);
$retStr = $http->xmlRpc($urlEndpoint, $xmlIn);

Makes an XML RPC call to a URL endpoint. The XML string is passed in an HTTP POST, and the XML response is returned.

Returns 1 for success, 0 for failure.

HTTP XMLRPC Example

# $urlEndpoint is a string
# $xmlIn is a string
# $outStr is a CkString (output)
$status = $http->XmlRpcPut($urlEndpoint, $xmlIn, $outStr);
$retStr = $http->xmlRpcPut($urlEndpoint, $xmlIn);

Same as XmlRpc, but uses the HTTP PUT method instead of the POST method.

Returns 1 for success, 0 for failure.