Difference between revisions of "Lua API:HTTP"

From The Powder Toy
Jump to: navigation, search
m (Update content as per 8928280)
(Update as per commit afefd045)
Line 28: Line 28:
 
== Methods ==
 
== Methods ==
  
=== http.request ===
+
=== http.get ===
  HTTPRequest http.request(string uri, [table post_params, [table headers]])
+
  HTTPRequest http.get(string uri, [table headers])
Constructs a HTTPRequest object and starts the underlying request immediately with the URI, post parameters and headers supplied. Both optional tables are collections of string key and string value pairs. The request is a POST if post parameters are supplied, a GET otherwise.
+
Constructs an HTTPRequest object and starts the underlying GET request immediately with the URI and headers supplied. The optional table argument is a collection of string key and string value pairs.
 +
 
 +
=== http.post ===
 +
HTTPRequest http.post(string uri, table post_params, [table headers])
 +
Same as http.get, except the underlying request is a POST. Post parameters are passed in the extra table argument, a collection of string key and string value pairs.

Revision as of 19:46, 6 December 2020

The HTTP API provides access to basic HTTP functionality. Depending on how TPT is built, it may only work with secure sites (ones that use TLS, i.e. HTTPS) or it may even be wholly unable to actually complete HTTP requests; see relevant #defines in Config.h.

Classes

HTTPRequest

HTTPRequest:status

string HTTPRequest:status()

Returns one of the following:

  • "running" if the request hasn't finished yet;
  • "done" if the request has finished and the response body is ready to be read;
  • "dead" if the request is dead, i.e. if it has been cancelled or if the response body has been read.

HTTPRequest:progress

number, number HTTPRequest:progress()

If the request is not dead, returns the size of the response body in bytes in the first return value (-1 if the size is not known), and the number of bytes received so far in the second. If the request is dead, returns nothing.

HTTPRequest:cancel

nil HTTPRequest:cancel()

Cancels the request. Does nothing if the request is dead.

HTTPRequest:finish

string, number HTTPRequest:finish()

Finishes the request and returns the response body and the status code. Call this only when HTTPRequest:status returns "done". Does and returns nothing if the request is dead.

Non-standard status codes of note are 601, which is returned by plain HTTP requests if TPT is built with ENFORCE_HTTPS, and 604, which is returned by all requests if TPT is built with NOHTTP. Note that both codes may be returned for other reasons.

Methods

http.get

HTTPRequest http.get(string uri, [table headers])

Constructs an HTTPRequest object and starts the underlying GET request immediately with the URI and headers supplied. The optional table argument is a collection of string key and string value pairs.

http.post

HTTPRequest http.post(string uri, table post_params, [table headers])

Same as http.get, except the underlying request is a POST. Post parameters are passed in the extra table argument, a collection of string key and string value pairs.