diff options
Diffstat (limited to 'doc/classes/HTTPClient.xml')
| -rw-r--r-- | doc/classes/HTTPClient.xml | 31 |
1 files changed, 18 insertions, 13 deletions
diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index 325e6ca48e..c91ddccaa4 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -4,8 +4,8 @@ Hyper-text transfer protocol client. </brief_description> <description> - Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases. - Note that this client only needs to connect to a host once (see [method connect_to_host]) to send multiple requests. Because of this, methods that take URLs usually take just the part after the host instead of the full URL, as the client is already connected to a host. See [method request] for a full example and to get started. + Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases. See [HTTPRequest] for an higher-level alternative. + [b]Note:[/b] This client only needs to connect to a host once (see [method connect_to_host]) to send multiple requests. Because of this, methods that take URLs usually take just the part after the host instead of the full URL, as the client is already connected to a host. See [method request] for a full example and to get started. A [HTTPClient] should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports SSL and SSL server certificate verification. HTTP status codes in the 2xx range indicate success, 3xx redirection (i.e. "try again, but over here"), 4xx something was wrong with the request, and 5xx something went wrong on the server's side. For more information on HTTP, see https://developer.mozilla.org/en-US/docs/Web/HTTP (or read RFC 2616 to get it straight from the source: https://tools.ietf.org/html/rfc2616). </description> @@ -33,7 +33,7 @@ <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. + Connects 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. If no [code]port[/code] is specified (or [code]-1[/code] is used), it is automatically set to 80 for HTTP and 443 for HTTPS (if [code]use_ssl[/code] is enabled). [code]verify_host[/code] will check the SSL identity of the host if set to [code]true[/code]. @@ -64,16 +64,21 @@ <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) + Returns all response headers as a Dictionary of structure [code]{ "key": "value1; value2" }[/code] 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. + [b]Example:[/b] + [codeblock] + { + "content-length": 12, + "Content-Type": "application/json; charset=UTF-8", + } + [/codeblock] </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. + Returns a [code]STATUS_*[/code] enum constant. Need to call [method poll] in order to get status updates. </description> </method> <method name="has_response" qualifiers="const"> @@ -107,13 +112,13 @@ [codeblock] var fields = {"username": "user", "password": "pass"} String query_string = http_client.query_string_from_dict(fields) - # returns: "username=user&password=pass" + # Returns "username=user&password=pass" [/codeblock] - Furthermore, if a key has a null value, only the key itself is added, without equal sign and value. If the value is an array, for each value in it a pair with the same key is added. + Furthermore, if a key has a [code]null[/code] value, only the key itself is added, without equal sign and value. If the value is an array, for each value in it a pair with the same key is added. [codeblock] var fields = {"single": 123, "not_valued": null, "multiple": [22, 33, 44]} String query_string = http_client.query_string_from_dict(fields) - # returns: "single=123&not_valued&multiple=22&multiple=33&multiple=44" + # Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44" [/codeblock] </description> </method> @@ -175,7 +180,7 @@ </method> </methods> <members> - <member name="blocking_mode_enabled" type="bool" setter="set_blocking_mode" getter="is_blocking_mode_enabled"> + <member name="blocking_mode_enabled" type="bool" setter="set_blocking_mode" getter="is_blocking_mode_enabled" default="false"> If [code]true[/code], execution will block until all data is read from the response. </member> <member name="connection" type="StreamPeer" setter="set_connection" getter="get_connection"> @@ -298,10 +303,10 @@ HTTP status code [code]304 Not Modified[/code]. A conditional GET or HEAD request has been received and would have resulted in a 200 OK response if it were not for the fact that the condition evaluated to [code]false[/code]. </constant> <constant name="RESPONSE_USE_PROXY" value="305" enum="ResponseCode"> - HTTP status code [code]305 Use Proxy[/code]. Deprecated. Do not use. + HTTP status code [code]305 Use Proxy[/code]. [i]Deprecated. Do not use.[/i] </constant> <constant name="RESPONSE_SWITCH_PROXY" value="306" enum="ResponseCode"> - HTTP status code [code]306 Switch Proxy[/code]. Deprecated. Do not use. + HTTP status code [code]306 Switch Proxy[/code]. [i]Deprecated. Do not use.[/i] </constant> <constant name="RESPONSE_TEMPORARY_REDIRECT" value="307" enum="ResponseCode"> HTTP status code [code]307 Temporary Redirect[/code]. The target resource resides temporarily under a different URI and the user agent MUST NOT change the request method if it performs an automatic redirection to that URI. |