diff options
Diffstat (limited to 'doc/classes/HTTPRequest.xml')
| -rw-r--r-- | doc/classes/HTTPRequest.xml | 106 |
1 files changed, 94 insertions, 12 deletions
diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml index dc88c53810..f2ab93033a 100644 --- a/doc/classes/HTTPRequest.xml +++ b/doc/classes/HTTPRequest.xml @@ -7,7 +7,8 @@ A node with the ability to send HTTP requests. Uses [HTTPClient] internally. Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP. [b]Example of contacting a REST API and printing one of its returned fields:[/b] - [codeblock] + [codeblocks] + [gdscript] func _ready(): # Create an HTTP request node and connect its completion signal. var http_request = HTTPRequest.new() @@ -23,7 +24,7 @@ # Note: Don't make simultaneous requests using a single HTTPRequest node. # The snippet below is provided for reference only. var body = {"name": "Godette"} - var error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body) + error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body) if error != OK: push_error("An error occurred in the HTTP request.") @@ -34,9 +35,48 @@ # Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org). print(response.headers["User-Agent"]) - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + // Create an HTTP request node and connect its completion signal. + var httpRequest = new HTTPRequest(); + AddChild(httpRequest); + httpRequest.Connect("request_completed", this, nameof(HttpRequestCompleted)); + + // Perform a GET request. The URL below returns JSON as of writing. + Error error = httpRequest.Request("https://httpbin.org/get"); + if (error != Error.Ok) + { + GD.PushError("An error occurred in the HTTP request."); + } + + // Perform a POST request. The URL below returns JSON as of writing. + // Note: Don't make simultaneous requests using a single HTTPRequest node. + // The snippet below is provided for reference only. + string[] body = { "name", "Godette" }; + // GDScript to_json is non existent, so we use JSON.Print() here. + error = httpRequest.Request("https://httpbin.org/post", null, true, HTTPClient.Method.Post, JSON.Print(body)); + if (error != Error.Ok) + { + GD.PushError("An error occurred in the HTTP request."); + } + } + + + // Called when the HTTP request is completed. + private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body) + { + // GDScript parse_json is non existent so we have to use JSON.parse, which has a slightly different syntax. + var response = JSON.Parse(body.GetStringFromUTF8()).Result as Godot.Collections.Dictionary; + // Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org). + GD.Print((response["headers"] as Godot.Collections.Dictionary)["User-Agent"]); + } + [/csharp] + [/codeblocks] [b]Example of loading and displaying an image using HTTPRequest:[/b] - [codeblock] + [codeblocks] + [gdscript] func _ready(): # Create an HTTP request node and connect its completion signal. var http_request = HTTPRequest.new() @@ -51,6 +91,9 @@ # Called when the HTTP request is completed. func _http_request_completed(result, response_code, headers, body): + if result != HTTPRequest.RESULT_SUCCESS: + push_error("Image couldn't be downloaded. Try a different image.") + var image = Image.new() var error = image.load_png_from_buffer(body) if error != OK: @@ -63,13 +106,52 @@ var texture_rect = TextureRect.new() add_child(texture_rect) texture_rect.texture = texture - [/codeblock] + [/gdscript] + [csharp] + public override void _Ready() + { + // Create an HTTP request node and connect its completion signal. + var httpRequest = new HTTPRequest(); + AddChild(httpRequest); + httpRequest.Connect("request_completed", this, nameof(HttpRequestCompleted)); + + // Perform the HTTP request. The URL below returns a PNG image as of writing. + Error error = httpRequest.Request("https://via.placeholder.com/512"); + if (error != Error.Ok) + { + GD.PushError("An error occurred in the HTTP request."); + } + } + + + // Called when the HTTP request is completed. + private void HttpRequestCompleted(int result, int response_code, string[] headers, byte[] body) + { + if (result != (int)HTTPRequest.Result.Success) + { + GD.PushError("Image couldn't be downloaded. Try a different image."); + } + var image = new Image(); + Error error = image.LoadPngFromBuffer(body); + if (error != Error.Ok) + { + GD.PushError("Couldn't load the image."); + } + + var texture = new ImageTexture(); + texture.CreateFromImage(image); + + // Display the image in a TextureRect node. + var textureRect = new TextureRect(); + AddChild(textureRect); + textureRect.Texture = texture; + } + [/csharp] + [/codeblocks] - [b]Gzipped response bodies[/b] - HttpRequest will automatically handle decompression of response bodies. - A "Accept-Encoding" header will be automatically added to each of your requests, unless one is already specified. - Any response with a "Content-Encoding: gzip" header will automatically be decompressed and delivered to you as a uncompressed bytes. + [b]Gzipped response bodies[/b]: HTTPRequest will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. [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 title="Making HTTP requests">https://docs.godotengine.org/en/latest/tutorials/networking/http_request_class.html</link> @@ -146,16 +228,16 @@ <members> <member name="accept_gzip" type="bool" setter="set_accept_gzip" getter="is_accepting_gzip" default="true"> If [code]true[/code], this header will be added to each request: [code]Accept-Encoding: gzip, deflate[/code] telling servers that it's okay to compress response bodies. - Any Reponse body declaring a [code]Content-Encoding[/code] of either [code]gzip[/code] or [code]deflate[/code] will then be automatically decompressed, and the uncompressed bytes will be delivered via [code]request_completed[/code]. + Any Response body declaring a [code]Content-Encoding[/code] of either [code]gzip[/code] or [code]deflate[/code] will then be automatically decompressed, and the uncompressed bytes will be delivered via [code]request_completed[/code]. If the user has specified their own [code]Accept-Encoding[/code] header, then no header will be added regaurdless of [code]accept_gzip[/code]. If [code]false[/code] no header will be added, and no decompression will be performed on response bodies. The raw bytes of the response body will be returned via [code]request_completed[/code]. </member> <member name="body_size_limit" type="int" setter="set_body_size_limit" getter="get_body_size_limit" default="-1"> Maximum allowed size for response bodies. If the response body is compressed, this will be used as the maximum allowed size for the decompressed body. </member> - <member name="download_chunk_size" type="int" setter="set_download_chunk_size" getter="get_download_chunk_size" default="4096"> + <member name="download_chunk_size" type="int" setter="set_download_chunk_size" getter="get_download_chunk_size" default="65536"> The size of the buffer used and maximum bytes to read per iteration. See [member HTTPClient.read_chunk_size]. - Set this to a higher value (e.g. 65536 for 64 KiB) when downloading large files to achieve better speeds at the cost of memory. + Set this to a lower value (e.g. 4096 for 4 KiB) when downloading small files to decrease memory usage at the cost of download speeds. </member> <member name="download_file" type="String" setter="set_download_file" getter="get_download_file" default=""""> The file to download into. Will output any received file into it. |