To create new wiki account, please join us on #znc at Libera.Chat and ask admins to create a wiki account for you. You can say thanks to spambots for this inconvenience.
Api: Difference between revisions
Start API documentation draft |
Add ENOSYS |
||
| (7 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
== Commands == | == Commands == | ||
{| | {| class="wikitable" | ||
| <code>PING</code> | | <code>PING</code> | ||
| Unconditionally returns PONG. Exists primarily for testing things, or may be used to probe for API availability without making any calls. | | Unconditionally returns PONG. Exists primarily for testing things, or may be used to probe for API availability without making any calls. | ||
| Line 14: | Line 14: | ||
| Returns a list of available QUERY scopes. See below. | | Returns a list of available QUERY scopes. See below. | ||
|- | |- | ||
| <code>QUERY</code> | | <code>QUERY <scope> <property></code> | ||
| Used to query information. See below. | | Used to query information. See below. | ||
|} | |} | ||
=== QUERY command === | === QUERY command === | ||
The <code>QUERY</code> command is organized into scopes. The scope specifies where to query for the information. Here are the available scopes: | |||
{| class="wikitable" | |||
| <code>ZNC</code> | |||
| Static, ZNC-wide readonly information about the ZNC binary. | |||
|- | |||
| <code>USER</code> | |||
| Information about the currently authenticated user. | |||
|} | |||
TODO document parameters | |||
== Types == | == Types == | ||
Scalar types are returned | Scalar types are returned preceded by the string <code>VALUE</code>, or <code>NULL</code> if the result was empty. | ||
Lists of scalar types are returned one element per IRC message, preceded by the string <code>LIST</code> and ended by the string <code>LISTEND</code>. | Lists of scalar types are returned one element per IRC message, preceded by the string <code>LIST</code> and ended by the string <code>LISTEND</code>. Queries that return lists will never return <code>NULL</code>, but they may return lists with zero elements. | ||
Lists of n-tuples are returned one tuple element per IRC message and in order, preceded by the string <code>TUPLELIST <n></code> and ended by the string <code>TUPLELISTEND</code> where <code><n></code> is the arity of the tuples in the list. | Lists of n-tuples are returned one tuple element per IRC message and in order, preceded by the string <code>TUPLELIST <n></code> and ended by the string <code>TUPLELISTEND</code> where <code><n></code> is the arity of the tuples in the list. | ||
| Line 48: | Line 60: | ||
== Errors == | == Errors == | ||
Each error consists of a general code followed by a space and a more specific, human-readable string. Here are all the general error codes you may encounter and what they mean: | |||
{| class="wikitable" | |||
| <code>EINVAL</code> | |||
| Invalid command or argument | |||
|- | |||
| <code>ENOSYS</code> | |||
| Function not implemented | |||
|- | |||
| <code>EACCES</code> | |||
| Permission denied | |||
|} | |||
Here's an example of an error returned after trying to <code>QUERY</code> a property that doesn't exist in the <code>USER</code> scope: | |||
EINVAL Unknown query in scope USER | |||
Here <code>EINVAL</code> is the general code and <code>Unknown query in scope USER</code> is the human-readable-string. Both elements of these errors will be kept stable over time. | |||
These general error codes may be used in existing APIs in the future: | |||
{| class="wikitable" | |||
| <code>EIDRM</code> | |||
| This functionality was previously available, but has been removed | |||
|- | |||
| <code>ENOTSUP</code> | |||
| The operation is not supported, perhaps because of missing libraries | |||
|} | |||
Latest revision as of 07:34, 6 August 2021
Commands
PING
|
Unconditionally returns PONG. Exists primarily for testing things, or may be used to probe for API availability without making any calls. |
HELP
|
Returns informational text about the API's self-documentation. |
COMMANDS
|
Returns a list of available commands. |
QUERYSCOPES
|
Returns a list of available QUERY scopes. See below. |
QUERY <scope> <property>
|
Used to query information. See below. |
QUERY command
The QUERY command is organized into scopes. The scope specifies where to query for the information. Here are the available scopes:
ZNC
|
Static, ZNC-wide readonly information about the ZNC binary. |
USER
|
Information about the currently authenticated user. |
TODO document parameters
Types
Scalar types are returned preceded by the string VALUE, or NULL if the result was empty.
Lists of scalar types are returned one element per IRC message, preceded by the string LIST and ended by the string LISTEND. Queries that return lists will never return NULL, but they may return lists with zero elements.
Lists of n-tuples are returned one tuple element per IRC message and in order, preceded by the string TUPLELIST <n> and ended by the string TUPLELISTEND where <n> is the arity of the tuples in the list.
For example, here is a list of the numbers 1, 2, and 3:
LIST 1 2 3 LISTEND
And here is a list of the 2-tuples (A, 1), (B, 2), and (C, 3):
TUPLELIST 2 A 1 B 2 C 3 TUPLELISTEND
Errors
Each error consists of a general code followed by a space and a more specific, human-readable string. Here are all the general error codes you may encounter and what they mean:
EINVAL
|
Invalid command or argument |
ENOSYS
|
Function not implemented |
EACCES
|
Permission denied |
Here's an example of an error returned after trying to QUERY a property that doesn't exist in the USER scope:
EINVAL Unknown query in scope USER
Here EINVAL is the general code and Unknown query in scope USER is the human-readable-string. Both elements of these errors will be kept stable over time.
These general error codes may be used in existing APIs in the future:
EIDRM
|
This functionality was previously available, but has been removed |
ENOTSUP
|
The operation is not supported, perhaps because of missing libraries |