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
Document errors |
Add ENOSYS |
||
(4 intermediate revisions by the same user not shown) | |||
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. | ||
|} | |} | ||
Line 34: | Line 34: | ||
== 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 61: | Line 61: | ||
== Errors == | == Errors == | ||
Each error consists of a general code followed by a space and a more specific, human-readable string. Here are all the error codes you may encounter: | 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: | ||
Line 67: | Line 67: | ||
| <code>EINVAL</code> | | <code>EINVAL</code> | ||
| Invalid command or argument | | Invalid command or argument | ||
|- | |||
| <code>ENOSYS</code> | |||
| Function not implemented | |||
|- | |- | ||
| <code>EACCES</code> | | <code>EACCES</code> | ||
Line 77: | Line 80: | ||
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. | 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 |