# HTTPClient

from pandac.PandaModules import HTTPClient

Class : HTTPClient
Description : Handles contacting an HTTP server and retrieving a document. Each HTTPClient object represents a separate context, and stores its own list of cookies, passwords, and certificates; however, a given HTTPClient is capable of making multiple simultaneous requests to the same or different servers.
It is up to the programmer whether one HTTPClient should be used to retrieve all documents, or a separate one should be created each time. There is a default, global HTTPClient available in HTTPClient::get_global_ptr().

## Inheritance:

HTTPClient: ReferenceCount
ReferenceCount: MemoryBase
MemoryBase:

## Methods of HTTPClient:

HTTPClient (Constructor)
addDirectHost
addExpectedServer
addProxy
base64Decode
base64Encode
clearAllCookies
clearCookie
clearDirectHost
clearExpectedServers
clearProxy
copyCookiesFrom
getCipherList
getCookie
getDirectHostSpec
getDocument
getGlobalPtr
getHeader
getHttpVersion
getHttpVersionString
getProxiesForUrl
getProxySpec
getTryAllDirect
getUsername
getVerifySsl
hasCookie
initRandomSeed
loadCertificates
loadClientCertificate
makeChannel
operator =
parseHttpVersionString
postForm
sendCookies
setCipherList
setClientCertificateFilename
setClientCertificatePassphrase
setClientCertificatePem
setCookie
setDirectHostSpec
setHttpVersion
setProxySpec
setTryAllDirect
setUsername
setVerifySsl
writeCookies

## Methods of ReferenceCount:

getClassType
getRefCount
ref
testRefCountIntegrity
testRefCountNonzero
unref

## Constants in HTTPClient:

VSNoVerify | (VerifySSL)
VSNoDateCheck | (VerifySSL)
VSNormal | (VerifySSL)

HTTPClient HTTPClient::HTTPClient(void); Description:

addDirectHost void HTTPClient::add_direct_host(string const &hostname); Description: Adds the indicated name to the set of hostnames that are connected to directly, without using a proxy. This name may be either a DNS name or an IP address, and it may include the * as a wildcard character.

addExpectedServer bool HTTPClient::add_expected_server(string const &server_attributes); Description: Adds the indicated string as a definition of a valid server to contact via https. If no servers have been been added, an https connection will be allowed to any server. If at least one server has been added, an https connection will be allowed to any of the named servers, but none others. The string passed in defines a subset of the server properties that are to be insisted on, using the X509 naming convention, e.g. O=WDI/OU=VRStudio/CN=ttown. It makes sense to use this in conjunction with set_verify_ssl(), which insists that the https connection uses a verifiable certificate.

addProxy void HTTPClient::add_proxy(string const &scheme, URLSpec const &proxy); Description: Adds the indicated proxy host as a proxy for communications on the given scheme. Usually the scheme is "http" or "https". It may be the empty string to indicate a general proxy. The proxy string may be the empty URL to indicate a direct connection.

base64Decode static string HTTPClient::base64_decode(string const &s); Description: Implements HTTPAuthorization::base64_decode(). This is provided here just as a convenient place to publish it for access by the scripting language; C++ code should probably use HTTPAuthorization directly.

base64Encode static string HTTPClient::base64_encode(string const &s); Description: Implements HTTPAuthorization::base64_encode(). This is provided here just as a convenient place to publish it for access by the scripting language; C++ code should probably use HTTPAuthorization directly.

clearAllCookies void HTTPClient::clear_all_cookies(void); Description: Removes the all stored cookies from the client.

clearCookie bool HTTPClient::clear_cookie(HTTPCookie const &cookie); Description: Removes the cookie with the matching domain/path/name from the client's list of cookies. Returns true if it was removed, false if the cookie was not matched.

clearDirectHost void HTTPClient::clear_direct_host(void); Description: Resets the set of direct hosts to empty. Subsequent calls to add_direct_host() may be made to build up the list of hosts that do not require a proxy connection.

clearExpectedServers void HTTPClient::clear_expected_servers(void); Description: Clears the set of expected servers; the HTTPClient will allow an https connection to any server.

clearProxy void HTTPClient::clear_proxy(void); Description: Resets the proxy spec to empty. Subsequent calls to add_proxy() may be made to build up the set of proxy servers.

copyCookiesFrom void HTTPClient::copy_cookies_from(HTTPClient const &other); Description: Copies all the cookies from the indicated HTTPClient into this one. Existing cookies in this client are not affected, unless they are shadowed by the new cookies.

getCipherList string const &HTTPClient::get_cipher_list(void) const; Description: Returns the set of ciphers as set by set_cipher_list(). See set_cipher_list().

getCookie HTTPCookie HTTPClient::get_cookie(HTTPCookie const &cookie) const; Description: Looks up and returns the cookie in the client matching the given cookie's domain/path/name. If there is no matching cookie, returns an empty cookie.

getDirectHostSpec string HTTPClient::get_direct_host_spec(void) const; Description: Returns the set of hosts that should be connected to directly, without using a proxy, as a semicolon-separated list of hostnames that may contain wildcard characters ("*").

