2017-09-12 22:42:36 +02:00
<?xml version="1.0" encoding="UTF-8" ?>
2021-04-26 13:14:51 +02:00
<class name= "HTTPRequest" inherits= "Node" version= "3.4" >
2017-09-12 22:42:36 +02:00
<brief_description >
2019-11-07 01:51:31 +01:00
A node with the ability to send HTTP(S) requests.
2017-09-12 22:42:36 +02:00
</brief_description>
<description >
2017-12-10 20:32:34 +01:00
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.
2019-12-24 23:20:27 +01:00
[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")
2020-07-09 23:24:04 +02:00
# Perform a GET request. The URL below returns JSON as of writing.
2019-12-24 23:20:27 +01:00
var error = http_request.request("https://httpbin.org/get")
if error != OK:
push_error("An error occurred in the HTTP request.")
2020-07-09 23:24:04 +02:00
# 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"}
2020-10-31 19:20:18 +01:00
error = http_request.request("https://httpbin.org/post", [], true, HTTPClient.METHOD_POST, body)
2020-07-09 23:24:04 +02:00
if error != OK:
push_error("An error occurred in the HTTP request.")
2019-12-24 23:20:27 +01:00
# 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]
2019-11-07 01:51:31 +01:00
[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]
2021-05-09 13:05:32 +02:00
[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.
2020-07-20 15:12:36 +02:00
[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.
2020-10-17 14:47:49 +02:00
[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.
2017-09-12 22:42:36 +02:00
</description>
<tutorials >
2021-03-26 10:43:43 +01:00
<link > https://docs.godotengine.org/en/3.3/tutorials/networking/http_request_class.html</link>
<link > https://docs.godotengine.org/en/3.3/tutorials/networking/ssl_certificates.html</link>
2017-09-12 22:42:36 +02:00
</tutorials>
<methods >
<method name= "cancel_request" >
<return type= "void" >
</return>
<description >
2017-12-10 20:32:34 +01:00
Cancels the current request.
2017-09-12 22:42:36 +02:00
</description>
</method>
<method name= "get_body_size" qualifiers= "const" >
<return type= "int" >
</return>
<description >
2017-12-10 20:32:34 +01:00
Returns the response body length.
2019-10-22 20:16:29 +02:00
[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].
2017-09-12 22:42:36 +02:00
</description>
</method>
<method name= "get_downloaded_bytes" qualifiers= "const" >
<return type= "int" >
</return>
<description >
2017-12-10 20:32:34 +01:00
Returns the amount of bytes this HTTPRequest downloaded.
2017-09-12 22:42:36 +02:00
</description>
</method>
<method name= "get_http_client_status" qualifiers= "const" >
<return type= "int" enum= "HTTPClient.Status" >
</return>
<description >
2019-12-06 23:09:20 +01:00
Returns the current status of the underlying [HTTPClient]. See [enum HTTPClient.Status].
2017-09-12 22:42:36 +02:00
</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= """" >
</argument>
<description >
2018-04-20 11:25:06 +02:00
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].
2019-06-27 13:24:03 +02:00
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.
2020-08-03 14:56:53 +02:00
[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.
2017-09-12 22:42:36 +02:00
</description>
</method>
2021-05-09 13:05:32 +02:00
<method name= "request_raw" >
<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_raw" type= "PoolByteArray" default= "PoolByteArray( )" >
</argument>
<description >
Creates request on the underlying [HTTPClient] using a raw array of bytes for the request body. 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.
</description>
</method>
2017-09-12 22:42:36 +02:00
</methods>
<members >
2021-05-09 13:05:32 +02:00
<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].
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>
2019-06-29 12:38:01 +02:00
<member name= "body_size_limit" type= "int" setter= "set_body_size_limit" getter= "get_body_size_limit" default= "-1" >
2021-05-09 13:05:32 +02:00
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.
2017-09-12 22:42:36 +02:00
</member>
2020-10-19 14:41:29 +02:00
<member name= "download_chunk_size" type= "int" setter= "set_download_chunk_size" getter= "get_download_chunk_size" default= "65536" >
2019-11-24 13:20:24 +01:00
The size of the buffer used and maximum bytes to read per iteration. See [member HTTPClient.read_chunk_size].
2020-10-19 14:41:29 +02:00
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.
2019-11-24 13:20:24 +01:00
</member>
2019-06-29 12:38:01 +02:00
<member name= "download_file" type= "String" setter= "set_download_file" getter= "get_download_file" default= """" >
2018-01-11 23:38:35 +01:00
The file to download into. Will output any received file into it.
</member>
2019-06-29 12:38:01 +02:00
<member name= "max_redirects" type= "int" setter= "set_max_redirects" getter= "get_max_redirects" default= "8" >
2017-12-10 20:32:34 +01:00
Maximum number of allowed redirects.
2017-09-12 22:42:36 +02:00
</member>
2019-07-10 16:06:23 +02:00
<member name= "timeout" type= "int" setter= "set_timeout" getter= "get_timeout" default= "0" >
</member>
2019-06-29 12:38:01 +02:00
<member name= "use_threads" type= "bool" setter= "set_use_threads" getter= "is_using_threads" default= "false" >
2018-12-20 13:46:54 +01:00
If [code]true[/code], multithreading is used to improve performance.
2017-09-12 22:42:36 +02:00
</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 >
2019-06-22 01:04:47 +02:00
Emitted when a request is completed.
2017-09-12 22:42:36 +02:00
</description>
</signal>
</signals>
<constants >
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_SUCCESS" value= "0" enum= "Result" >
2017-09-12 22:42:36 +02:00
Request successful.
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_CHUNKED_BODY_SIZE_MISMATCH" value= "1" enum= "Result" >
2017-09-12 22:42:36 +02:00
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_CANT_CONNECT" value= "2" enum= "Result" >
2017-09-12 22:42:36 +02:00
Request failed while connecting.
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_CANT_RESOLVE" value= "3" enum= "Result" >
2017-09-12 22:42:36 +02:00
Request failed while resolving.
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_CONNECTION_ERROR" value= "4" enum= "Result" >
2018-12-29 00:17:09 +01:00
Request failed due to connection (read/write) error.
2017-09-12 22:42:36 +02:00
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_SSL_HANDSHAKE_ERROR" value= "5" enum= "Result" >
2017-09-12 22:42:36 +02:00
Request failed on SSL handshake.
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_NO_RESPONSE" value= "6" enum= "Result" >
2018-12-29 00:17:09 +01:00
Request does not have a response (yet).
2017-09-12 22:42:36 +02:00
</constant>
2021-05-09 13:05:32 +02:00
<constant name= "RESULT_BODY_DECOMPRESS_FAILED" value= "8" enum= "Result" >
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_BODY_SIZE_LIMIT_EXCEEDED" value= "7" enum= "Result" >
2018-12-29 00:17:09 +01:00
Request exceeded its maximum size limit, see [member body_size_limit].
2017-09-12 22:42:36 +02:00
</constant>
2021-05-09 13:05:32 +02:00
<constant name= "RESULT_REQUEST_FAILED" value= "9" enum= "Result" >
2020-01-23 11:14:14 +01:00
Request failed (currently unused).
2017-09-12 22:42:36 +02:00
</constant>
2021-05-09 13:05:32 +02:00
<constant name= "RESULT_DOWNLOAD_FILE_CANT_OPEN" value= "10" enum= "Result" >
2017-09-12 22:42:36 +02:00
HTTPRequest couldn't open the download file.
</constant>
2021-05-09 13:05:32 +02:00
<constant name= "RESULT_DOWNLOAD_FILE_WRITE_ERROR" value= "11" enum= "Result" >
2017-09-12 22:42:36 +02:00
HTTPRequest couldn't write to the download file.
</constant>
2021-05-09 13:05:32 +02:00
<constant name= "RESULT_REDIRECT_LIMIT_REACHED" value= "12" enum= "Result" >
2018-12-29 00:17:09 +01:00
Request reached its maximum redirect limit, see [member max_redirects].
2017-09-12 22:42:36 +02:00
</constant>
2021-05-09 13:05:32 +02:00
<constant name= "RESULT_TIMEOUT" value= "13" enum= "Result" >
2019-07-10 16:06:23 +02:00
</constant>
2017-09-12 22:42:36 +02:00
</constants>
</class>