virtualx-engine/doc/classes/HTTPClient.xml

<?xml version="1.0" encoding="UTF-8" ?>
<class name="HTTPClient" inherits="Reference" category="Core" version="3.0-beta">
	<brief_description>
		Hyper-text transfer protocol client.
	</brief_description>
	<description>
		Hyper-text transfer protocol client. Supports SSL and SSL server certificate verification.
		Can be reused to connect to different hosts and make many requests.
	</description>
	<tutorials>
	</tutorials>
	<demos>
	</demos>
	<methods>
		<method name="close">
			<return type="void">
			</return>
			<description>
				Cloces the current connection, allows for reusal of [code]HTTPClient[/code].
			</description>
		</method>
		<method name="connect_to_host">
			<return type="int" enum="Error">
			</return>
			<argument index="0" name="host" type="String">
			</argument>
			<argument index="1" name="port" type="int">
			</argument>
			<argument index="2" name="use_ssl" type="bool" default="false">
			</argument>
			<argument index="3" name="verify_host" type="bool" default="true">
			</argument>
			<description>
				Connect to a host. This needs to be done before any requests are sent.
				The host should not have http:// prepended but will strip the protocol identifier if provided.
				verify_host will check the SSL identity of the host if set to true.
			</description>
		</method>
		<method name="get_connection" qualifiers="const">
			<return type="StreamPeer">
			</return>
			<description>
				Return current connection.
			</description>
		</method>
		<method name="get_response_body_length" qualifiers="const">
			<return type="int">
			</return>
			<description>
				Return the response's body length.
			</description>
		</method>
		<method name="get_response_code" qualifiers="const">
			<return type="int">
			</return>
			<description>
				Return the HTTP status code of the response.
			</description>
		</method>
		<method name="get_response_headers">
			<return type="PoolStringArray">
			</return>
			<description>
				Return the response headers.
			</description>
		</method>
		<method name="get_response_headers_as_dictionary">
			<return type="Dictionary">
			</return>
			<description>
				Returns all response headers as dictionary where the case-sensitivity of the keys and values is kept like the server delivers it. A value is a simple String, this string can have more than one value where "; " is used as separator.
				Structure: ("key":"value1; value2")
				Example: (content-length:12), (Content-Type:application/json; charset=UTF-8)
			</description>
		</method>
		<method name="get_status" qualifiers="const">
			<return type="int" enum="HTTPClient.Status">
			</return>
			<description>
				Returns a STATUS_* enum constant. Need to call [method poll] in order to get status updates.
			</description>
		</method>
		<method name="has_response" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Return whether this [code]HTTPClient[/code] has a response available.
			</description>
		</method>
		<method name="is_blocking_mode_enabled" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Return whether blocking mode is enabled.
			</description>
		</method>
		<method name="is_response_chunked" qualifiers="const">
			<return type="bool">
			</return>
			<description>
				Return whether this [code]HTTPClient[/code] has a response that is chunked.
			</description>
		</method>
		<method name="poll">
			<return type="int" enum="Error">
			</return>
			<description>
				This needs to be called in order to have any request processed. Check results with [method get_status]
			</description>
		</method>
		<method name="query_string_from_dict">
			<return type="String">
			</return>
			<argument index="0" name="fields" type="Dictionary">
			</argument>
			<description>
				Generates a GET/POST application/x-www-form-urlencoded style query string from a provided dictionary, e.g.:
				[codeblock]
				var fields = {"username": "user", "password": "pass"}
				String queryString = httpClient.query_string_from_dict(fields)
				returns:= "username=user&amp;password=pass"
				[/codeblock]
			</description>
		</method>
		<method name="read_response_body_chunk">
			<return type="PoolByteArray">
			</return>
			<description>
				Reads one chunk from the response.
			</description>
		</method>
		<method name="request">
			<return type="int" enum="Error">
			</return>
			<argument index="0" name="method" type="int" enum="HTTPClient.Method">
			</argument>
			<argument index="1" name="url" type="String">
			</argument>
			<argument index="2" name="headers" type="PoolStringArray">
			</argument>
			<argument index="3" name="body" type="String" default="&quot;&quot;">
			</argument>
			<description>
				Sends a request to the connected host. The url is what is normally behind the hostname, i.e. in [code]http://somehost.com/index.php[/code], url would be "index.php".
				Headers are HTTP request headers.
				To create a POST request with query strings to push to the server, do:
				[codeblock]
				var fields = {"username" : "user", "password" : "pass"}
				var queryString = httpClient.query_string_from_dict(fields)
				var headers = ["Content-Type: application/x-www-form-urlencoded", "Content-Length: " + str(queryString.length())]
				var result = httpClient.request(httpClient.METHOD_POST, "index.php", headers, queryString)
				[/codeblock]
			</description>
		</method>
		<method name="request_raw">
			<return type="int" enum="Error">
			</return>
			<argument index="0" name="method" type="int" enum="HTTPClient.Method">
			</argument>
			<argument index="1" name="url" type="String">
			</argument>
			<argument index="2" name="headers" type="PoolStringArray">
			</argument>
			<argument index="3" name="body" type="PoolByteArray">
			</argument>
			<description>
				Sends a raw request to the connected host. The url is what is normally behind the hostname, i.e. in [code]http://somehost.com/index.php[/code], url would be "index.php".
				Headers are HTTP request headers.
				Sends body raw, as a byte array, does not encode it in any way.
			</description>
		</method>
		<method name="set_blocking_mode">
			<return type="void">
			</return>
			<argument index="0" name="enabled" type="bool">
			</argument>
			<description>
				If set to true, execution will block until all data is read from the response.
			</description>
		</method>
		<method name="set_connection">
			<return type="void">
			</return>
			<argument index="0" name="connection" type="StreamPeer">
			</argument>
			<description>
				Set connection to use, for this client.
			</description>
		</method>
		<method name="set_read_chunk_size">
			<return type="void">
			</return>
			<argument index="0" name="bytes" type="int">
			</argument>
			<description>
				Sets the size of the buffer used and maximum bytes to read per iteration. see [method read_response_body_chunk]
			</description>
		</method>
	</methods>
	<constants>
		<constant name="METHOD_GET" value="0" enum="Method">
		</constant>
		<constant name="METHOD_HEAD" value="1" enum="Method">
		</constant>
		<constant name="METHOD_POST" value="2" enum="Method">
		</constant>
		<constant name="METHOD_PUT" value="3" enum="Method">
		</constant>
		<constant name="METHOD_DELETE" value="4" enum="Method">
		</constant>
		<constant name="METHOD_OPTIONS" value="5" enum="Method">
		</constant>
		<constant name="METHOD_TRACE" value="6" enum="Method">
		</constant>
		<constant name="METHOD_CONNECT" value="7" enum="Method">
		</constant>
		<constant name="METHOD_MAX" value="8" enum="Method">
		</constant>
		<constant name="STATUS_DISCONNECTED" value="0" enum="Status">
		</constant>
		<constant name="STATUS_RESOLVING" value="1" enum="Status">
		</constant>
		<constant name="STATUS_CANT_RESOLVE" value="2" enum="Status">
		</constant>
		<constant name="STATUS_CONNECTING" value="3" enum="Status">
		</constant>
		<constant name="STATUS_CANT_CONNECT" value="4" enum="Status">
		</constant>
		<constant name="STATUS_CONNECTED" value="5" enum="Status">
		</constant>
		<constant name="STATUS_REQUESTING" value="6" enum="Status">
		</constant>
		<constant name="STATUS_BODY" value="7" enum="Status">
		</constant>
		<constant name="STATUS_CONNECTION_ERROR" value="8" enum="Status">
		</constant>
		<constant name="STATUS_SSL_HANDSHAKE_ERROR" value="9" enum="Status">
		</constant>
		<constant name="RESPONSE_CONTINUE" value="100" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_SWITCHING_PROTOCOLS" value="101" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_PROCESSING" value="102" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_OK" value="200" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_CREATED" value="201" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_ACCEPTED" value="202" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_NON_AUTHORITATIVE_INFORMATION" value="203" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_NO_CONTENT" value="204" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_RESET_CONTENT" value="205" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_PARTIAL_CONTENT" value="206" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_MULTI_STATUS" value="207" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_IM_USED" value="226" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_MULTIPLE_CHOICES" value="300" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_MOVED_PERMANENTLY" value="301" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_FOUND" value="302" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_SEE_OTHER" value="303" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_NOT_MODIFIED" value="304" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_TEMPORARY_REDIRECT" value="307" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_BAD_REQUEST" value="400" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_UNAUTHORIZED" value="401" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_PAYMENT_REQUIRED" value="402" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_FORBIDDEN" value="403" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_NOT_FOUND" value="404" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_METHOD_NOT_ALLOWED" value="405" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_NOT_ACCEPTABLE" value="406" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_PROXY_AUTHENTICATION_REQUIRED" value="407" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_REQUEST_TIMEOUT" value="408" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_CONFLICT" value="409" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_GONE" value="410" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_LENGTH_REQUIRED" value="411" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_PRECONDITION_FAILED" value="412" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_REQUEST_ENTITY_TOO_LARGE" value="413" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_REQUEST_URI_TOO_LONG" value="414" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_UNSUPPORTED_MEDIA_TYPE" value="415" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_REQUESTED_RANGE_NOT_SATISFIABLE" value="416" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_EXPECTATION_FAILED" value="417" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_UNPROCESSABLE_ENTITY" value="422" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_LOCKED" value="423" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_FAILED_DEPENDENCY" value="424" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_UPGRADE_REQUIRED" value="426" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_INTERNAL_SERVER_ERROR" value="500" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_NOT_IMPLEMENTED" value="501" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_BAD_GATEWAY" value="502" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_SERVICE_UNAVAILABLE" value="503" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_GATEWAY_TIMEOUT" value="504" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_HTTP_VERSION_NOT_SUPPORTED" value="505" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_INSUFFICIENT_STORAGE" value="507" enum="ResponseCode">
		</constant>
		<constant name="RESPONSE_NOT_EXTENDED" value="510" enum="ResponseCode">
		</constant>
	</constants>
</class>