227 lines
8.2 KiB
Text
227 lines
8.2 KiB
Text
|
.. _doc_http_client_class:
|
||
|
|
|
||
|
|
HTTP client class
|
||
|
|
=================
|
||
|
|
|
||
|
|
:ref:`HTTPClient <class_HTTPClient>` provides low-level access to HTTP communication.
|
||
|
|
For a higher-level interface, you may want to take a look at :ref:`HTTPRequest <class_HTTPRequest>` first,
|
||
|
|
which has a tutorial available :ref:`here <doc_http_request_class>`.
|
||
|
|
|
||
|
|
.. warning::
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
Here's an example of using the :ref:`HTTPClient <class_HTTPClient>`
|
||
|
|
class. It's just a script, so it can be run by executing:
|
||
|
|
|
||
|
|
.. tabs::
|
||
|
|
|
||
|
|
.. code-tab:: console GDScript
|
||
|
|
|
||
|
|
c:\godot> godot -s http_test.gd
|
||
|
|
|
||
|
|
.. code-tab:: console C#
|
||
|
|
|
||
|
|
c:\godot> godot -s HTTPTest.cs
|
||
|
|
|
||
|
|
It will connect and fetch a website.
|
||
|
|
|
||
|
|
.. tabs::
|
||
|
|
|
||
|
|
.. code-tab:: gdscript GDScript
|
||
|
|
|
||
|
|
extends SceneTree
|
||
|
|
|
||
|
|
# HTTPClient demo
|
||
|
|
# This simple class can do HTTP requests; it will not block, but it needs to be polled.
|
||
|
|
|
||
|
|
func _init():
|
||
|
|
var err = 0
|
||
|
|
var http = HTTPClient.new() # Create the Client.
|
||
|
|
|
||
|
|
err = http.connect_to_host("www.php.net", 80) # Connect to host/port.
|
||
|
|
assert(err == OK) # Make sure connection is OK.
|
||
|
|
|
||
|
|
# Wait until resolved and connected.
|
||
|
|
while http.get_status() == HTTPClient.STATUS_CONNECTING or http.get_status() == HTTPClient.STATUS_RESOLVING:
|
||
|
|
http.poll()
|
||
|
|
print("Connecting...")
|
||
|
|
if not OS.has_feature("web"):
|
||
|
|
OS.delay_msec(500)
|
||
|
|
else:
|
||
|
|
yield(Engine.get_main_loop(), "idle_frame")
|
||
|
|
|
||
|
|
assert(http.get_status() == HTTPClient.STATUS_CONNECTED) # Check if the connection was made successfully.
|
||
|
|
|
||
|
|
# Some headers
|
||
|
|
var headers = [
|
||
|
|
"User-Agent: Pirulo/1.0 (Godot)",
|
||
|
|
"Accept: */*"
|
||
|
|
]
|
||
|
|
|
||
|
|
err = http.request(HTTPClient.METHOD_GET, "/ChangeLog-5.php", headers) # Request a page from the site (this one was chunked..)
|
||
|
|
assert(err == OK) # Make sure all is OK.
|
||
|
|
|
||
|
|
while http.get_status() == HTTPClient.STATUS_REQUESTING:
|
||
|
|
# Keep polling for as long as the request is being processed.
|
||
|
|
http.poll()
|
||
|
|
print("Requesting...")
|
||
|
|
if OS.has_feature("web"):
|
||
|
|
# Synchronous HTTP requests are not supported on the web,
|
||
|
|
# so wait for the next main loop iteration.
|
||
|
|
yield(Engine.get_main_loop(), "idle_frame")
|
||
|
|
else:
|
||
|
|
OS.delay_msec(500)
|
||
|
|
|
||
|
|
assert(http.get_status() == HTTPClient.STATUS_BODY or http.get_status() == HTTPClient.STATUS_CONNECTED) # Make sure request finished well.
|
||
|
|
|
||
|
|
print("response? ", http.has_response()) # Site might not have a response.
|
||
|
|
|
||
|
|
if http.has_response():
|
||
|
|
# If there is a response...
|
||
|
|
|
||
|
|
headers = http.get_response_headers_as_dictionary() # Get response headers.
|
||
|
|
print("code: ", http.get_response_code()) # Show response code.
|
||
|
|
print("**headers:\\n", headers) # Show headers.
|
||
|
|
|
||
|
|
# Getting the HTTP Body
|
||
|
|
|
||
|
|
if http.is_response_chunked():
|
||
|
|
# Does it use chunks?
|
||
|
|
print("Response is Chunked!")
|
||
|
|
else:
|
||
|
|
# Or just plain Content-Length
|
||
|
|
var bl = http.get_response_body_length()
|
||
|
|
print("Response Length: ", bl)
|
||
|
|
|
||
|
|
# This method works for both anyway
|
||
|
|
|
||
|
|
var rb = PoolByteArray() # Array that will hold the data.
|
||
|
|
|
||
|
|
while http.get_status() == HTTPClient.STATUS_BODY:
|
||
|
|
# While there is body left to be read
|
||
|
|
http.poll()
|
||
|
|
# Get a chunk.
|
||
|
|
var chunk = http.read_response_body_chunk()
|
||
|
|
if chunk.size() == 0:
|
||
|
|
if not OS.has_feature("web"):
|
||
|
|
# Got nothing, wait for buffers to fill a bit.
|
||
|
|
OS.delay_usec(1000)
|
||
|
|
else:
|
||
|
|
yield(Engine.get_main_loop(), "idle_frame")
|
||
|
|
else:
|
||
|
|
rb = rb + chunk # Append to read buffer.
|
||
|
|
# Done!
|
||
|
|
|
||
|
|
print("bytes got: ", rb.size())
|
||
|
|
var text = rb.get_string_from_ascii()
|
||
|
|
print("Text: ", text)
|
||
|
|
|
||
|
|
quit()
|
||
|
|
|
||
|
|
.. code-tab:: csharp
|
||
|
|
|
||
|
|
class HTTPTest : SceneTree
|
||
|
|
{
|
||
|
|
// HTTPClient demo.
|
||
|
|
// This simple class can make HTTP requests; it will not block, but it needs to be polled.
|
||
|
|
public override async void _Initialize()
|
||
|
|
{
|
||
|
|
Error err;
|
||
|
|
HTTPClient http = new HTTPClient(); // Create the client.
|
||
|
|
|
||
|
|
err = http.ConnectToHost("www.php.net", 80); // Connect to host/port.
|
||
|
|
Debug.Assert(err == Error.Ok); // Make sure the connection is OK.
|
||
|
|
|
||
|
|
// Wait until resolved and connected.
|
||
|
|
while (http.GetStatus() == HTTPClient.Status.Connecting || http.GetStatus() == HTTPClient.Status.Resolving)
|
||
|
|
{
|
||
|
|
http.Poll();
|
||
|
|
GD.Print("Connecting...");
|
||
|
|
OS.DelayMsec(500);
|
||
|
|
}
|
||
|
|
|
||
|
|
Debug.Assert(http.GetStatus() == HTTPClient.Status.Connected); // Check if the connection was made successfully.
|
||
|
|
|
||
|
|
// Some headers.
|
||
|
|
string[] headers = { "User-Agent: Pirulo/1.0 (Godot)", "Accept: */*" };
|
||
|
|
|
||
|
|
err = http.Request(HTTPClient.Method.Get, "/ChangeLog-5.php", headers); // Request a page from the site.
|
||
|
|
Debug.Assert(err == Error.Ok); // Make sure all is OK.
|
||
|
|
|
||
|
|
// Keep polling for as long as the request is being processed.
|
||
|
|
while (http.GetStatus() == HTTPClient.Status.Requesting)
|
||
|
|
{
|
||
|
|
http.Poll();
|
||
|
|
GD.Print("Requesting...");
|
||
|
|
if (OS.HasFeature("web"))
|
||
|
|
{
|
||
|
|
// Synchronous HTTP requests are not supported on the web,
|
||
|
|
// so wait for the next main loop iteration.
|
||
|
|
await ToSignal(Engine.GetMainLoop(), "idle_frame");
|
||
|
|
}
|
||
|
|
else
|
||
|
|
{
|
||
|
|
OS.DelayMsec(500);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
Debug.Assert(http.GetStatus() == HTTPClient.Status.Body || http.GetStatus() == HTTPClient.Status.Connected); // Make sure the request finished well.
|
||
|
|
|
||
|
|
GD.Print("Response? ", http.HasResponse()); // The site might not have a response.
|
||
|
|
|
||
|
|
// If there is a response...
|
||
|
|
if (http.HasResponse())
|
||
|
|
{
|
||
|
|
headers = http.GetResponseHeaders(); // Get response headers.
|
||
|
|
GD.Print("Code: ", http.GetResponseCode()); // Show response code.
|
||
|
|
GD.Print("Headers:");
|
||
|
|
foreach (string header in headers)
|
||
|
|
{
|
||
|
|
// Show headers.
|
||
|
|
GD.Print(header);
|
||
|
|
}
|
||
|
|
|
||
|
|
if (http.IsResponseChunked())
|
||
|
|
{
|
||
|
|
// Does it use chunks?
|
||
|
|
GD.Print("Response is Chunked!");
|
||
|
|
}
|
||
|
|
else
|
||
|
|
{
|
||
|
|
// Or just Content-Length.
|
||
|
|
GD.Print("Response Length: ", http.GetResponseBodyLength());
|
||
|
|
}
|
||
|
|
|
||
|
|
// This method works for both anyways.
|
||
|
|
List<byte> rb = new List<byte>(); // List that will hold the data.
|
||
|
|
|
||
|
|
// While there is data left to be read...
|
||
|
|
while (http.GetStatus() == HTTPClient.Status.Body)
|
||
|
|
{
|
||
|
|
http.Poll();
|
||
|
|
byte[] chunk = http.ReadResponseBodyChunk(); // Read a chunk.
|
||
|
|
if (chunk.Length == 0)
|
||
|
|
{
|
||
|
|
// If nothing was read, wait for the buffer to fill.
|
||
|
|
OS.DelayMsec(500);
|
||
|
|
}
|
||
|
|
else
|
||
|
|
{
|
||
|
|
// Append the chunk to the read buffer.
|
||
|
|
rb.AddRange(chunk);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
|
||
|
|
// Done!
|
||
|
|
GD.Print("Bytes Downloaded: ", rb.Count);
|
||
|
|
string text = Encoding.ASCII.GetString(rb.ToArray());
|
||
|
|
GD.Print(text);
|
||
|
|
}
|
||
|
|
Quit();
|
||
|
|
}
|
||
|
|
}
|