Working on section 3 of PC-BSD API 1.0 documentation.

Added subsections to section 3: dispatcher, life preserver, and system state. Added examples of dispatcher messaging to parts of section 4: Classes. Added further examples of messaging to section 3 in the subsections.
2026-01-27 10:20:26 +00:00 · 2016-03-29 16:17:26 -04:00
parent 842a594ce3
commit 9a371de28d
4 changed files with 494 additions and 12 deletions
--- a/api/classes/iohyve.rst
+++ b/api/classes/iohyve.rst
@@ -148,7 +148,30 @@ The "fetchiso" action is used to retrieve the installation ISO. It is used with
  "name": "response",
  "namespace": "sysadm"
 }
- 
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"iohyve",
+    "state" : "running" OR "finished",
+    "filename",
+    "percent_done",
+    "download_rate",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+   }
+ }
+
 .. index:: listisos, iohyve

 .. _List ISOs:
--- a/api/classes/pkg.rst
+++ b/api/classes/pkg.rst
@@ -225,7 +225,29 @@ The "pkg_info" action reads the pkg database directly and returns any relevant i
  "name": "response",
  "namespace": "sysadm"
 }
- 
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_info",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ } 
+
 .. index:: pkg_search, pkg

 .. _Search Packages:
@@ -404,6 +426,28 @@ The "pkg_search" action searches the package database for pkgs which match the g
  "namespace": "sysadm"
 }

+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_search",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ }  
+
 .. index:: list_categories, pkg

 .. _List Categories:
@@ -502,6 +546,29 @@ The "list_categories" action lists all the known, non-empty categories within th
  "name": "response",
  "namespace": "sysadm"
 }
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "list_categories",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ }  
+ 
 .. index:: list_repos, pkg

 .. _List Repositories:
@@ -549,7 +616,29 @@ action are valid as the optional "repo" argument for the other pkg API actions.
  "name": "response",
  "namespace": "sysadm"
 }
- 
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "list_repos",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ }  
+
 .. index:: pkg_audit, pkg

 .. _Audit Packages:
@@ -600,7 +689,31 @@ The "pkg_audit" action performs an audit of all installed packages and reports a
  "name": "response",
  "namespace": "sysadm"
 }
- 
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_audit",
+    "vulnerable_pkgs" : ["pkg 1"], ["pkg 2"],
+    "impacts_pkgs" : ["pkg 1", "pkg 2"],
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ } 
+
 .. index:: pkg_upgrade, pkg

 .. _Upgrade Packages:
@@ -649,7 +762,29 @@ instructions on how to subscribe to and query dispatcher events.
  "name": "response",
  "namespace": "sysadm"
 }
- 
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_upgrade",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ }  
+
 .. index:: pkg_check_upgrade, pkg

 .. _Check Packages:
@@ -699,6 +834,29 @@ instructions on how to subscribe to and query dispatcher events.
  "namespace": "sysadm"
 }
 
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_check_upgrade"
+    "updates_available" : "true" OR "false",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ }
+
 .. index:: pkg_update, pkg

 .. _Update Package Database:
@@ -752,6 +910,28 @@ If you include "force" = "true", it forces :command:`pkg` to completely resync a
  "namespace": "sysadm"
 }
 
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_update",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ }  
+
 .. index:: pkg_lock, pkg_unlock, pkg

 .. _Lock/Unlock Packages:
@@ -811,6 +991,28 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di
  "namespace": "sysadm"
 }

+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_lock",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ } 
+ 
 **REST Request**

 .. code-block:: json
@@ -852,6 +1054,28 @@ Both actions return any information as a dispatcher event. Refer to the :ref:`Di
  "namespace": "sysadm"
 }
 
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_unlock",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ } 
+ 
 .. index:: pkg_install, pkg

 .. _Install Packages:
@@ -905,6 +1129,28 @@ Unless the "repo" is specified, :command:`pkg` will automatically determine the
  "name": "response",
  "namespace": "sysadm"
 }
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_install",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ } 
 
 .. index:: pkg_remove, pkg

@@ -961,4 +1207,26 @@ The uninstall messages will be returned as a dispatcher event. Refer to the :ref
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
- }
+ }
+ 
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"pkg",
+    "state" : "running" OR "finished",
+    "pkg_log",
+    "action" : "pkg_remove",
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
+ } 
--- a/api/classes/updates.rst
+++ b/api/classes/updates.rst
@@ -217,4 +217,25 @@ The "startupdate" action starts the specified update. You must specify a "target
  "id": "fooid",
  "name": "response",
  "namespace": "sysadm"
+ }
+
+**Dispatcher Events System Reply**
+
+.. code-block:: json
+
+ {
+  "namespace" : "events",
+  "name" : "dispatcher",
+  "id" : "none",
+  "args" : {
+    "event_system" : "sysadm"/"update",
+    "state" : "running" OR "finished",
+    "update_log"
+    "process_details" : {
+      "time_started" : <ISO 8601 time date string>,
+      "cmd_list" : [ "<command 1>", "<command 2>"],
+      "process_id" : "<some id string>",
+      "state" : "running"
+      }
+    }
 }