getDocument PointerTo< HTTPChannel > HTTPClient::get_document(URLSpec const &url); Description: Opens the named document for reading. Returns a new HTTPChannel object whether the document is successfully read or not; you can test is_valid() and get_return_code() to determine whether the document was retrieved.

getGlobalPtr static HTTPClient *HTTPClient::get_global_ptr(void); Description: Returns the default global HTTPClient.

getHeader PointerTo< HTTPChannel > HTTPClient::get_header(URLSpec const &url); Description: Like get_document(), except only the header associated with the document is retrieved. This may be used to test for existence of the document; it might also return the size of the document (if the server gives us this information).

getHttpVersion HTTPEnum::HTTPVersion HTTPClient::get_http_version(void) const; Description: Returns the client's current setting for HTTP version. See set_http_version().

getHttpVersionString string HTTPClient::get_http_version_string(void) const; Description: Returns the current HTTP version setting as a string, e.g. "HTTP/1.0" or "HTTP/1.1".

getProxiesForUrl void HTTPClient::get_proxies_for_url(URLSpec const &url, vector< URLSpec > &proxies) const; Description: Fills up the indicated vector with the list of URLSpec objects, in the order in which they should be tried, that are appropriate proxies to try for the indicated URL. The empty URL is returned for a direct connection. It is the user's responsibility to empty this vector before calling this method; otherwise, the proxy URL's will simply be appended to the existing list. Description: Returns a semicolon-delimited list of proxies, in the order in which they should be tried, that are appropriate for the indicated URL. The keyword DIRECT indicates a direct connection should be tried.

getProxySpec string HTTPClient::get_proxy_spec(void) const; Description: Returns the complete set of proxies to use for all schemes. This is a string of the form specified by set_proxy_spec(), above. Note that the string returned by this function may not be exactly the same as the string passed into set_proxy_spec(), since the string is regenerated from the internal storage structures and may therefore be reordered.

getTryAllDirect bool HTTPClient::get_try_all_direct(void) const; Description: Returns whether a failed connection through a proxy will be followed up by a direct connection attempt, false otherwise.

getUsername string HTTPClient::get_username(string const &server, string const &realm) const; Description: Returns the username:password string set for this server/realm pair, or empty string if nothing has been set. See set_username().

getVerifySsl HTTPClient::VerifySSL HTTPClient::get_verify_ssl(void) const; Description: Returns whether the client will insist on verifying the identity of the servers it connects to via SSL (that is, https). See set_verify_ssl().

hasCookie bool HTTPClient::has_cookie(HTTPCookie const &cookie) const; Description: Returns true if there is a cookie in the client matching the given cookie's domain/path/name, false otherwise.

initRandomSeed static void HTTPClient::init_random_seed(void); Description: This may be called once, presumably at the beginning of an application, to initialize OpenSSL's random seed. On Windows, it is particularly important to call this at startup if you are going to be perfoming any https operations or otherwise use encryption, since the Windows algorithm for getting a random seed takes 2-3 seconds at startup, but can take 30 seconds or more after you have opened a 3-D graphics window and started rendering. There is no harm in calling this method multiple times, or in not calling it at all.

loadCertificates bool HTTPClient::load_certificates(Filename const &filename); Description: Reads the certificate(s) (delimited by -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----) from the indicated file and makes them known as trusted public keys for validating future connections. Returns true on success, false otherwise.

loadClientCertificate bool HTTPClient::load_client_certificate(void); Description: Attempts to load the certificate named by set_client_certificate_filename() immediately, and returns true if successful, false otherwise. Normally this need not be explicitly called, since it will be called automatically if the server requests a certificate, but it may be useful to determine ahead of time if the certificate can be loaded correctly.

makeChannel PointerTo< HTTPChannel > HTTPClient::make_channel(bool persistent_connection); Description: Returns a new HTTPChannel object that may be used for reading multiple documents using the same connection, for greater network efficiency than calling HTTPClient::get_document() repeatedly (which would force a new connection for each document). Also, HTTPChannel has some additional, less common interface methods than the basic interface methods that exist on HTTPClient; if you wish to call any of these methods you must first obtain an HTTPChannel. Pass true for persistent_connection to gain this network efficiency. If, on the other hand, your intention is to use the channel to retrieve only one document, then pass false to inform the server that we will be dropping the connection after the first document.

operator = void HTTPClient::operator =(HTTPClient const &copy); Description:

parseHttpVersionString static HTTPEnum::HTTPVersion HTTPClient::parse_http_version_string(string const &version); Description: Matches the string representing a particular HTTP version against any of the known versions and returns the appropriate enumerated value, or HV_other if the version is unknown.

postForm PointerTo< HTTPChannel > HTTPClient::post_form(URLSpec const &url, string const &body); Description: Posts form data to a particular URL and retrieves the response. Returns a new HTTPChannel object whether the document is successfully read or not; you can test is_valid() and get_return_code() to determine whether the document was retrieved.

