Difference between revisions of "Lua API:HTTP"

From The Powder Toy
Jump to: navigation, search
(Add HTTP API page)
 
(Update as per commit afefd045)
 
(2 intermediate revisions by the same user not shown)
Line 1: Line 1:
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 not even be available.
+
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.
assert(http, "HTTP functionality unavailable")
 
  
 
== Classes ==
 
== Classes ==
Line 24: Line 23:
 
  string, number 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.
 
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 ==
 
== 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.
+
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.

Latest 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.