diff options
Diffstat (limited to 'doc/classes/HTTPClient.xml')
| -rw-r--r-- | doc/classes/HTTPClient.xml | 46 |
1 files changed, 35 insertions, 11 deletions
diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index 7e8f0807ac..ddfcdf7724 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -1,18 +1,19 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="HTTPClient" inherits="Reference" version="4.0"> <brief_description> - Hyper-text transfer protocol client. + Low-level 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. See [HTTPRequest] for an higher-level alternative. + 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. [b]See the [HTTPRequest] node for a higher-level alternative.[/b] [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). [b]Note:[/b] When performing HTTP requests from a project exported to HTML5, keep in mind the remote server may not allow requests from foreign origins due to [url=https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS]CORS[/url]. If you host the server in question, you should modify its backend to allow requests from foreign origins by adding the [code]Access-Control-Allow-Origin: *[/code] HTTP header. + [b]Note:[/b] SSL/TLS support is currently limited to TLS 1.0, TLS 1.1, and TLS 1.2. Attempting to connect to a TLS 1.3-only server will return an error. </description> <tutorials> - <link>https://docs.godotengine.org/en/latest/tutorials/networking/http_client_class.html</link> - <link>https://docs.godotengine.org/en/latest/tutorials/networking/ssl_certificates.html</link> + <link title="HTTP client class">https://docs.godotengine.org/en/latest/tutorials/networking/http_client_class.html</link> + <link title="SSL certificates">https://docs.godotengine.org/en/latest/tutorials/networking/ssl_certificates.html</link> </tutorials> <methods> <method name="close"> @@ -111,17 +112,31 @@ </argument> <description> Generates a GET/POST application/x-www-form-urlencoded style query string from a provided dictionary, e.g.: - [codeblock] + [codeblocks] + [gdscript] var fields = {"username": "user", "password": "pass"} var query_string = http_client.query_string_from_dict(fields) # Returns "username=user&password=pass" - [/codeblock] + [/gdscript] + [csharp] + var fields = new Godot.Collections.Dictionary { { "username", "user" }, { "password", "pass" } }; + string queryString = new HTTPClient().QueryStringFromDict(fields); + // Returns "username=user&password=pass" + [/csharp] + [/codeblocks] 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] + [codeblocks] + [gdscript] var fields = {"single": 123, "not_valued": null, "multiple": [22, 33, 44]} var query_string = http_client.query_string_from_dict(fields) # Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44" - [/codeblock] + [/gdscript] + [csharp] + var fields = new Godot.Collections.Dictionary{{"single", 123}, {"notValued", null}, {"multiple", new Godot.Collections.Array{22, 33, 44}}}; + string queryString = new HTTPClient().QueryStringFromDict(fields); + // Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44" + [/csharp] + [/codeblocks] </description> </method> <method name="read_response_body_chunk"> @@ -146,12 +161,21 @@ Sends a request to the connected host. The URL parameter is just the part after the host, so for [code]http://somehost.com/index.php[/code], it is [code]index.php[/code]. Headers are HTTP request headers. For available HTTP methods, see [enum Method]. To create a POST request with query strings to push to the server, do: - [codeblock] + [codeblocks] + [gdscript] var fields = {"username" : "user", "password" : "pass"} var query_string = http_client.query_string_from_dict(fields) var headers = ["Content-Type: application/x-www-form-urlencoded", "Content-Length: " + str(query_string.length())] var result = http_client.request(http_client.METHOD_POST, "index.php", headers, query_string) - [/codeblock] + [/gdscript] + [csharp] + var fields = new Godot.Collections.Dictionary { { "username", "user" }, { "password", "pass" } }; + string queryString = new HTTPClient().QueryStringFromDict(fields); + string[] headers = {"Content-Type: application/x-www-form-urlencoded", "Content-Length: " + queryString.Length}; + var result = new HTTPClient().Request(HTTPClient.Method.Post, "index.php", headers, queryString); + [/csharp] + [/codeblocks] + [b]Note:[/b] The [code]request_data[/code] parameter is ignored if [code]method[/code] is [constant HTTPClient.METHOD_GET]. This is because GET methods can't contain request data. As a workaround, you can pass request data as a query string in the URL. See [method String.uri_encode] for an example. </description> </method> <method name="request_raw"> @@ -179,7 +203,7 @@ <member name="connection" type="StreamPeer" setter="set_connection" getter="get_connection"> The connection to use for this client. </member> - <member name="read_chunk_size" type="int" setter="set_read_chunk_size" getter="get_read_chunk_size" default="4096"> + <member name="read_chunk_size" type="int" setter="set_read_chunk_size" getter="get_read_chunk_size" default="65536"> The size of the buffer used and maximum bytes to read per iteration. See [method read_response_body_chunk]. </member> </members> |