sendCookies void HTTPClient::send_cookies(ostream &out, URLSpec const &url); Description: Writes to the indicated ostream a "Cookie" header line for sending the cookies appropriate to the indicated URL along with an HTTP request. This also removes expired cookies.

setCipherList void HTTPClient::set_cipher_list(string const &cipher_list); Description: Specifies the set of ciphers that are to be made available for SSL connections. This is a string as described in the ciphers(1) man page of the OpenSSL documentation (or see http://www.openssl.org/docs/apps/ciphers.html ). If this is not specified, the default is provided by the Config file. You may also specify "DEFAULT" to use the built-in OpenSSL default value.

setClientCertificateFilename void HTTPClient::set_client_certificate_filename(Filename const &filename); Description: Sets the filename of the pem-formatted file that will be read for the client public and private keys if an SSL server requests a certificate. Either this or set_client_certificate_pem() may be used to specify a client certificate.

setClientCertificatePassphrase void HTTPClient::set_client_certificate_passphrase(string const &passphrase); Description: Sets the passphrase used to decrypt the private key in the certificate named by set_client_certificate_filename() or set_client_certificate_pem().

setClientCertificatePem void HTTPClient::set_client_certificate_pem(string const &pem); Description: Sets the pem-formatted contents of the certificate that will be parsed for the client public and private keys if an SSL server requests a certificate. Either this or set_client_certificate_filename() may be used to specify a client certificate.

setCookie void HTTPClient::set_cookie(HTTPCookie const &cookie); Description: Stores the indicated cookie in the client's list of cookies, as if it had been received from a server.

setDirectHostSpec void HTTPClient::set_direct_host_spec(string const &direct_host_spec); Description: Specifies the set of hosts that should be connected to directly, without using a proxy. This is a semicolon-separated list of hostnames that may contain wildcard characters ("*").

setHttpVersion void HTTPClient::set_http_version(HTTPEnum::HTTPVersion version); Description: Specifies the version of HTTP that the client uses to identify itself to the server. The default is HV_11, or HTTP 1.0; you can set this to HV_10 (HTTP 1.0) to request the server use the older interface.

setProxySpec void HTTPClient::set_proxy_spec(string const &proxy_spec); Description: Specifies the complete set of proxies to use for all schemes. This is either a semicolon-delimited set of hostname:ports, or a semicolon-delimited set of pairs of the form "scheme=hostname:port", or a combination. Use the keyword DIRECT, or an empty string, to represent a direct connection. A particular scheme and/or proxy host may be listed more than once. This is a convenience function that can be used in place of explicit calls to add_proxy() for each scheme/proxy pair.

setTryAllDirect void HTTPClient::set_try_all_direct(bool try_all_direct); Description: If this is set true, then after a connection attempt through a proxy fails, we always try a direct connection, regardless of whether the host is listed on the direct_host_spec list. If this is false, a direct attempt is not made when we have a proxy in effect, even if the proxy fails.

setUsername void HTTPClient::set_username(string const &server, string const &realm, string const &username); Description: Specifies the username:password string corresponding to a particular server and/or realm, when demanded by the server. Either or both of the server or realm may be empty; if so, they match anything. Also, the server may be set to the special string "*proxy", which will match any proxy server. If the username is set to the empty string, this clears the password for the particular server/realm pair.

setVerifySsl void HTTPClient::set_verify_ssl(HTTPClient::VerifySSL verify_ssl); Description: Specifies whether the client will insist on verifying the identity of the servers it connects to via SSL (that is, https). The parameter value is an enumerated type which indicates the level of security to which the client will insist upon.

writeCookies void HTTPClient::write_cookies(ostream &out) const; Description: Outputs the complete list of cookies stored on the client, for all domains, including the expired cookies (which will normally not be sent back to a host).

getClassType static TypeHandle ReferenceCount::get_class_type(void); Undocumented function.

getRefCount int ReferenceCount::get_ref_count(void) const; Description: Returns the current reference count.

ref void ReferenceCount::ref(void) const; Description: Explicitly increments the reference count. User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it.

testRefCountIntegrity bool ReferenceCount::test_ref_count_integrity(void) const; Description: Does some easy checks to make sure that the reference count isn't completely bogus. Returns true if ok, false otherwise.

testRefCountNonzero bool ReferenceCount::test_ref_count_nonzero(void) const; Description: Does some easy checks to make sure that the reference count isn't zero, or completely bogus. Returns true if ok, false otherwise.

unref bool ReferenceCount::unref(void) const; Description: Explicitly decrements the reference count. Note that the object will not be implicitly deleted by unref() simply because the reference count drops to zero. (Having a member function delete itself is problematic; plus, we don't have a virtual destructor anyway.) However, see the helper function unref_delete(). User code should avoid using ref() and unref() directly, which can result in missed reference counts. Instead, let a PointerTo object manage the reference counting automatically. This function is const, even though it changes the object, because generally fiddling with an object's reference count isn't considered part of fiddling with the object. An object might be const in other ways, but we still need to accurately count the number of references to it. The return value is true if the new reference count is nonzero, false if it is zero.