Struct HttpClient

pub struct HttpClient { /* private fields */ }

Expand description

Godot class HTTPClient.

Inherits RefCounted.

Related symbols:

http_client: sidecar module with related enum/flag types
IHttpClient: virtual methods

§Construction

This class is reference-counted. You can create a new instance using HttpClient::new_gd().

§Godot docs

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 the HTTPRequest node for a higher-level alternative.

Note: This client only needs to connect to a host once (see 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 request for a full example and to get started.

An HTTPClient should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports Transport Layer Security (TLS), including 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 MDN’s documentation on HTTP (or read RFC 2616 to get it straight from the source).

Note: When exporting to Android, make sure to enable the INTERNET permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

Note: It’s recommended to use transport encryption (TLS) and to avoid sending sensitive information (such as login credentials) in HTTP GET URL parameters. Consider using HTTP POST requests or HTTP headers for such information instead.

Note: When performing HTTP requests from a project exported to Web, keep in mind the remote server may not allow requests from foreign origins due to CORS. If you host the server in question, you should modify its backend to allow requests from foreign origins by adding the Access-Control-Allow-Origin: * HTTP header.

Note: TLS support is currently limited to TLSv1.2 and TLSv1.3. Attempting to connect to a server that only supports older (insecure) TLS versions will return an error.

Warning: TLS certificate revocation and certificate pinning are currently not supported. Revoked certificates are accepted as long as they are otherwise valid. If this is a concern, you may want to use automatically managed certificates with a short validity period.

Implementations§

§

impl HttpClient

pub fn connect_to_host(&mut self, host: impl AsArg<GString>) -> Error

To set the default parameters, use connect_to_host_ex and its builder methods. See the book for detailed usage instructions. Connects to a host. This needs to be done before any requests are sent.

If no port is specified (or -1 is used), it is automatically set to 80 for HTTP and 443 for HTTPS. You can pass the optional tls_options parameter to customize the trusted certification authorities, or the common name verification when using HTTPS. See client and client_unsafe.

pub fn connect_to_host_ex<'ex>( &'ex mut self, host: impl AsArg<GString> + 'ex, ) -> ExConnectToHost<'ex>

Connects to a host. This needs to be done before any requests are sent.

If no port is specified (or -1 is used), it is automatically set to 80 for HTTP and 443 for HTTPS. You can pass the optional tls_options parameter to customize the trusted certification authorities, or the common name verification when using HTTPS. See client and client_unsafe.

pub fn set_connection(&mut self, connection: impl AsArg<Option<Gd<StreamPeer>>>)

pub fn get_connection(&self) -> Option<Gd<StreamPeer>>

pub fn request_raw( &mut self, method: Method, url: impl AsArg<GString>, headers: &PackedArray<GString>, body: &PackedArray<u8>, ) -> Error

Sends a raw HTTP request to the connected host with the given method.

The URL parameter is usually just the part after the host, so for https://example.com/index.php, it is /index.php. When sending requests to an HTTP proxy server, it should be an absolute URL. For Method::OPTIONS requests, * is also allowed. For Method::CONNECT requests, it should be the authority component (host:port).

headers are HTTP request headers.

Sends the body data raw, as a byte array and does not encode it in any way.

pub fn request( &mut self, method: Method, url: impl AsArg<GString>, headers: &PackedArray<GString>, ) -> Error

To set the default parameters, use request_ex and its builder methods. See the book for detailed usage instructions. Sends an HTTP request to the connected host with the given method.

The URL parameter is usually just the part after the host, so for https://example.com/index.php, it is /index.php. When sending requests to an HTTP proxy server, it should be an absolute URL. For Method::OPTIONS requests, * is also allowed. For Method::CONNECT requests, it should be the authority component (host:port).

headers are HTTP request headers.

To create a POST request with query strings to push to the server, do:

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)

Note: The body parameter is ignored if method is 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 uri_encode for an example.

