diff --git a/api/connection.rst b/api/connection.rst index 532f290..52a3a1e 100644 --- a/api/connection.rst +++ b/api/connection.rst @@ -231,9 +231,11 @@ Dispatcher Subsystem The dispatcher subsystem is designed for running external utilities or scripts in an asynchronous fashion. Any connected client can subscribe to per-connection event notifications about dispatcher processes through the events system, but only users in the *wheel* group have the authority to directly submit new jobs for the dispatcher. -.. note:: other subsystems may also use the dispatcher for long-running processes in the background, and these subsystems may allow non-wheel group users to perform these tasks as necessary. +.. note:: other subsystems may also use the dispatcher for long-running processes in the background, and these subsystems may allow non-wheel group users to perform these tasks as + necessary. Also, the events namespace does not really translate over to REST which was not designed for asyncronous events. For this reason, only Websocket examples are used in this + section. -The user needs to first subscribe to "dispatcher" event notifications: +The format of "dispatcher" event requests is as follows: +---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ | **Parameter** | **Value** | **Description** | @@ -263,7 +265,8 @@ For example, to subscribe to dispatcher events: "args" : ["dispatcher"] } -To unsubscribe from dispatcher events: +Once subscribed, the requested events will be received as they are produced. To unsubscribe from event notifications, repeat the request, using "unsubscribe" for the "name". For example, +to unsubscribe from dispatcher events: .. code-block:: json diff --git a/api/events.rst b/api/events.rst deleted file mode 100644 index 3d3c498..0000000 --- a/api/events.rst +++ /dev/null @@ -1,61 +0,0 @@ -.. _Events: - -Events -****** - -The "events" namespace can be used to setup and receive asyncronous updates about system status and other types of system notifications. - -.. _note: the events namespace does not really translate over to REST which was not designed for asyncronous events. For this reason, only Websocket examples are used in this section. - -Every events request contains the following parameters: - -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| **Parameter** | **Value** | **Description** | -| | | | -+=================================+===============+======================================================================================================================+ -| id | | any unique value for the request; examples include a hash, checksum, or uuid | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| name | | supported values are "subscribe" or unsubscribe" | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| namespace | events | | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ -| args | | values vary by type of class | -| | | | -+---------------------------------+---------------+----------------------------------------------------------------------------------------------------------------------+ - -Here is an example of subscribing to Life Preserver events: - -**Websocket Request** - -.. code-block:: json - - { - "namespace" : "events", - "name" : "subscribe", - "id" : "sampleID", - "args" : ["dispatcher", "life-preserver"] - } - -Once subscribed, events will be received as they are produced. To unsubscribe from events, repeat the request, using "unsubscribe" for the "name". - -Here is an example reply: - -**Websocket Reply** - -.. code-block:: json - - { - "namespace" : "events", - "name" : "life-preserver", - "id" : "" - "args" : { - "message" : , - "priority" : " - - ", - "class" : "[snapshot/replication]" - } - } - diff --git a/api/index.rst b/api/index.rst index c81f9ba..3f1675f 100644 --- a/api/index.rst +++ b/api/index.rst @@ -7,7 +7,6 @@ PC-BSDĀ® API Reference connection users - events classes/index Indices and tables