2017-09-12 22:42:36 +02:00
<?xml version="1.0" encoding="UTF-8" ?>
2020-01-26 16:01:49 +01:00
<class name= "HTTPRequest" inherits= "Node" version= "3.2" >
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"}
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.")
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]
2017-09-12 22:42:36 +02:00
</description>
<tutorials >
2019-11-07 01:51:31 +01:00
<link > https://docs.godotengine.org/en/latest/tutorials/networking/http_request_class.html</link>
2018-11-05 08:46:27 +01:00
<link > https://docs.godotengine.org/en/latest/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.
2017-09-12 22:42:36 +02:00
</description>
</method>
</methods>
<members >
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" >
2017-12-10 20:32:34 +01:00
Maximum allowed size for response bodies.
2017-09-12 22:42:36 +02:00
</member>
2019-11-24 13:20:24 +01:00
<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>
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>
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>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_REQUEST_FAILED" value= "8" enum= "Result" >
2020-01-23 11:14:14 +01:00
Request failed (currently unused).
2017-09-12 22:42:36 +02:00
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_DOWNLOAD_FILE_CANT_OPEN" value= "9" enum= "Result" >
2017-09-12 22:42:36 +02:00
HTTPRequest couldn't open the download file.
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_DOWNLOAD_FILE_WRITE_ERROR" value= "10" enum= "Result" >
2017-09-12 22:42:36 +02:00
HTTPRequest couldn't write to the download file.
</constant>
2017-11-24 23:16:30 +01:00
<constant name= "RESULT_REDIRECT_LIMIT_REACHED" value= "11" 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>
2019-07-10 16:06:23 +02:00
<constant name= "RESULT_TIMEOUT" value= "12" enum= "Result" >
</constant>
2017-09-12 22:42:36 +02:00
</constants>
</class>