Documentation
¶
Overview ¶
A node with the ability to send HTTP requests. Uses graphics.gd/classdb/HTTPClient internally.
Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP.
Warning: See the notes and warnings on graphics.gd/classdb/HTTPClient for limitations, especially regarding TLS security.
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.
Example: Contact a REST API and print one of its returned fields:
package main
import (
"encoding/json"
"graphics.gd/classdb/Engine"
"graphics.gd/classdb/HTTPClient"
"graphics.gd/classdb/HTTPRequest"
"graphics.gd/classdb/Node"
"graphics.gd/variant/Signal"
)
type ExampleHTTP struct {
Node.Extension[ExampleHTTP]
}
func (n *ExampleHTTP) Ready() {
// Create an HTTP request node and connect its completion signal.
var httpRequest = HTTPRequest.New()
n.AsNode().AddChild(httpRequest.AsNode())
httpRequest.OnRequestCompleted(func(result HTTPRequest.Result, response_code int, headers []string, body []byte) {
var Response struct {
Headers map[string]string
}
json.Unmarshal(body, &Response)
// Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
println(Response.Headers["User-Agent"])
// Perform a POST request. The URL below returns JSON as of writing.
body, _ = json.Marshal(map[string]string{"name": "Godette"})
var err = HTTPRequest.Expanded(httpRequest).Request("https://httpbin.org/post", nil, HTTPClient.MethodPost, string(body))
if err != nil {
Engine.Raise(err)
}
}, Signal.OneShot)
// Perform a GET request. The URL below returns JSON as of writing.
var err = HTTPRequest.Expanded(httpRequest).Request("https://httpbin.org/get", nil, HTTPClient.MethodGet, "")
if err != nil {
Engine.Raise(err)
}
// Note: Don't make simultaneous requests using a single HTTPRequest node.
}
Example: Load an image using graphics.gd/classdb/HTTPRequest and display it:
package main
import (
"errors"
"graphics.gd/classdb/Engine"
"graphics.gd/classdb/HTTPRequest"
"graphics.gd/classdb/Image"
"graphics.gd/classdb/ImageTexture"
"graphics.gd/classdb/Node"
"graphics.gd/classdb/TextureRect"
"graphics.gd/variant/Signal"
)
type ExampleDownloadImage struct {
Node.Extension[ExampleDownloadImage]
}
func (n ExampleDownloadImage) Ready() {
var http_request = HTTPRequest.New()
n.AsNode().AddChild(http_request.AsNode())
http_request.AsHTTPRequest().OnRequestCompleted(func(result HTTPRequest.Result, response_code int, headers []string, body []byte) {
if result != HTTPRequest.ResultSuccess {
Engine.Raise(errors.New("Image couldn't be downloaded. Try a different image."))
}
var image = Image.New()
var err = image.LoadPngFromBuffer(body)
if err != nil {
Engine.Raise(errors.New("Couldn't load the image."))
}
var texture = ImageTexture.CreateFromImage(image)
// Display the image in a TextureRect node.
var texture_rect = TextureRect.New()
texture_rect.AsTextureRect().SetTexture(texture.AsTexture2D())
n.AsNode().AddChild(texture_rect.AsNode())
}, Signal.OneShot)
// Perform the HTTP request. The URL below returns a PNG image as of writing.
var error = http_request.Request("https://placehold.co/512")
if error != nil {
panic("An error occurred in the HTTP request.")
}
}
Note: graphics.gd/classdb/HTTPRequest nodes will automatically handle decompression of response bodies. An 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 uncompressed bytes.
Index ¶
- type Advanced
- type Any
- type Expanded
- type Extension
- type ID
- type Instance
- func (self Instance) AcceptGzip() bool
- func (self Instance) AsHTTPRequest() Instance
- func (self Instance) AsNode() Node.Instance
- func (self Instance) AsObject() [1]gd.Object
- func (self Instance) BodySizeLimit() int
- func (self Instance) CancelRequest()
- func (self Instance) DownloadChunkSize() int
- func (self Instance) DownloadFile() string
- func (self Instance) GetBodySize() int
- func (self Instance) GetDownloadedBytes() int
- func (self Instance) GetHttpClientStatus() HTTPClient.Status
- func (self Instance) ID() ID
- func (self Instance) MaxRedirects() int
- func (self Instance) OnRequestCompleted(cb func(result Result, response_code int, headers []string, body []byte), ...)
- func (self Instance) Request(url string) error
- func (self Instance) RequestRaw(url string) error
- func (self Instance) SetAcceptGzip(value bool)
- func (self Instance) SetBodySizeLimit(value int)
- func (self Instance) SetDownloadChunkSize(value int)
- func (self Instance) SetDownloadFile(value string)
- func (self Instance) SetHttpProxy(host string, port int)
- func (self Instance) SetHttpsProxy(host string, port int)
- func (self Instance) SetMaxRedirects(value int)
- func (self *Instance) SetObject(obj [1]gd.Object) bool
- func (self Instance) SetTimeout(value Float.X)
- func (self Instance) SetTlsOptions(client_options TLSOptions.Instance)
- func (self Instance) SetUseThreads(value bool)
- func (self Instance) Timeout() Float.X
- func (self Instance) UseThreads() bool
- func (self Instance) Virtual(name string) reflect.Value
- type Result
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Advanced ¶
type Advanced = class
Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.
type Expanded ¶
type Expanded [1]gdclass.HTTPRequest
func (Expanded) Request ¶
func (self Expanded) Request(url string, custom_headers []string, method HTTPClient.Method, request_data string) error
Creates request on the underlying graphics.gd/classdb/HTTPClient. If there is no configuration errors, it tries to connect using graphics.gd/classdb/HTTPClient.Instance.ConnectToHost and passes parameters onto graphics.gd/classdb/HTTPClient.Instance.Request.
Returns [Ok] if request is successfully created. (Does not imply that the server has responded), [ErrUnconfigured] if not in the tree, [ErrBusy] if still processing previous request, [ErrInvalidParameter] if given string is not a valid URL format, or [ErrCantConnect] if not using thread and the graphics.gd/classdb/HTTPClient cannot connect to host.
Note: When 'method' is [Httpclient.MethodGet], the payload sent via 'request_data' might be ignored by the server or even cause the server to reject the request (check RFC 7231 section 4.3.1 for more details). As a workaround, you can send data as a query string in the URL (see graphics.gd/classdb/String.Instance.UriEncode for an example).
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.
func (Expanded) RequestRaw ¶
func (self Expanded) RequestRaw(url string, custom_headers []string, method HTTPClient.Method, request_data_raw []byte) error
Creates request on the underlying graphics.gd/classdb/HTTPClient using a raw array of bytes for the request body. If there is no configuration errors, it tries to connect using graphics.gd/classdb/HTTPClient.Instance.ConnectToHost and passes parameters onto graphics.gd/classdb/HTTPClient.Instance.Request.
Returns [Ok] if request is successfully created. (Does not imply that the server has responded), [ErrUnconfigured] if not in the tree, [ErrBusy] if still processing previous request, [ErrInvalidParameter] if given string is not a valid URL format, or [ErrCantConnect] if not using thread and the graphics.gd/classdb/HTTPClient cannot connect to host.
type Extension ¶
Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension
func (*Extension[T]) AsHTTPRequest ¶
type ID ¶
ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.
type Instance ¶
type Instance [1]gdclass.HTTPRequest
Instance of the class with convieniently typed arguments and results.
var Nil Instance
Nil is a nil/null instance of the class. Equivalent to the zero value.
func (Instance) AcceptGzip ¶
func (Instance) AsHTTPRequest ¶
func (Instance) BodySizeLimit ¶
func (Instance) DownloadChunkSize ¶
func (Instance) DownloadFile ¶
func (Instance) GetBodySize ¶
Returns the response 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.
func (Instance) GetDownloadedBytes ¶
Returns the number of bytes this HTTPRequest downloaded.
func (Instance) GetHttpClientStatus ¶
func (self Instance) GetHttpClientStatus() HTTPClient.Status
Returns the current status of the underlying graphics.gd/classdb/HTTPClient.
func (Instance) MaxRedirects ¶
func (Instance) OnRequestCompleted ¶
func (Instance) Request ¶
Creates request on the underlying graphics.gd/classdb/HTTPClient. If there is no configuration errors, it tries to connect using graphics.gd/classdb/HTTPClient.Instance.ConnectToHost and passes parameters onto graphics.gd/classdb/HTTPClient.Instance.Request.
Returns [Ok] if request is successfully created. (Does not imply that the server has responded), [ErrUnconfigured] if not in the tree, [ErrBusy] if still processing previous request, [ErrInvalidParameter] if given string is not a valid URL format, or [ErrCantConnect] if not using thread and the graphics.gd/classdb/HTTPClient cannot connect to host.
Note: When 'method' is [Httpclient.MethodGet], the payload sent via 'request_data' might be ignored by the server or even cause the server to reject the request (check RFC 7231 section 4.3.1 for more details). As a workaround, you can send data as a query string in the URL (see graphics.gd/classdb/String.Instance.UriEncode for an example).
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.
func (Instance) RequestRaw ¶
Creates request on the underlying graphics.gd/classdb/HTTPClient using a raw array of bytes for the request body. If there is no configuration errors, it tries to connect using graphics.gd/classdb/HTTPClient.Instance.ConnectToHost and passes parameters onto graphics.gd/classdb/HTTPClient.Instance.Request.
Returns [Ok] if request is successfully created. (Does not imply that the server has responded), [ErrUnconfigured] if not in the tree, [ErrBusy] if still processing previous request, [ErrInvalidParameter] if given string is not a valid URL format, or [ErrCantConnect] if not using thread and the graphics.gd/classdb/HTTPClient cannot connect to host.
func (Instance) SetAcceptGzip ¶
func (Instance) SetBodySizeLimit ¶
func (Instance) SetDownloadChunkSize ¶
func (Instance) SetDownloadFile ¶
func (Instance) SetHttpProxy ¶
Sets the proxy server for HTTP requests.
The proxy server is unset if 'host' is empty or 'port' is -1.
func (Instance) SetHttpsProxy ¶
Sets the proxy server for HTTPS requests.
The proxy server is unset if 'host' is empty or 'port' is -1.
func (Instance) SetMaxRedirects ¶
func (Instance) SetTimeout ¶
func (Instance) SetTlsOptions ¶
func (self Instance) SetTlsOptions(client_options TLSOptions.Instance)
Sets the graphics.gd/classdb/TLSOptions to be used when connecting to an HTTPS server. See graphics.gd/classdb/TLSOptions.Instance.Client.
func (Instance) SetUseThreads ¶
func (Instance) UseThreads ¶
type Result ¶
type Result int //gd:HTTPRequest.Result
const ( // Request successful. ResultSuccess Result = 0 // Request failed due to a mismatch between the expected and actual chunked body size during transfer. Possible causes include network errors, server misconfiguration, or issues with chunked encoding. ResultChunkedBodySizeMismatch Result = 1 // Request failed while connecting. ResultCantConnect Result = 2 // Request failed while resolving. ResultCantResolve Result = 3 // Request failed due to connection (read/write) error. ResultConnectionError Result = 4 // Request failed on TLS handshake. ResultTlsHandshakeError Result = 5 // Request does not have a response (yet). ResultNoResponse Result = 6 // Request exceeded its maximum size limit, see [Instance.BodySizeLimit]. ResultBodySizeLimitExceeded Result = 7 // Request failed due to an error while decompressing the response body. Possible causes include unsupported or incorrect compression format, corrupted data, or incomplete transfer. ResultBodyDecompressFailed Result = 8 // Request failed (currently unused). ResultRequestFailed Result = 9 // HTTPRequest couldn't open the download file. ResultDownloadFileCantOpen Result = 10 // HTTPRequest couldn't write to the download file. ResultDownloadFileWriteError Result = 11 // Request reached its maximum redirect limit, see [Instance.MaxRedirects]. ResultRedirectLimitReached Result = 12 // Request failed due to a timeout. If you expect requests to take a long time, try increasing the value of [Instance.Timeout] or setting it to 0.0 to remove the timeout completely. ResultTimeout Result = 13 )
Source Files