Skip to content
Download

HTTP (function list)

Status: Implemented (API 1.24). Generated from client/clight/idl/clight_api.json by tools/docs/gen_api_reference.py; do not edit by hand. 5 functions, the newest from API 1.20.

Explanations and examples: Filesystem and HTTP. Every function of the http module is listed here in table order. The details of each function follow the table, in the same order. Side: where the function works (server, client, both). Context: the thread it may be called on (Conventions). Since: the API version that added it.

C function Lua Side Context Since
cl_http_request cl.http.request both ANY 1.20
cl_http_cancel cl.http.cancel both ANY 1.20
cl_http_error cl.http.error both ANY 1.20
cl_http_header cl.http.header both ANY 1.20
cl_http_allowed cl.http.allowed both ANY 1.20

cl_http_request

cl_result cl_http_request(cl_str url, const cl_http_opts* opts, cl_http_fn fn, void* user, cl_http_req* out);

Starts a request; at most 4 run at once per mod (more wait in a queue of 32: CL_E_LIMIT beyond). CL_E_PERMISSION_DENIED: the host is not declared or the player did not allow it; CL_E_INVALID_ARGUMENT: not an http(s) URL. The request handle stays valid until the callback has returned.

  • Side: both. Context: ANY (any thread). Since: API 1.20.
  • Lua: cl.http.request
  • C++: clight::http::request(std::string_view url, const cl_http_opts* opts, cl_http_fn fn, void* user) → Expected<HttpReq>
  • The last parameter receives the result. Lua returns it; C++ returns it in Expected<T>.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_http_cancel

cl_result cl_http_cancel(cl_http_req req);

The callback still runs, with status 0 and the error “cancelled”.

  • Side: both. Context: ANY (any thread). Since: API 1.20.
  • Lua: cl.http.cancel, http_req:cancel(...)
  • C++: HttpReq::http_cancel() → Expected<void>; clight::http::cancel(HttpReq req) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_http_error

cl_result cl_http_error(cl_http_req req, char* buf, size_t cap, size_t* out_len);

Why it failed (“” when an answer came).

  • Side: both. Context: ANY (any thread). Since: API 1.20.
  • Lua: cl.http.error, http_req:error(...)
  • C++: HttpReq::http_error() → Expected<std::string>; clight::http::error(HttpReq req) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_http_header

cl_result cl_http_header(cl_http_req req, cl_str name, char* buf, size_t cap, size_t* out_len);

A response header (“Content-Type”; any case). CL_E_NOT_FOUND: not sent.

  • Side: both. Context: ANY (any thread). Since: API 1.20.
  • Lua: cl.http.header, http_req:header(...)
  • C++: HttpReq::http_header(std::string_view name) → Expected<std::string>; clight::http::header(HttpReq req, std::string_view name) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_http_allowed

bool cl_http_allowed(cl_str url);

Whether a request to the URL (or bare host) would be allowed now.

  • Side: both. Context: ANY (any thread). Since: API 1.20.
  • Lua: cl.http.allowed
  • C++: clight::http::allowed(std::string_view url) → bool