diff options
Diffstat (limited to 'doc/classes/HTTPClient.xml')
| -rw-r--r-- | doc/classes/HTTPClient.xml | 28 |
1 files changed, 14 insertions, 14 deletions
diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index 645f328be0..b3ed38d250 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -7,17 +7,17 @@ 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. [b]Note:[/b] This client only needs to connect to a host once (see [method 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 [method request] for a full example and to get started. - A [HTTPClient] should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports SSL and SSL 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. + A [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 https://developer.mozilla.org/en-US/docs/Web/HTTP (or read RFC 2616 to get it straight from the source: https://tools.ietf.org/html/rfc2616). [b]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] 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. - [b]Note:[/b] It's recommended to use transport encryption (SSL/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. - [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. - [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. - [b]Warning:[/b] SSL/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. + [b]Note:[/b] 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. + [b]Note:[/b] 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 [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. + [b]Note:[/b] 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. + [b]Warning:[/b] 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. </description> <tutorials> <link title="HTTP client class">$DOCS_URL/tutorials/networking/http_client_class.html</link> - <link title="SSL certificates">$DOCS_URL/tutorials/networking/ssl_certificates.html</link> + <link title="TLS certificates">$DOCS_URL/tutorials/networking/ssl_certificates.html</link> </tutorials> <methods> <method name="close"> @@ -30,13 +30,13 @@ <return type="int" enum="Error" /> <param index="0" name="host" type="String" /> <param index="1" name="port" type="int" default="-1" /> - <param index="2" name="use_ssl" type="bool" default="false" /> + <param index="2" name="use_tls" type="bool" default="false" /> <param index="3" name="verify_host" type="bool" default="true" /> <description> Connects to a host. This needs to be done before any requests are sent. The host should not have http:// prepended but will strip the protocol identifier if provided. - If no [code]port[/code] is specified (or [code]-1[/code] is used), it is automatically set to 80 for HTTP and 443 for HTTPS (if [code]use_ssl[/code] is enabled). - [code]verify_host[/code] will check the SSL identity of the host if set to [code]true[/code]. + If no [param port] is specified (or [code]-1[/code] is used), it is automatically set to 80 for HTTP and 443 for HTTPS (if [param use_tls] is enabled). + [param verify_host] will check the TLS identity of the host if set to [code]true[/code]. </description> </method> <method name="get_response_body_length" qualifiers="const"> @@ -158,7 +158,7 @@ var result = new HTTPClient().Request(HTTPClient.Method.Post, "index.php", headers, queryString); [/csharp] [/codeblocks] - [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.uri_encode] for an example. + [b]Note:[/b] The [param body] parameter is ignored if [param method] 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.uri_encode] for an example. </description> </method> <method name="request_raw"> @@ -180,7 +180,7 @@ <param index="1" name="port" type="int" /> <description> Sets the proxy server for HTTP requests. - The proxy server is unset if [code]host[/code] is empty or [code]port[/code] is -1. + The proxy server is unset if [param host] is empty or [param port] is -1. </description> </method> <method name="set_https_proxy"> @@ -189,7 +189,7 @@ <param index="1" name="port" type="int" /> <description> Sets the proxy server for HTTPS requests. - The proxy server is unset if [code]host[/code] is empty or [code]port[/code] is -1. + The proxy server is unset if [param host] is empty or [param port] is -1. </description> </method> </methods> @@ -262,8 +262,8 @@ <constant name="STATUS_CONNECTION_ERROR" value="8" enum="Status"> Status: Error in HTTP connection. </constant> - <constant name="STATUS_SSL_HANDSHAKE_ERROR" value="9" enum="Status"> - Status: Error in SSL handshake. + <constant name="STATUS_TLS_HANDSHAKE_ERROR" value="9" enum="Status"> + Status: Error in TLS handshake. </constant> <constant name="RESPONSE_CONTINUE" value="100" enum="ResponseCode"> HTTP status code [code]100 Continue[/code]. Interim response that indicates everything so far is OK and that the client should continue with the request (or ignore this status if already finished). |