godot/doc/classes/HTTPRequest.xml
Hugo Locurcio 1f7f28a1eb
Document HTTPRequest not supporting request data with GET method
This also improves the HTTPClient class documentation to be easier
to read and more informative.

This closes #40564.

(cherry picked from commit 2f577facc9)
2020-08-31 15:29:43 +02:00

198 lines
9.1 KiB
XML

<?xml version="1.0" encoding="UTF-8" ?>
<class name="HTTPRequest" inherits="Node" version="3.2">
<brief_description>
A node with the ability to send HTTP(S) requests.
</brief_description>
<description>
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]
func _ready():
# Create an HTTP request node and connect its completion signal.
var http_request = HTTPRequest.new()
add_child(http_request)
http_request.connect("request_completed", self, "_http_request_completed")
# Perform a GET request. The URL below returns JSON as of writing.
var error = http_request.request("https://httpbin.org/get")
if error != OK:
push_error("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.
var body = {"name": "Godette"}
var 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.")
# Called when the HTTP request is completed.
func _http_request_completed(result, response_code, headers, body):
var response = parse_json(body.get_string_from_utf8())
# Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
print(response.headers["User-Agent"])
[/codeblock]
[b]Example of loading and displaying an image using HTTPRequest:[/b]
[codeblock]
func _ready():
# Create an HTTP request node and connect its completion signal.
var http_request = HTTPRequest.new()
add_child(http_request)
http_request.connect("request_completed", self, "_http_request_completed")
# Perform the HTTP request. The URL below returns a PNG image as of writing.
var error = http_request.request("https://via.placeholder.com/512")
if error != OK:
push_error("An error occurred in the HTTP request.")
# Called when the HTTP request is completed.
func _http_request_completed(result, response_code, headers, body):
var image = Image.new()
var error = image.load_png_from_buffer(body)
if error != OK:
push_error("Couldn't load the image.")
var texture = ImageTexture.new()
texture.create_from_image(image)
# Display the image in a TextureRect node.
var texture_rect = TextureRect.new()
add_child(texture_rect)
texture_rect.texture = texture
[/codeblock]
[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.
</description>
<tutorials>
<link>https://docs.godotengine.org/en/latest/tutorials/networking/http_request_class.html</link>
<link>https://docs.godotengine.org/en/latest/tutorials/networking/ssl_certificates.html</link>
</tutorials>
<methods>
<method name="cancel_request">
<return type="void">
</return>
<description>
Cancels the current request.
</description>
</method>
<method name="get_body_size" qualifiers="const">
<return type="int">
</return>
<description>
Returns the response body length.
[b]Note:[/b] Some Web servers may not send a body length. In this case, the value returned will be [code]-1[/code]. If using chunked transfer encoding, the body length will also be [code]-1[/code].
</description>
</method>
<method name="get_downloaded_bytes" qualifiers="const">
<return type="int">
</return>
<description>
Returns the amount of bytes this HTTPRequest downloaded.
</description>
</method>
<method name="get_http_client_status" qualifiers="const">
<return type="int" enum="HTTPClient.Status">
</return>
<description>
Returns the current status of the underlying [HTTPClient]. See [enum HTTPClient.Status].
</description>
</method>
<method name="request">
<return type="int" enum="Error">
</return>
<argument index="0" name="url" type="String">
</argument>
<argument index="1" name="custom_headers" type="PoolStringArray" default="PoolStringArray( )">
</argument>
<argument index="2" name="ssl_validate_domain" type="bool" default="true">
</argument>
<argument index="3" name="method" type="int" enum="HTTPClient.Method" default="0">
</argument>
<argument index="4" name="request_data" type="String" default="&quot;&quot;">
</argument>
<description>
Creates request on the underlying [HTTPClient]. If there is no configuration errors, it tries to connect using [method HTTPClient.connect_to_host] and passes parameters onto [method HTTPClient.request].
Returns [constant OK] if request is successfully created. (Does not imply that the server has responded), [constant ERR_UNCONFIGURED] if not in the tree, [constant ERR_BUSY] if still processing previous request, [constant ERR_INVALID_PARAMETER] if given string is not a valid URL format, or [constant ERR_CANT_CONNECT] if not using thread and the [HTTPClient] cannot connect to host.
[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.http_escape] for an example.
</description>
</method>
</methods>
<members>
<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.
</member>
<member name="download_chunk_size" type="int" setter="set_download_chunk_size" getter="get_download_chunk_size" default="4096">
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.
</member>
<member name="download_file" type="String" setter="set_download_file" getter="get_download_file" default="&quot;&quot;">
The file to download into. Will output any received file into it.
</member>
<member name="max_redirects" type="int" setter="set_max_redirects" getter="get_max_redirects" default="8">
Maximum number of allowed redirects.
</member>
<member name="timeout" type="int" setter="set_timeout" getter="get_timeout" default="0">
</member>
<member name="use_threads" type="bool" setter="set_use_threads" getter="is_using_threads" default="false">
If [code]true[/code], multithreading is used to improve performance.
</member>
</members>
<signals>
<signal name="request_completed">
<argument index="0" name="result" type="int">
</argument>
<argument index="1" name="response_code" type="int">
</argument>
<argument index="2" name="headers" type="PoolStringArray">
</argument>
<argument index="3" name="body" type="PoolByteArray">
</argument>
<description>
Emitted when a request is completed.
</description>
</signal>
</signals>
<constants>
<constant name="RESULT_SUCCESS" value="0" enum="Result">
Request successful.
</constant>
<constant name="RESULT_CHUNKED_BODY_SIZE_MISMATCH" value="1" enum="Result">
</constant>
<constant name="RESULT_CANT_CONNECT" value="2" enum="Result">
Request failed while connecting.
</constant>
<constant name="RESULT_CANT_RESOLVE" value="3" enum="Result">
Request failed while resolving.
</constant>
<constant name="RESULT_CONNECTION_ERROR" value="4" enum="Result">
Request failed due to connection (read/write) error.
</constant>
<constant name="RESULT_SSL_HANDSHAKE_ERROR" value="5" enum="Result">
Request failed on SSL handshake.
</constant>
<constant name="RESULT_NO_RESPONSE" value="6" enum="Result">
Request does not have a response (yet).
</constant>
<constant name="RESULT_BODY_SIZE_LIMIT_EXCEEDED" value="7" enum="Result">
Request exceeded its maximum size limit, see [member body_size_limit].
</constant>
<constant name="RESULT_REQUEST_FAILED" value="8" enum="Result">
Request failed (currently unused).
</constant>
<constant name="RESULT_DOWNLOAD_FILE_CANT_OPEN" value="9" enum="Result">
HTTPRequest couldn't open the download file.
</constant>
<constant name="RESULT_DOWNLOAD_FILE_WRITE_ERROR" value="10" enum="Result">
HTTPRequest couldn't write to the download file.
</constant>
<constant name="RESULT_REDIRECT_LIMIT_REACHED" value="11" enum="Result">
Request reached its maximum redirect limit, see [member max_redirects].
</constant>
<constant name="RESULT_TIMEOUT" value="12" enum="Result">
</constant>
</constants>
</class>