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

HTTPRequest http.request(string uri, [table post_params, [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.