1
0

APIDump: Reformatted the docs to include type information.

Also fixed a bit of documentation in the CPP source.
This commit is contained in:
Mattes D 2016-09-12 23:21:15 +02:00
parent 08861becc3
commit 2622a8622a
12 changed files with 23340 additions and 2407 deletions

1
Server/.gitignore vendored
View File

@ -32,6 +32,7 @@ motd.txt
*.xml *.xml
mcserver_api.lua mcserver_api.lua
cuberite_api.lua cuberite_api.lua
DuplicateDocs.txt
# Ignore the webadmin certs / privkey, so that no-one commits theirs by accident: # Ignore the webadmin certs / privkey, so that no-one commits theirs by accident:
webadmin/httpscert.crt webadmin/httpscert.crt

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

File diff suppressed because it is too large Load Diff

View File

@ -11,8 +11,7 @@ return
{ {
cNetwork = cNetwork =
{ {
Desc = Desc = [[
[[
This is the namespace for high-level network-related operations. Allows plugins to make TCP This is the namespace for high-level network-related operations. Allows plugins to make TCP
connections to the outside world using a callback-based API.</p> connections to the outside world using a callback-based API.</p>
<p> <p>
@ -21,12 +20,139 @@ return
local Server = cNetwork:Listen(1024, ListenCallbacks); local Server = cNetwork:Listen(1024, ListenCallbacks);
</pre></p> </pre></p>
]], ]],
Functions =
{
Connect =
{
IsStatic = true,
Params =
{
{
Name = "Host",
Type = "string",
},
{
Name = "Port",
Type = "number",
},
{
Name = "LinkCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Begins establishing a (client) TCP connection to the specified host. Uses the LinkCallbacks table to report progress, success, errors and incoming data. Returns false if it fails immediately (bad port value, bad hostname format), true otherwise. Host can be either an IP address or a hostname.",
},
CreateUDPEndpoint =
{
IsStatic = true,
Params =
{
{
Name = "Port",
Type = "number",
},
{
Name = "UDPCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "cUDPEndpoint",
},
},
Notes = "Creates a UDP endpoint that listens for incoming datagrams on the specified port, and can be used to send or broadcast datagrams. Uses the UDPCallbacks to report incoming datagrams or errors. If the endpoint cannot be created, the OnError callback is called with the error details and the returned endpoint will report IsOpen() == false. The plugin needs to store the returned endpoint object for as long as it needs the UDP port open; if the endpoint is garbage-collected by Lua, the socket will be closed and no more incoming data will be reported.<br>If the Port is zero, the OS chooses an available UDP port for the endpoint; use {{cUDPEndpoint}}:GetPort() to query the port number in such case.",
},
EnumLocalIPAddresses =
{
IsStatic = true,
Returns =
{
{
Type = "table",
},
},
Notes = "Returns all local IP addresses for network interfaces currently available on the machine, as an array-table of strings.",
},
HostnameToIP =
{
IsStatic = true,
Params =
{
{
Name = "Host",
Type = "string",
},
{
Name = "LookupCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Begins a DNS lookup to find the IP address(es) for the specified host. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad hostname format), true if the lookup started successfully. Host can be either a hostname or an IP address.",
},
IPToHostname =
{
IsStatic = true,
Params =
{
{
Name = "Address",
Type = "string",
},
{
Name = "LookupCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Begins a reverse-DNS lookup to find out the hostname for the specified IP address. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad address format), true if the lookup started successfully.",
},
Listen =
{
IsStatic = true,
Params =
{
{
Name = "Port",
Type = "number",
},
{
Name = "ListenCallbacks",
Type = "table",
},
},
Returns =
{
{
Type = "cServerHandle",
},
},
Notes = "Starts listening on the specified port. Uses the ListenCallbacks to report incoming connections or errors. Returns a {{cServerHandle}} object representing the server. If the listen operation failed, the OnError callback is called with the error details and the returned server handle will report IsListening() == false. The plugin needs to store the server handle object for as long as it needs the server running, if the server handle is garbage-collected by Lua, the listening socket will be closed and all current connections dropped.",
},
},
AdditionalInfo = AdditionalInfo =
{ {
{ {
Header = "Using callbacks", Header = "Using callbacks",
Contents = Contents = [[
[[
The entire Networking API is callback-based. Whenever an event happens on the network object, a The entire Networking API is callback-based. Whenever an event happens on the network object, a
specific plugin-provided function is called. The callbacks are stored in tables which are passed specific plugin-provided function is called. The callbacks are stored in tables which are passed
to the API functions, each table contains multiple callbacks for the various situations.</p> to the API functions, each table contains multiple callbacks for the various situations.</p>
@ -146,11 +272,9 @@ local UDPCallbacks =
</pre> </pre>
]], ]],
}, },
{ {
Header = "Example client connection", Header = "Example client connection",
Contents = Contents = [[
[[
The following example, adapted from the NetworkTest plugin, shows a simple example of a client The following example, adapted from the NetworkTest plugin, shows a simple example of a client
connection using the cNetwork API. It connects to www.google.com on port 80 (http) and sends a http connection using the cNetwork API. It connects to www.google.com on port 80 (http) and sends a http
request for the front page. It dumps the received data to the console.</p> request for the front page. It dumps the received data to the console.</p>
@ -195,11 +319,9 @@ end
</pre> </pre>
]], ]],
}, },
{ {
Header = "Example server implementation", Header = "Example server implementation",
Contents = Contents = [[
[[
The following example, adapted from the NetworkTest plugin, shows a simple example of creating a The following example, adapted from the NetworkTest plugin, shows a simple example of creating a
server listening on a TCP port using the cNetwork API. The server listens on port 9876 and for server listening on a TCP port using the cNetwork API. The server listens on port 9876 and for
each incoming connection it sends a welcome message and then echoes back whatever the client has each incoming connection it sends a welcome message and then echoes back whatever the client has
@ -283,41 +405,38 @@ g_Server = nil
</pre> </pre>
]], ]],
}, },
}, -- AdditionalInfo
Functions =
{
Connect = { Params = "Host, Port, LinkCallbacks", Return = "bool", IsStatic = true, Notes = "Begins establishing a (client) TCP connection to the specified host. Uses the LinkCallbacks table to report progress, success, errors and incoming data. Returns false if it fails immediately (bad port value, bad hostname format), true otherwise. Host can be either an IP address or a hostname." },
CreateUDPEndpoint = { Params = "Port, UDPCallbacks", Return = "{{cUDPEndpoint|UDPEndpoint}}", IsStatic = true, Notes = "Creates a UDP endpoint that listens for incoming datagrams on the specified port, and can be used to send or broadcast datagrams. Uses the UDPCallbacks to report incoming datagrams or errors. If the endpoint cannot be created, the OnError callback is called with the error details and the returned endpoint will report IsOpen() == false. The plugin needs to store the returned endpoint object for as long as it needs the UDP port open; if the endpoint is garbage-collected by Lua, the socket will be closed and no more incoming data will be reported.<br>If the Port is zero, the OS chooses an available UDP port for the endpoint; use {{cUDPEndpoint}}:GetPort() to query the port number in such case." },
EnumLocalIPAddresses = { Params = "", Return = "array-table of strings", IsStatic = true, Notes = "Returns all local IP addresses for network interfaces currently available on the machine." },
HostnameToIP = { Params = "Host, LookupCallbacks", Return = "bool", IsStatic = true, Notes = "Begins a DNS lookup to find the IP address(es) for the specified host. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad hostname format), true if the lookup started successfully. Host can be either a hostname or an IP address." },
IPToHostname = { Params = "Address, LookupCallbacks", Return = "bool", IsStatic = true, Notes = "Begins a reverse-DNS lookup to find out the hostname for the specified IP address. Uses the LookupCallbacks table to report progress, success or errors. Returns false if it fails immediately (bad address format), true if the lookup started successfully." },
Listen = { Params = "Port, ListenCallbacks", Return = "{{cServerHandle|ServerHandle}}", IsStatic = true, Notes = "Starts listening on the specified port. Uses the ListenCallbacks to report incoming connections or errors. Returns a {{cServerHandle}} object representing the server. If the listen operation failed, the OnError callback is called with the error details and the returned server handle will report IsListening() == false. The plugin needs to store the server handle object for as long as it needs the server running, if the server handle is garbage-collected by Lua, the listening socket will be closed and all current connections dropped." },
}, },
}, -- cNetwork },
cServerHandle = cServerHandle =
{ {
Desc = Desc = [[
[[
This class provides an interface for TCP sockets listening for a connection. In order to listen, the This class provides an interface for TCP sockets listening for a connection. In order to listen, the
plugin needs to use the {{cNetwork}}:Listen() function to create the listening socket.</p> plugin needs to use the {{cNetwork}}:Listen() function to create the listening socket.</p>
<p> <p>
Note that when Lua garbage-collects this class, the listening socket is closed. Therefore the plugin Note that when Lua garbage-collects this class, the listening socket is closed. Therefore the plugin
should keep it referenced in a global variable for as long as it wants the server running. should keep it referenced in a global variable for as long as it wants the server running.
]], ]],
Functions = Functions =
{ {
Close = { Params = "", Return = "", Notes = "Closes the listening socket. No more connections will be accepted, and all current connections will be closed." }, Close =
IsListening = { Params = "", Return = "bool", Notes = "Returns true if the socket is listening." }, {
Notes = "Closes the listening socket. No more connections will be accepted, and all current connections will be closed.",
},
IsListening =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the socket is listening.",
},
}, },
}, -- cServerHandle },
cTCPLink = cTCPLink =
{ {
Desc = Desc = [[
[[
This class wraps a single TCP connection, that has been established. Plugins can create these by This class wraps a single TCP connection, that has been established. Plugins can create these by
calling {{cNetwork}}:Connect() to connect to a remote server, or by listening using calling {{cNetwork}}:Connect() to connect to a remote server, or by listening using
{{cNetwork}}:Listen() and accepting incoming connections. The links are callback-based - when an event {{cNetwork}}:Listen() and accepting incoming connections. The links are callback-based - when an event
@ -332,45 +451,202 @@ g_Server = nil
network. Note that calling Send() before the TLS handshake finishes is supported, but the data is network. Note that calling Send() before the TLS handshake finishes is supported, but the data is
queued internally and only sent once the TLS handshake is completed. queued internally and only sent once the TLS handshake is completed.
]], ]],
Functions = Functions =
{ {
Close = { Params = "", Return = "", Notes = "Closes the link forcefully (TCP RST). There's no guarantee that the last sent data is even being delivered. See also the Shutdown() method." }, Close =
GetLocalIP = { Params = "", Return = "string", Notes = "Returns the IP address of the local endpoint of the TCP connection." }, {
GetLocalPort = { Params = "", Return = "number", Notes = "Returns the port of the local endpoint of the TCP connection." }, Notes = "Closes the link forcefully (TCP RST). There's no guarantee that the last sent data is even being delivered. See also the Shutdown() method.",
GetRemoteIP = { Params = "", Return = "string", Notes = "Returns the IP address of the remote endpoint of the TCP connection." }, },
GetRemotePort = { Params = "", Return = "number", Notes = "Returns the port of the remote endpoint of the TCP connection." }, GetLocalIP =
Send = { Params = "Data", Return = "", Notes = "Sends the data (raw string) to the remote peer. The data is sent asynchronously and there is no report on the success of the send operation, other than the connection being closed or reset by the underlying OS." }, {
Shutdown = { Params = "", Return = "", Notes = "Shuts the socket down for sending data. Notifies the remote peer that there will be no more data coming from us (TCP FIN). The data that is in flight will still be delivered. The underlying socket will be closed when the remote end shuts down as well, or after a timeout." }, Returns =
StartTLSClient = { Params = "OwnCert, OwnPrivateKey, OwnPrivateKeyPassword", Return = "true / nil + ErrMsg", Notes = "Starts a TLS handshake on the link, as a client side of the TLS. The Own___ parameters specify the client certificate and its corresponding private key and password; all three parameters are optional and no client certificate is presented to the remote peer if they are not used or all empty. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic." }, {
StartTLSServer = { Params = "Certificate, PrivateKey, PrivateKeyPassword, StartTLSData", Return = "true / nil + ErrMsg", Notes = "Starts a TLS handshake on the link, as a server side of the TLS. The plugin needs to specify the server certificate and its corresponding private key and password. The StartTLSData can contain data that the link has already reported as received but it should be used as part of the TLS handshake. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic." }, {
Type = "string",
},
},
Notes = "Returns the IP address of the local endpoint of the TCP connection.",
},
GetLocalPort =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the port of the local endpoint of the TCP connection.",
},
GetRemoteIP =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the IP address of the remote endpoint of the TCP connection.",
},
GetRemotePort =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the port of the remote endpoint of the TCP connection.",
},
Send =
{
Params =
{
{
Name = "Data",
Type = "string",
},
},
Notes = "Sends the data (raw string) to the remote peer. The data is sent asynchronously and there is no report on the success of the send operation, other than the connection being closed or reset by the underlying OS.",
},
Shutdown =
{
Notes = "Shuts the socket down for sending data. Notifies the remote peer that there will be no more data coming from us (TCP FIN). The data that is in flight will still be delivered. The underlying socket will be closed when the remote end shuts down as well, or after a timeout.",
},
StartTLSClient =
{
Params =
{
{
Name = "OwnCert",
Type = "string",
},
{
Name = "OwnPrivateKey",
Type = "string",
},
{
Name = "OwnPrivateKeyPassword",
Type = "string",
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrorMessage",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a TLS handshake on the link, as a client side of the TLS. The Own___ parameters specify the client certificate and its corresponding private key and password; all three parameters are optional and no client certificate is presented to the remote peer if they are not used or all empty. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic.",
},
StartTLSServer =
{
Params =
{
{
Name = "Certificate",
Type = "string",
},
{
Name = "PrivateKey",
Type = "string",
},
{
Name = "PrivateKeyPassword",
Type = "string",
},
{
Name = "StartTLSData",
Type = "string",
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrorMessage",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a TLS handshake on the link, as a server side of the TLS. The plugin needs to specify the server certificate and its corresponding private key and password. The StartTLSData can contain data that the link has already reported as received but it should be used as part of the TLS handshake. Once the TLS handshake is started by this call, all incoming data is first decrypted before being sent to the OnReceivedData callback, and all outgoing data is queued until the TLS handshake completes, and then sent encrypted over the link. Returns true on success, nil and optional error message on immediate failure.<br/><b>NOTE:</b> The TLS support in the API is currently experimental and shouldn't be considered safe - there's no peer certificate verification and the error reporting is only basic.",
},
}, },
}, -- cTCPLink },
cUDPEndpoint = cUDPEndpoint =
{ {
Desc = Desc = [[
[[
Represents a UDP socket that is listening for incoming datagrams on a UDP port and can send or broadcast datagrams to other peers on the network. Plugins can create an instance of the endpoint by calling {{cNetwork}}:CreateUDPEndpoint(). The endpoints are callback-based - when a datagram is read from the network, the OnRececeivedData() callback is called with details about the datagram. See the additional information in {{cNetwork}} documentation for details.</p> Represents a UDP socket that is listening for incoming datagrams on a UDP port and can send or broadcast datagrams to other peers on the network. Plugins can create an instance of the endpoint by calling {{cNetwork}}:CreateUDPEndpoint(). The endpoints are callback-based - when a datagram is read from the network, the OnRececeivedData() callback is called with details about the datagram. See the additional information in {{cNetwork}} documentation for details.</p>
<p> <p>
Note that when Lua garbage-collects this class, the listening socket is closed. Therefore the plugin should keep this object referenced in a global variable for as long as it wants the endpoint open. Note that when Lua garbage-collects this class, the listening socket is closed. Therefore the plugin should keep this object referenced in a global variable for as long as it wants the endpoint open.
]], ]],
Functions = Functions =
{ {
Close = { Params = "", Return = "", Notes = "Closes the UDP endpoint. No more datagrams will be reported through the callbacks, the UDP port will be closed." }, Close =
EnableBroadcasts = { Params = "", Return = "", Notes = "Some OSes need this call before they allow UDP broadcasts on an endpoint." }, {
GetPort = { Params = "", Return = "number", Notes = "Returns the local port number of the UDP endpoint listening for incoming datagrams. Especially useful if the UDP endpoint was created with auto-assign port (0)." }, Notes = "Closes the UDP endpoint. No more datagrams will be reported through the callbacks, the UDP port will be closed.",
IsOpen = { Params = "", Return = "bool", Notes = "Returns true if the UDP endpoint is listening for incoming datagrams." }, },
Send = { Params = "RawData, RemoteHost, RemotePort", Return = "bool", Notes = "Sends the specified raw data (string) to the specified remote host. The RemoteHost can be either a hostname or an IP address; if it is a hostname, the endpoint will queue a DNS lookup first, if it is an IP address, the send operation is executed immediately. Returns true if there was no immediate error, false on any failure. Note that the return value needn't represent whether the packet was actually sent, only if it was successfully queued." }, EnableBroadcasts =
{
Notes = "Some OSes need this call before they allow UDP broadcasts on an endpoint.",
},
GetPort =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the local port number of the UDP endpoint listening for incoming datagrams. Especially useful if the UDP endpoint was created with auto-assign port (0).",
},
IsOpen =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the UDP endpoint is listening for incoming datagrams.",
},
Send =
{
Params =
{
{
Name = "RawData",
Type = "string",
},
{
Name = "RemoteHost",
Type = "string",
},
{
Name = "RemotePort",
Type = "number",
},
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Sends the specified raw data (string) to the specified remote host. The RemoteHost can be either a hostname or an IP address; if it is a hostname, the endpoint will queue a DNS lookup first, if it is an IP address, the send operation is executed immediately. Returns true if there was no immediate error, false on any failure. Note that the return value needn't represent whether the packet was actually sent, only if it was successfully queued.",
},
}, },
}, -- cUDPEndpoint },
cUrlClient = cUrlClient =
{ {
Desc = Desc = [[
[[
Implements high-level asynchronous access to URLs, such as downloading webpages over HTTP(S).</p> Implements high-level asynchronous access to URLs, such as downloading webpages over HTTP(S).</p>
<p> <p>
Note that unlike other languages' URL access libraries, this class implements asynchronous requests. Note that unlike other languages' URL access libraries, this class implements asynchronous requests.
@ -391,13 +667,233 @@ g_Server = nil
POST and PUT requests), and an Options parameter specifying additional options specific to the protocol POST and PUT requests), and an Options parameter specifying additional options specific to the protocol
used. used.
]], ]],
Functions =
{
Delete =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrorMessagge",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP DELETE request. Alias for Request(\"DELETE\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Get =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP GET request. Alias for Request(\"GET\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Post =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP POST request. Alias for Request(\"POST\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Put =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a HTTP PUT request. Alias for Request(\"PUT\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
Request =
{
IsStatic = true,
Params =
{
{
Name = "Method",
Type = "string",
},
{
Name = "URL",
Type = "string",
},
{
Name = "Callbacks",
Type = "table",
},
{
Name = "Headers",
Type = "table",
IsOptional = true,
},
{
Name = "RequestBody",
Type = "string",
IsOptional = true,
},
{
Name = "Options",
Type = "table",
IsOptional = true,
},
},
Returns =
{
{
Name = "IsSuccess",
Type = "boolean",
},
{
Name = "ErrMsg",
Type = "string",
IsOptional = true,
},
},
Notes = "Starts a request with the specified Method. Returns true on succes, false and error message on immediate failure (unparsable URL etc.).",
},
},
AdditionalInfo = AdditionalInfo =
{ {
{ {
Header = "Simple Callback", Header = "Simple Callback",
Contents = Contents = [[
[[
When you don't need fine control for receiving the requests and are interested only in the result, When you don't need fine control for receiving the requests and are interested only in the result,
you can use the simple callback approach. Pass a single function as the Callback parameter, the you can use the simple callback approach. Pass a single function as the Callback parameter, the
function will get called when the response is fully processed, either with the body of the response, function will get called when the response is fully processed, either with the body of the response,
@ -418,8 +914,7 @@ cUrlClient:Get(url,
}, },
{ {
Header = "Callback Table", Header = "Callback Table",
Contents = Contents = [[
[[
To provide complete control over the request and response handling, Cuberite allows plugins to pass To provide complete control over the request and response handling, Cuberite allows plugins to pass
a table of callbacks as the Callback parameter. Then the respective functions are called for their a table of callbacks as the Callback parameter. Then the respective functions are called for their
respective events during the lifetime of the request and response. This way it is possible to respective events during the lifetime of the request and response. This way it is possible to
@ -504,8 +999,7 @@ end
}, },
{ {
Header = "Options", Header = "Options",
Contents = Contents = [[
[[
The requests support the following options, specified in the optional Options table parameter: The requests support the following options, specified in the optional Options table parameter:
<table> <table>
<tr><th>Option name</th><th>Description</th></tr> <tr><th>Option name</th><th>Description</th></tr>
@ -527,18 +1021,5 @@ end
]], ]],
}, },
}, },
},
Functions =
{
Delete = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP DELETE request. Alias for Request(\"DELETE\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Get = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP GET request. Alias for Request(\"GET\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Post = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP POST request. Alias for Request(\"POST\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Put = { Params = "URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a HTTP PUT request. Alias for Request(\"PUT\", ...). Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
Request = { Params = "Method, URL, Callbacks, [Headers], [RequestBody], [Options]", Return = "bool, [ErrMsg]", IsStatic = true, Notes = "Starts a request with the specified Method. Returns true on succes, false and error message on immediate failure (unparsable URL etc.)."},
},
}, -- cUrlClient
} }

File diff suppressed because it is too large Load Diff

View File

@ -7,24 +7,115 @@ return
]], ]],
Functions = Functions =
{ {
CanPickup = { Params = "{{cPlayer|Player}}", Return = "bool", Notes = "Returns true if the specified player can pick the arrow when it's on the ground" }, CanPickup =
GetBlockHit = { Params = "", Returns = "{{Vector3i}}", Desc = "Gets the block arrow is in" }, {
GetDamageCoeff = { Params = "", Return = "number", Notes = "Returns the damage coefficient stored within the arrow. The damage dealt by this arrow is multiplied by this coeff" }, Params =
GetPickupState = { Params = "", Return = "PickupState", Notes = "Returns the pickup state (one of the psXXX constants, above)" }, {
IsCritical = { Params = "", Return = "bool", Notes = "Returns true if the arrow should deal critical damage. Based on the bow charge when the arrow was shot." }, {
SetDamageCoeff = { Params = "number", Return = "", Notes = "Sets the damage coefficient. The damage dealt by this arrow is multiplied by this coeff" }, Name = "Player",
SetIsCritical = { Params = "bool", Return = "", Notes = "Sets the IsCritical flag on the arrow. Critical arrow deal additional damage" }, Type = "cPlayer",
SetPickupState = { Params = "PickupState", Return = "", Notes = "Sets the pickup state (one of the psXXX constants, above)" }, },
},
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the specified player can pick the arrow when it's on the ground",
},
GetBlockHit =
{
Desc = "Gets the block arrow is in",
Returns =
{
{
Type = "Vector3i",
},
},
},
GetDamageCoeff =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the damage coefficient stored within the arrow. The damage dealt by this arrow is multiplied by this coeff",
},
GetPickupState =
{
Returns =
{
{
Type = "cArrowEntity#ePickupState",
},
},
Notes = "Returns the pickup state (one of the psXXX constants, above)",
},
IsCritical =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if the arrow should deal critical damage. Based on the bow charge when the arrow was shot.",
},
SetDamageCoeff =
{
Params =
{
{
Name = "DamageCoeff",
Type = "number",
},
},
Notes = "Sets the damage coefficient. The damage dealt by this arrow is multiplied by this coeff",
},
SetIsCritical =
{
Params =
{
{
Name = "IsCritical",
Type = "boolean",
},
},
Notes = "Sets the IsCritical flag on the arrow. Critical arrow deal additional damage",
},
SetPickupState =
{
Params =
{
{
Name = "PickupState",
Type = "cArrowEntity#ePickupState",
},
},
Notes = "Sets the pickup state (one of the psXXX constants, above)",
},
}, },
Constants = Constants =
{ {
psInCreative = { Notes = "The arrow can be picked up only by players in creative gamemode" }, psInCreative =
psInSurvivalOrCreative = { Notes = "The arrow can be picked up by players in survival or creative gamemode" }, {
psNoPickup = { Notes = "The arrow cannot be picked up at all" }, Notes = "The arrow can be picked up only by players in creative gamemode",
},
psInSurvivalOrCreative =
{
Notes = "The arrow can be picked up by players in survival or creative gamemode",
},
psNoPickup =
{
Notes = "The arrow cannot be picked up at all",
},
}, },
ConstantGroups = ConstantGroups =
{ {
PickupState = ePickupState =
{ {
Include = "ps.*", Include = "ps.*",
TextBefore = [[ TextBefore = [[
@ -34,9 +125,7 @@ return
}, },
}, },
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cArrowEntity },
cExpBottleEntity = cExpBottleEntity =
{ {
Desc = [[ Desc = [[
@ -44,146 +133,325 @@ return
]], ]],
Functions = Functions =
{ {
}, },
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cExpBottleEntity },
cFireChargeEntity = cFireChargeEntity =
{ {
Desc = [[ Desc = [[
Represents a fire charge that has been shot by a Blaze or a {{cDispenserEntity|Dispenser}}. A subclass Represents a fire charge that has been shot by a Blaze or a {{cDispenserEntity|Dispenser}}. A subclass
of the {{cProjectileEntity}}. of the {{cProjectileEntity}}.
]], ]],
Functions = {}, Functions =
{
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cFireChargeEntity },
cFireworkEntity = cFireworkEntity =
{ {
Desc = [[ Desc = [[
Represents a firework rocket. Represents a firework rocket.
]], ]],
Functions = Functions =
{
GetItem =
{ {
GetItem = { Params = "", Return = "{{cItem}}", Notes = "Returns the item that has been used to create the firework rocket. The item's m_FireworkItem member contains all the firework-related data." }, Returns =
GetTicksToExplosion = { Params = "", Return = "number", Notes = "Returns the number of ticks left until the firework explodes." }, {
SetItem = { Params = "{{cItem}}", Return = "", Notes = "Sets a new item to be used for the firework." }, {
SetTicksToExplosion = { Params = "NumTicks", Return = "", Notes = "Sets the number of ticks left until the firework explodes." }, Type = "cItem",
},
},
Notes = "Returns the item that has been used to create the firework rocket. The item's m_FireworkItem member contains all the firework-related data.",
}, },
GetTicksToExplosion =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the number of ticks left until the firework explodes.",
},
SetItem =
{
Params =
{
{
Name = "FireworkItem",
Type = "cItem",
},
},
Notes = "Sets a new item to be used for the firework.",
},
SetTicksToExplosion =
{
Params =
{
{
Name = "NumTicks",
Type = "number",
},
},
Notes = "Sets the number of ticks left until the firework explodes.",
},
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cFireworkEntity },
cFloater =
{
Desc = "",
Functions = {},
Inherits = "cProjectileEntity",
}, -- cFloater
cGhastFireballEntity = cGhastFireballEntity =
{ {
Desc = "", Desc = "",
Functions = {}, Functions =
{
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cGhastFireballEntity },
cProjectileEntity = cProjectileEntity =
{ {
Desc = "Base class for all projectiles, such as arrows and fireballs.", Desc = "Base class for all projectiles, such as arrows and fireballs.",
Functions = Functions =
{ {
GetCreator = { Params = "", Return = "{{cEntity}} descendant", Notes = "Returns the entity who created this projectile. May return nil." }, GetCreator =
GetCreatorName = { Params = "", Return = "string", Notes = "Returns the name of the player that created the projectile. Will be empty for non-player creators" }, {
GetCreatorUniqueID = { Params = "", Return = "number", Notes = "Returns the unique ID of the entity who created this projectile, or {{cEntity#NO_ID|cEntity.NO_ID}} if the projectile wasn't created by an entity." }, Returns =
GetMCAClassName = { Params = "", Return = "string", Notes = "Returns the string that identifies the projectile type (class name) in MCA files" }, {
GetProjectileKind = { Params = "", Return = "ProjectileKind", Notes = "Returns the kind of this projectile (pkXXX constant)" }, {
IsInGround = { Params = "", Return = "bool", Notes = "Returns true if this projectile has hit the ground." }, Type = "cEntity",
},
},
Notes = "Returns the entity who created this projectile. May return nil.",
},
GetCreatorName =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the name of the player that created the projectile. Will be empty for non-player creators",
},
GetCreatorUniqueID =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the unique ID of the entity who created this projectile, or {{cEntity#INVALID_ID|cEntity.INVALID_ID}} if the projectile wasn't created by an entity.",
},
GetMCAClassName =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the string that identifies the projectile type (class name) in MCA files",
},
GetProjectileKind =
{
Returns =
{
{
Type = "cProjectileEntity#eKind",
},
},
Notes = "Returns the kind of this projectile (pkXXX constant)",
},
IsInGround =
{
Returns =
{
{
Type = "boolean",
},
},
Notes = "Returns true if this projectile has hit the ground.",
},
}, },
Constants = Constants =
{ {
pkArrow = { Notes = "The projectile is an {{cArrowEntity|arrow}}" }, pkArrow =
pkEgg = { Notes = "The projectile is a {{cThrownEggEntity|thrown egg}}" }, {
pkEnderPearl = { Notes = "The projectile is a {{cThrownEnderPearlEntity|thrown enderpearl}}" }, Notes = "The projectile is an {{cArrowEntity|arrow}}",
pkExpBottle = { Notes = "The projectile is a {{cExpBottleEntity|thrown exp bottle}}" }, },
pkFireCharge = { Notes = "The projectile is a {{cFireChargeEntity|fire charge}}" }, pkEgg =
pkFirework = { Notes = "The projectile is a (flying) {{cFireworkEntity|firework}}" }, {
pkFishingFloat = { Notes = "The projectile is a {{cFloater|fishing float}}" }, Notes = "The projectile is a {{cThrownEggEntity|thrown egg}}",
pkGhastFireball = { Notes = "The projectile is a {{cGhastFireballEntity|ghast fireball}}" }, },
pkSnowball = { Notes = "The projectile is a {{cThrownSnowballEntity|thrown snowball}}" }, pkEnderPearl =
pkSplashPotion = { Notes = "The projectile is a {{cSplashPotionEntity|thrown splash potion}}" }, {
pkWitherSkull = { Notes = "The projectile is a {{cWitherSkullEntity|wither skull}}" }, Notes = "The projectile is a {{cThrownEnderPearlEntity|thrown enderpearl}}",
},
pkExpBottle =
{
Notes = "The projectile is a {{cExpBottleEntity|thrown exp bottle}}",
},
pkFireCharge =
{
Notes = "The projectile is a {{cFireChargeEntity|fire charge}}",
},
pkFirework =
{
Notes = "The projectile is a (flying) {{cFireworkEntity|firework}}",
},
pkFishingFloat =
{
Notes = "The projectile is a {{cFloater|fishing float}}",
},
pkGhastFireball =
{
Notes = "The projectile is a {{cGhastFireballEntity|ghast fireball}}",
},
pkSnowball =
{
Notes = "The projectile is a {{cThrownSnowballEntity|thrown snowball}}",
},
pkSplashPotion =
{
Notes = "The projectile is a {{cSplashPotionEntity|thrown splash potion}}",
},
pkWitherSkull =
{
Notes = "The projectile is a {{cWitherSkullEntity|wither skull}}",
},
}, },
ConstantGroups = ConstantGroups =
{ {
ProjectileKind = eKind =
{ {
Include = "pk.*", Include = "pk.*",
TextBefore = "The following constants are used to distinguish between the different projectile kinds:", TextBefore = "The following constants are used to distinguish between the different projectile kinds:",
}, },
}, },
Inherits = "cEntity", Inherits = "cEntity",
}, -- cProjectileEntity },
cSplashPotionEntity = cSplashPotionEntity =
{ {
Desc = [[ Desc = [[
Represents a thrown splash potion. Represents a thrown splash potion.
]], ]],
Functions = Functions =
{
GetEntityEffect =
{ {
GetEntityEffect = { Params = "", Return = "{{cEntityEffect}}", Notes = "Returns the entity effect in this potion" }, Returns =
GetEntityEffectType = { Params = "", Return = "{{cEntityEffect|Entity effect type}}", Notes = "Returns the effect type of this potion" }, {
GetPotionColor = { Params = "", Return = "number", Notes = "Returns the color index of the particles emitted by this potion" }, {
GetItem = { Params = "", Return = "{{cItem}}", Notes = "Gets the potion item that was thrown." }, Type = "cEntityEffect",
SetEntityEffect = { Params = "{{cEntityEffect}}", Return = "", Notes = "Sets the entity effect for this potion" }, },
SetEntityEffectType = { Params = "{{cEntityEffect|Entity effect type}}", Return = "", Notes = "Sets the effect type of this potion" }, },
SetPotionColor = { Params = "number", Return = "", Notes = "Sets the color index of the particles for this potion" }, Notes = "Returns the entity effect in this potion",
}, },
GetEntityEffectType =
{
Returns =
{
{
Type = "cEntityEffect",
},
},
Notes = "Returns the effect type of this potion",
},
GetItem =
{
Returns =
{
{
Type = "cItem",
},
},
Notes = "Gets the potion item that was thrown.",
},
GetPotionColor =
{
Returns =
{
{
Type = "number",
},
},
Notes = "Returns the color index of the particles emitted by this potion",
},
SetEntityEffect =
{
Params =
{
{
Name = "EntityEffect",
Type = "cEntityEffect",
},
},
Notes = "Sets the entity effect for this potion",
},
SetEntityEffectType =
{
Params =
{
{
Name = "EntityEffectType",
Type = "cEntityEffect#eType",
},
},
Notes = "Sets the effect type of this potion",
},
SetPotionColor =
{
Params =
{
{
Name = "PotionColor",
Type = "number",
},
},
Notes = "Sets the color index of the particles for this potion",
},
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cSplashPotionEntity },
cThrownEggEntity = cThrownEggEntity =
{ {
Desc = [[ Desc = [[
Represents a thrown egg. Represents a thrown egg.
]], ]],
Functions = {}, Functions =
{
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cThrownEggEntity },
cThrownEnderPearlEntity = cThrownEnderPearlEntity =
{ {
Desc = "Represents a thrown ender pearl.", Desc = "Represents a thrown ender pearl.",
Functions = {}, Functions =
{
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cThrownEnderPearlEntity },
cThrownSnowballEntity = cThrownSnowballEntity =
{ {
Desc = "Represents a thrown snowball.", Desc = "Represents a thrown snowball.",
Functions = {}, Functions =
{
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cThrownSnowballEntity },
cWitherSkullEntity = cWitherSkullEntity =
{ {
Desc = "Represents a wither skull being shot.", Desc = "Represents a wither skull being shot.",
Functions = {}, Functions =
{
},
Inherits = "cProjectileEntity", Inherits = "cProjectileEntity",
}, -- cWitherSkullEntity },
} }

View File

@ -5,31 +5,165 @@ return
Desc = "", Desc = "",
Functions = Functions =
{ {
AddWebTab = { Params = "Title, UrlPath, HandlerFn", Return = "", IsStatic = true, Notes = "Adds a new web tab to webadmin. The tab uses \"Title\" as its display string and is identified in the URL using the UrlPath (https://server.domain.com/webadmin/{PluginName}/{UrlPath}). The HandlerFn is the callback function that is called when the admin accesses the page, it has the following signature:<br/><pre class=\"prettyprint lang-lua\">function ({{a_Request|HTTPRequest}}, a_UrlPath)<br/> return Content, ContentType<br/>end</pre> URLPath must not contain a '/', the recommendation is to use only 7-bit-clean ASCII character set." }, AddWebTab =
GetAllWebTabs = { Params = "", Return = "array-table", IsStatic = true, Notes = "Returns an array-table with each item describing a web tab, for all web tabs registered in the WebAdmin, for all plugins. The returned table has the following format:<br/><pre class=\"prettyprint lang-lua\">{<br/> {<br/> PluginName = \"Plugin's API name\",<br/> UrlPath = \"UrlPath given to AddWebTab\",<br/> Title = \"Title given to AddWebTab\",<br/> },<br/> ...<br/>}"}, {
GetBaseURL = { Params = "URL", Return = "string", IsStatic = true, Notes = "Returns the string that is the path of the base webadmin (\"../../../webadmin\") relative to the given URL." }, IsStatic = true,
GetContentTypeFromFileExt = { Params = "FileExt", Return = "string", IsStatic = true, Notes = "Returns the content-type that should be used for files with the specified extension (without the dot), such as \"text/plain\" for the \"txt\" extension. If the extension is not known, returns an empty string." }, Params =
GetHTMLEscapedString = { Params = "string", Return = "string", IsStatic = true, Notes = "Gets the HTML-escaped representation of a requested string. This is useful for user input and game data that is not guaranteed to be escaped already." }, {
GetPage = { Params = "{{Request|HTTPRequest}}", Return = "table", IsStatic = true, Notes = "Returns the (inner HTML) page contents for the specified request. Calls the appropriate WebTab handler registered via AddWebTab() and returns the information from that plugin wrapped in a table with the following structure:<br/><pre class=\"prettyprint lang-lua\">{<br/> Content = \"\", -- Content returned by the plugin<br/> ContentType = \"\", -- Content type returned by the plugin, or \"text/html\" if none returned<br/> UrlPath = \"\", -- UrlPath decoded from the request<br/> TabTitle = \"\", -- Title of the tab that handled the request, as given to AddWebTab()<br/> PluginName = \"\", -- API name of the plugin that handled the request<br/> PluginFolder = \"\", -- Folder name (= display name) of the plugin that handled the request<br/>}</pre>This function is mainly used in the webadmin template file." }, {
GetPorts = { Params = "", Return = "string", Notes = "Returns a comma-separated list of ports on which the webadmin is configured to listen. Note that this list does include ports that may currently be unavailable (another server was already listening on them prior to launching Cuberite)." }, Name = "Title",
GetURLEncodedString = { Params = "string", Return = "string", IsStatic = true, Notes = "Returns the string given to it escaped by URL encoding, which makes the string suitable for transmission in an URL. Invalid characters are turned into \"%xy\" values." }, Type = "string",
Reload = { Params = "", Return = "", Notes = "Reloads the webadmin's config - the allowed logins, the template script and the login page. Note that reloading will not change the \"enabled\" state of the server, and it will not update listening ports. Existing WebTabs will be kept registered even after the reload." }, },
{
Name = "UrlPath",
Type = "string",
},
{
Name = "HandlerFn",
Type = "function",
},
},
Notes = "Adds a new web tab to webadmin. The tab uses \"Title\" as its display string and is identified in the URL using the UrlPath (https://server.domain.com/webadmin/{PluginName}/{UrlPath}). The HandlerFn is the callback function that is called when the admin accesses the page, it has the following signature:<br/><pre class=\"prettyprint lang-lua\">function ({{a_Request|HTTPRequest}}, a_UrlPath)<br/> return Content, ContentType<br/>end</pre> URLPath must not contain a '/', the recommendation is to use only 7-bit-clean ASCII character set.",
},
GetAllWebTabs =
{
IsStatic = true,
Returns =
{
{
Type = "table",
},
},
Notes = "Returns an array-table with each item describing a web tab, for all web tabs registered in the WebAdmin, for all plugins. The returned table has the following format:<br/><pre class=\"prettyprint lang-lua\">{<br/> {<br/> PluginName = \"Plugin's API name\",<br/> UrlPath = \"UrlPath given to AddWebTab\",<br/> Title = \"Title given to AddWebTab\",<br/> },<br/> ...<br/>}",
},
GetBaseURL =
{
IsStatic = true,
Params =
{
{
Name = "URL",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the string that is the path of the base webadmin (\"../../../webadmin\") relative to the given URL.",
},
GetContentTypeFromFileExt =
{
IsStatic = true,
Params =
{
{
Name = "FileExt",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the content-type that should be used for files with the specified extension (without the dot), such as \"text/plain\" for the \"txt\" extension. If the extension is not known, returns an empty string.",
},
GetHTMLEscapedString =
{
IsStatic = true,
Params =
{
{
Name = "Input",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Gets the HTML-escaped representation of a requested string. This is useful for user input and game data that is not guaranteed to be escaped already.",
},
GetPage =
{
IsStatic = true,
Params =
{
{
Name = "HTTPRequest",
Type = "Request",
},
},
Returns =
{
{
Type = "table",
},
},
Notes = "Returns the (inner HTML) page contents for the specified request. Calls the appropriate WebTab handler registered via AddWebTab() and returns the information from that plugin wrapped in a table with the following structure:<br/><pre class=\"prettyprint lang-lua\">{<br/> Content = \"\", -- Content returned by the plugin<br/> ContentType = \"\", -- Content type returned by the plugin, or \"text/html\" if none returned<br/> UrlPath = \"\", -- UrlPath decoded from the request<br/> TabTitle = \"\", -- Title of the tab that handled the request, as given to AddWebTab()<br/> PluginName = \"\", -- API name of the plugin that handled the request<br/> PluginFolder = \"\", -- Folder name (= display name) of the plugin that handled the request<br/>}</pre>This function is mainly used in the webadmin template file.",
},
GetPorts =
{
Returns =
{
{
Type = "string",
},
},
Notes = "Returns a comma-separated list of ports on which the webadmin is configured to listen. Note that this list does include ports that may currently be unavailable (another server was already listening on them prior to launching Cuberite).",
},
GetURLEncodedString =
{
IsStatic = true,
Params =
{
{
Name = "Input",
Type = "string",
},
},
Returns =
{
{
Type = "string",
},
},
Notes = "Returns the string given to it escaped by URL encoding, which makes the string suitable for transmission in an URL. Invalid characters are turned into \"%xy\" values.",
},
Reload =
{
Notes = "Reloads the webadmin's config - the allowed logins, the template script and the login page. Note that reloading will not change the \"enabled\" state of the server, and it will not update listening ports. Existing WebTabs will be kept registered even after the reload.",
},
}, },
}, -- cWebAdmin },
HTTPFormData = HTTPFormData =
{ {
Desc = "This class stores data for one form element for a {{HTTPRequest|HTTP request}}.", Desc = "This class stores data for one form element for a {{HTTPRequest|HTTP request}}.",
Variables = Variables =
{ {
Name = { Type = "string", Notes = "Name of the form element" }, Name =
Type = { Type = "string", Notes = "Type of the data (usually empty)" }, {
Value = { Type = "string", Notes = "Value of the form element. Contains the raw data as sent by the browser." }, Type = "string",
Notes = "Name of the form element",
},
Type =
{
Type = "string",
Notes = "Type of the data (usually empty)",
},
Value =
{
Type = "string",
Notes = "Value of the form element. Contains the raw data as sent by the browser.",
},
}, },
}, -- HTTPFormData },
HTTPRequest = HTTPRequest =
{ {
Desc = [[ Desc = [[
@ -39,32 +173,55 @@ return
]], ]],
Constants = Constants =
{ {
FormData = { Notes = "Array-table of {{HTTPFormData}}, contains the values of individual form elements submitted by the client" }, Params =
Params = { Notes = "Map-table of parameters given to the request in the URL (?param=value); if a form uses GET method, this is the same as FormData. For each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value." }, {
PostParams = { Notes = "Map-table of data posted through a FORM - either a GET or POST method. Logically the same as FormData, but in a map-table format (for each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value)." }, Notes = "Map-table of parameters given to the request in the URL (?param=value); if a form uses GET method, this is the same as FormData. For each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value.",
},
FormData =
{
Notes = "Array-table of {{HTTPFormData}}, contains the values of individual form elements submitted by the client",
},
PostParams =
{
Notes = "Map-table of data posted through a FORM - either a GET or POST method. Logically the same as FormData, but in a map-table format (for each parameter given as \"param=value\", there is an entry in the table with \"param\" as its key and \"value\" as its value).",
},
}, },
Variables = Variables =
{ {
Method = { Type = "string", Notes = "The HTTP method used to make the request. Usually GET or POST." }, Method =
Path = { Type = "string", Notes = "The Path part of the URL (excluding the parameters)" }, {
URL = { Type = "string", Notes = "The entire URL used for the request." }, Type = "string",
Username = { Type = "string", Notes = "Name of the logged-in user." }, Notes = "The HTTP method used to make the request. Usually GET or POST.",
},
Path =
{
Type = "string",
Notes = "The Path part of the URL (excluding the parameters)",
},
URL =
{
Type = "string",
Notes = "The entire URL used for the request.",
},
Username =
{
Type = "string",
Notes = "Name of the logged-in user.",
},
}, },
}, -- HTTPRequest },
HTTPTemplateRequest = HTTPTemplateRequest =
{ {
Desc = [[This class is used only in the WebAdmin template script as the parameter to the function that provides the template. Desc = [[
This class is used only in the WebAdmin template script as the parameter to the function that provides the template.
]], ]],
Variables = Variables =
{ {
Request = { Type = "HTTPRequest", Notes = "The request for which the template is being built." }, Request =
{
Type = "HTTPRequest",
Notes = "The request for which the template is being built.",
},
}, },
}, -- HTTPTemplateRequest },
} }

View File

@ -36,6 +36,16 @@ local function LoadAPIFiles(a_Folder, a_DstTable)
break break
end end
for k, cls in pairs(Tables) do for k, cls in pairs(Tables) do
if (a_DstTable[k]) then
-- The class is documented in two files, warn and store into a file (so that CIs can mark build as failure):
LOGWARNING(string.format(
"APIDump warning: class %s is documented at two places, the documentation in file %s will overwrite the previously loaded one!",
k, FileName
))
local f = io.open("DuplicateDocs.txt", "a")
f:write(k, "\t", FileName)
f:close()
end
a_DstTable[k] = cls; a_DstTable[k] = cls;
end end
end -- if (TablesFn) end -- if (TablesFn)
@ -511,8 +521,8 @@ local function ReadDescriptions(a_API, a_Desc)
local DoxyFunctions = {}; -- This will contain all the API functions together with their documentation local DoxyFunctions = {}; -- This will contain all the API functions together with their documentation
local function AddFunction(a_Name, a_Params, a_Return, a_IsStatic, a_Notes) local function AddFunction(a_Name, a_Params, a_Returns, a_IsStatic, a_Notes)
table.insert(DoxyFunctions, {Name = a_Name, Params = a_Params, Return = a_Return, IsStatic = a_IsStatic, Notes = a_Notes}); table.insert(DoxyFunctions, {Name = a_Name, Params = a_Params, Returns = a_Returns, IsStatic = a_IsStatic, Notes = a_Notes});
end end
if (APIDesc.Functions ~= nil) then if (APIDesc.Functions ~= nil) then
@ -530,11 +540,11 @@ local function ReadDescriptions(a_API, a_Desc)
-- Description is available -- Description is available
if (FnDesc[1] == nil) then if (FnDesc[1] == nil) then
-- Single function definition -- Single function definition
AddFunction(func.Name, FnDesc.Params, FnDesc.Return, FnDesc.IsStatic, FnDesc.Notes); AddFunction(func.Name, FnDesc.Params, FnDesc.Returns, FnDesc.IsStatic, FnDesc.Notes);
else else
-- Multiple function overloads -- Multiple function overloads
for _, desc in ipairs(FnDesc) do for _, desc in ipairs(FnDesc) do
AddFunction(func.Name, desc.Params, desc.Return, desc.IsStatic, desc.Notes); AddFunction(func.Name, desc.Params, desc.Returns, desc.IsStatic, desc.Notes);
end -- for k, desc - FnDesc[] end -- for k, desc - FnDesc[]
end end
FnDesc.IsExported = true; FnDesc.IsExported = true;
@ -773,16 +783,21 @@ local function LinkifyType(a_Type, a_API)
return "<a href=\"" .. a_Type .. ".html\">" .. a_Type .. "</a>" return "<a href=\"" .. a_Type .. ".html\">" .. a_Type .. "</a>"
end end
-- If the type has a colon, it's a child enum of a class: -- If the type has a hash sign, it's a child enum of a class:
local idxColon = a_Type:find(":") local idxColon = a_Type:find("#")
if (idxColon) then if (idxColon) then
local classType = a_Type:sub(1, idxColon - 1) local classType = a_Type:sub(1, idxColon - 1)
if (a_API[classType]) then if (a_API[classType]) then
local enumType = a_Type:sub(idxColon + 2) local enumType = a_Type:sub(idxColon + 1)
return "<a href=\"" .. classType .. ".html#" .. enumType .. "\">" .. a_Type .. "</a>" return "<a href=\"" .. classType .. ".html#" .. enumType .. "\">" .. enumType .. "</a>"
end end
end end
-- If the type is a ConstantGroup within the Globals, it's a global enum:
if ((a_API.Globals.ConstantGroups or {})[a_Type]) then
return "<a href=\"Globals.html#" .. a_Type .. "\">" .. a_Type .. "</a>"
end
-- Unknown or built-in type, output just text: -- Unknown or built-in type, output just text:
return a_Type return a_Type
end end
@ -869,7 +884,7 @@ local function WriteHtmlClass(a_ClassAPI, a_ClassMenu, a_API)
-- Add the anchor names as a title -- Add the anchor names as a title
cf:write("<tr><td id=\"", func.Name, "_", TableOverloadedFunctions[func.Name], "\" title=\"", func.Name, "_", TableOverloadedFunctions[func.Name], "\">", func.Name, "</td>\n"); cf:write("<tr><td id=\"", func.Name, "_", TableOverloadedFunctions[func.Name], "\" title=\"", func.Name, "_", TableOverloadedFunctions[func.Name], "\">", func.Name, "</td>\n");
cf:write("<td>", CreateFunctionParamsDescription(func.Params or {}, a_InheritedName or a_ClassAPI.Name, a_API), "</td>\n"); cf:write("<td>", CreateFunctionParamsDescription(func.Params or {}, a_InheritedName or a_ClassAPI.Name, a_API), "</td>\n");
cf:write("<td>", CreateFunctionParamsDescription(func.Return or {}, a_InheritedName or a_ClassAPI.Name, a_API), "</td>\n"); cf:write("<td>", CreateFunctionParamsDescription(func.Returns or {}, a_InheritedName or a_ClassAPI.Name, a_API), "</td>\n");
cf:write("<td>", StaticClause .. LinkifyString(func.Notes or "<i>(undocumented)</i>", (a_InheritedName or a_ClassAPI.Name)), "</td></tr>\n"); cf:write("<td>", StaticClause .. LinkifyString(func.Notes or "<i>(undocumented)</i>", (a_InheritedName or a_ClassAPI.Name)), "</td></tr>\n");
end end
cf:write("</table>\n"); cf:write("</table>\n");
@ -1531,6 +1546,7 @@ local function WriteZBSMethods(f, a_Methods)
f:write("\t\t\t[\"", func.Name, "\"] =\n") f:write("\t\t\t[\"", func.Name, "\"] =\n")
f:write("\t\t\t{\n") f:write("\t\t\t{\n")
f:write("\t\t\t\ttype = \"method\",\n") f:write("\t\t\t\ttype = \"method\",\n")
-- No way to indicate multiple signatures to ZBS, so don't output any params at all
if ((func.Notes ~= nil) and (func.Notes ~= "")) then if ((func.Notes ~= nil) and (func.Notes ~= "")) then
f:write("\t\t\t\tdescription = [[", CleanUpDescription(func.Notes or ""), " ]],\n") f:write("\t\t\t\tdescription = [[", CleanUpDescription(func.Notes or ""), " ]],\n")
end end
@ -1764,6 +1780,7 @@ local function PrepareApi()
-- Add Globals into the API: -- Add Globals into the API:
Globals.Name = "Globals"; Globals.Name = "Globals";
table.insert(API, Globals); table.insert(API, Globals);
API.Globals = Globals
-- Read in the descriptions: -- Read in the descriptions:
LOG("Reading descriptions..."); LOG("Reading descriptions...");

View File

@ -197,8 +197,8 @@ public:
/** Returns the enchantability of the item. When the item hasn't a enchantability, it will returns 0 */ /** Returns the enchantability of the item. When the item hasn't a enchantability, it will returns 0 */
int GetEnchantability(); // tolua_export int GetEnchantability(); // tolua_export
/** Enchants the item using the specified number of XP levels. /** Randomly enchants the item using the specified number of XP levels.
Returns true if item enchanted, false if not. */ Returns true if the item was enchanted, false if not (not enchantable / too many enchantments already). */
bool EnchantByXPLevels(int a_NumXPLevels); // tolua_export bool EnchantByXPLevels(int a_NumXPLevels); // tolua_export
// tolua_begin // tolua_begin

View File

@ -62,7 +62,7 @@ public:
virtual void HandleFalling(void) override; virtual void HandleFalling(void) override;
/** Engage pathfinder and tell it to calculate a path to a given position, and move the mobile accordingly /** Engage pathfinder and tell it to calculate a path to a given position, and move the mob accordingly
Currently, the mob will only start moving to a new position after the position it is currently going to is reached. */ Currently, the mob will only start moving to a new position after the position it is currently going to is reached. */
virtual void MoveToPosition(const Vector3d & a_Position); // tolua_export virtual void MoveToPosition(const Vector3d & a_Position); // tolua_export

View File

@ -477,7 +477,8 @@ public:
bool DigBlock (int a_X, int a_Y, int a_Z); bool DigBlock (int a_X, int a_Y, int a_Z);
virtual void SendBlockTo(int a_X, int a_Y, int a_Z, cPlayer * a_Player) override; virtual void SendBlockTo(int a_X, int a_Y, int a_Z, cPlayer * a_Player) override;
/** Set default spawn at the given coordinates. */ /** Set default spawn at the given coordinates.
Returns false if the new spawn couldn't be stored in the INI file. */
bool SetSpawn(double a_X, double a_Y, double a_Z); bool SetSpawn(double a_X, double a_Y, double a_Z);
double GetSpawnX(void) const { return m_SpawnX; } double GetSpawnX(void) const { return m_SpawnX; }