pub fn request_ex<'ex>( &'ex mut self, method: Method, url: impl AsArg<GString> + 'ex, headers: &'ex PackedArray<GString>, ) -> ExRequest<'ex>

Sends an HTTP request to the connected host with the given method.

The URL parameter is usually just the part after the host, so for https://example.com/index.php, it is /index.php. When sending requests to an HTTP proxy server, it should be an absolute URL. For Method::OPTIONS requests, * is also allowed. For Method::CONNECT requests, it should be the authority component (host:port).

headers are HTTP request headers.

To create a POST request with query strings to push to the server, do:

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)

Note: The body parameter is ignored if method is 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 uri_encode for an example.

pub fn close(&mut self)

Closes the current connection, allowing reuse of this HTTPClient.

pub fn has_response(&self) -> bool

If true, this HTTPClient has a response available.

pub fn is_response_chunked(&self) -> bool

If true, this HTTPClient has a response that is chunked.

pub fn get_response_code(&self) -> i32

Returns the response’s HTTP status code.

pub fn get_response_headers(&self) -> PackedArray<GString>

Returns the response headers.

pub fn get_response_headers_as_dictionary(&self) -> Dictionary<Variant, Variant>

Returns all response headers as a Dictionary. Each entry is composed by the header name, and a String containing the values separated by "; ". The casing is kept the same as the headers were received.

{
	"content-length": 12,
	"Content-Type": "application/json; charset=UTF-8",
}

pub fn get_response_body_length(&self) -> i64

Returns the response’s body length.

Note: Some Web servers may not send a body length. In this case, the value returned will be -1. If using chunked transfer encoding, the body length will also be -1.

Note: This function always returns -1 on the Web platform due to browsers limitations.

pub fn read_response_body_chunk(&mut self) -> PackedArray<u8>

Reads one chunk from the response.

pub fn set_read_chunk_size(&mut self, bytes: i32)

pub fn get_read_chunk_size(&self) -> i32

pub fn set_blocking_mode(&mut self, enabled: bool)

pub fn is_blocking_mode_enabled(&self) -> bool

pub fn get_status(&self) -> Status

Returns a [enum Status] constant. Need to call poll in order to get status updates.

pub fn poll(&mut self) -> Error

This needs to be called in order to have any request processed. Check results with get_status.

pub fn set_http_proxy(&mut self, host: impl AsArg<GString>, port: i32)

Sets the proxy server for HTTP requests.

The proxy server is unset if host is empty or port is -1.

pub fn set_https_proxy(&mut self, host: impl AsArg<GString>, port: i32)

Sets the proxy server for HTTPS requests.

The proxy server is unset if host is empty or port is -1.

pub fn query_string_from_dict(&mut self, fields: &AnyDictionary) -> GString

Generates a GET/POST application/x-www-form-urlencoded style query string from a provided dictionary, e.g.:

var fields = { "username": "user", "password": "pass" }
var query_string = http_client.query_string_from_dict(fields)
# Returns "username=user&password=pass"

Furthermore, if a key has a null 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.

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"

Methods from Deref<Target = RefCounted>§

pub fn get_reference_count(&self) -> i32

Returns the current reference count.

Methods from Deref<Target = Object>§

pub fn get_script(&self) -> Option<Gd<Script>>

pub fn set_script(&mut self, script: impl AsArg<Option<Gd<Script>>>)

pub fn connect( &mut self, signal: impl AsArg<StringName>, callable: &Callable, ) -> Error

pub fn connect_flags( &mut self, signal: impl AsArg<StringName>, callable: &Callable, flags: ConnectFlags, ) -> Error

pub fn get_class(&self) -> GString

Returns the object’s built-in class name, as a String. See also is_class.

Note: This method ignores class_name declarations. If this object’s script has defined a class_name, the base, built-in class name is returned instead.

pub fn is_class(&self, class: impl AsArg<GString>) -> bool

Returns true if the object inherits from the given class. See also get_class.

var sprite2d = Sprite2D.new()
sprite2d.is_class("Sprite2D") # Returns true
sprite2d.is_class("Node")     # Returns true
sprite2d.is_class("Node3D")   # Returns false

Note: This method ignores class_name declarations in the object’s script.

pub fn set(&mut self, property: impl AsArg<StringName>, value: &Variant)

Assigns value to the given property. If the property does not exist or the given value’s type doesn’t match, nothing happens.

var node = Node2D.new()
node.set("global_scale", Vector2(8, 2.5))
print(node.global_scale) # Prints (8.0, 2.5)

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get(&self, property: impl AsArg<StringName>) -> Variant

Returns the Variant value of the given property. If the property does not exist, this method returns null.

var node = Node2D.new()
node.rotation = 1.5
var a = node.get("rotation") # a is 1.5

Note: In C#, property must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn set_indexed( &mut self, property_path: impl AsArg<NodePath>, value: &Variant, )

Assigns a new value to the property identified by the property_path. The path should be a NodePath relative to this object, and can use the colon character (:) to access nested properties.

var node = Node2D.new()
node.set_indexed("position", Vector2(42, 0))
node.set_indexed("position:y", -10)
print(node.position) # Prints (42.0, -10.0)

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

pub fn get_indexed(&self, property_path: impl AsArg<NodePath>) -> Variant

Gets the object’s property indexed by the given property_path. The path should be a NodePath relative to the current object and can use the colon character (:) to access nested properties.

Examples: "position:x" or "material:next_pass:blend_mode".

var node = Node2D.new()
node.position = Vector2(5, -10)
var a = node.get_indexed("position")   # a is Vector2(5, -10)
var b = node.get_indexed("position:y") # b is -10

Note: In C#, property_path must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the PropertyName class to avoid allocating a new StringName on each call.

Note: This method does not support actual paths to nodes in the SceneTree, only sub-property paths. In the context of nodes, use get_node_and_resource instead.

pub fn get_property_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns the object’s property list as an Array of dictionaries. Each Dictionary contains the following entries:

name is the property’s name, as a String;
class_name is an empty StringName, unless the property is VariantType::OBJECT and it inherits from a class;
type is the property’s type, as an int (see [enum Variant.Type]);
hint is how the property is meant to be edited (see [enum PropertyHint]);
hint_string depends on the hint (see [enum PropertyHint]);
usage is a combination of [enum PropertyUsageFlags].

Note: In GDScript, all class members are treated as properties. In C# and GDExtension, it may be necessary to explicitly mark class members as Godot properties using decorators or attributes.

pub fn get_method_list(&self) -> Array<Dictionary<Variant, Variant>>

Returns this object’s methods and their signatures as an Array of dictionaries. Each Dictionary contains the following entries:

name is the name of the method, as a String;
args is an Array of dictionaries representing the arguments;
default_args is the default arguments as an Array of variants;
flags is a combination of [enum MethodFlags];
id is the method’s internal identifier int;
return is the returned value, as a Dictionary;

Note: The dictionaries of args and return are formatted identically to the results of get_property_list, although not all entries are used.

pub fn property_can_revert(&self, property: impl AsArg<StringName>) -> bool

Returns true if the given property has a custom default value. Use property_get_revert to get the property’s default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_can_revert] to customize the default value. If [method _property_can_revert] is not implemented, this method returns false.

pub fn property_get_revert(&self, property: impl AsArg<StringName>) -> Variant

Returns the custom default value of the given property. Use property_can_revert to check if the property has a custom default value.

Note: This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_get_revert] to customize the default value. If [method _property_get_revert] is not implemented, this method returns null.

pub fn set_meta(&mut self, name: impl AsArg<StringName>, value: &Variant)

Adds or changes the entry name inside the object’s metadata. The metadata value can be any Variant, although some types cannot be serialized correctly.

If value is null, the entry is removed. This is the equivalent of using remove_meta. See also has_meta and get_meta.

Note: A metadata’s name must be a valid identifier as per is_valid_identifier method.