doc/COMMANDS.in

   1 The server uses a protocol provided by libassuan to communicate with the
   2 client. An OK response is returned when a command succeeds or ERR along with
   3 an error code and description, if not. When a command requests data for
   4 retrieval (e.g., GET) the output is prefixed with D then a single SPACE then
   5 the actual data followed by a response. Read the libassuan docs for more info
   6 about the protocol.
   7
   8
   9 PROTOCOL COMMANDS
  10 -----------------
  11 !INSERT-HELP-TEXT!
  12
  13
  14 STATUS MESSAGES
  15 ---------------
  16 Some commands send a status message to the client when successful or as a
  17 progress indicator. Status messages begin with a KEYWORD followed by the
  18 status description. What messages are sent, when, and how often, depend on
  19 configuration settings:
  20
  21     COMMAND      | KEYWORD
  22     -------------|-------------
  23     <ALL>         LOCKED
  24
  25     OPEN          DECRYPT
  26                   DECOMPRESS
  27                   CACHE
  28
  29     SAVE          COMPRESS
  30                   ENCRYPT
  31                   CACHE
  32
  33     GET           XFER
  34
  35     LIST          XFER
  36
  37     DUMP          XFER
  38
  39     XPATH         XFER
  40
  41     CLEARCACHE    CACHE
  42
  43     CACHETIMEOUT  CACHE
  44
  45
  46     KEYWORD    |OUTPUT FORMAT
  47     -----------|--------------------
  48     CACHE       <slots used>
  49                 Sent to each client after the file cache changes.
  50
  51     ENCRYPT     <iterations so far> <total iterations>
  52
  53     DECRYPT     <iterations so far> <total iterations>
  54
  55     COMPRESS    <bytes so far> <total bytes>
  56
  57     DECOMPRESS  <bytes so far> <total bytes>
  58
  59     XFER        <bytes so far> <total bytes>
  60
  61     LOCKED      When another thread owns a mutex lock that the current thread
  62                 needs, this is status message is sent and the thread will
  63                 block until the lock can be obtained.
  64
  65     KEEPALIVE   Sent to each client after every configured amount of
  66                 seconds. It is important that this status message be sent to
  67                 test for client connectivity.
  68
  69     CONFIG      Sent to each client after the configuration file has
  70                 been reloaded or has had a value changed that may affect other
  71                 connected clients.
  72
  73     CLIENTS     <count>
  74                 Sent to each client after a client connects or disconnects.
  75
  76
  77 THE TARGET ATTRIBUTE
  78 --------------------
  79 There is a special attribute "target" (case sensitive) that can be set with
  80 ATTR SET. The value of this attribute is an element path that is located
  81 somewhere else in the XML document and are alot like how XPath treats
  82 entities, but is needed do to how pwmd commands are implemented. The syntax
  83 is as follows:
  84
  85 ATTR SET target [!]element[<TAB>[!]element[..]] [!]element[<TAB>[!]element[..]]
  86                 arg1^^^^^^^^^^^^^^^^^^^^^^^^^^^ arg2^^^^^^^^^^^^^^^^^^^^^^^^^^^
  87
  88 If the element path of where the "target" attribute (arg1) is to be stored
  89 doesn't exist then it will be created. This is the only time the ATTR command
  90 will create elements.
  91
  92 When a protocol command requests <arg1> as the element path then the path will
  93 be modified to use <arg2>. This is useful if you need elements to share the
  94 same data. If the target is modified, the other elements "pointing" to the
  95 target will have the same content. To get the real or literal element and
  96 ignore any "target" attributes, prefix the element with a '!' character.
  97 Another way to think of this attribute is that it's like a symbolic link in a
  98 filesystem. Here's an example XML document:
  99
 100     <pwmd>
 101         <element _name="a">
 102             <element _name="child">value a</element>
 103         </element>
 104         <element _name="b" target="a">
 105             <element _name="element_b">value b</element>
 106         </element>
 107         <element _name="c" target="b"/>
 108         <element name="d" target="!b"/>
 109     </pwmd>
 110
 111 Example:
 112     C> LIST b
 113     S> b
 114     S> b !child
 115
 116 Notice that there is not an <element_b> listed. This is because of the
 117 "target" attribute. The target attribute is recursive too, meaning that it can
 118 point to other elements with a "target" attibute:
 119
 120     C> LIST c
 121     S> c
 122     S> c !child
 123
 124 To get the value of an element with a "target" attribute without resolving the
 125 target, prefix the element with the literal element character '!':
 126
 127     C> LIST !b
 128     S> !b
 129     S> !b !element_b
 130
 131 A "target" attribute value may also contain the literal element character:
 132
 133     C> LIST d
 134     S> d
 135     S> d !element_b
 136
 137 The value of the "target" attribute isn't limited to only one element. It can
 138 be a full element path with literal element characters placed where needed.
 139 Use the REALPATH command to resolve all "target" attributes.
 140
 141 The "target" attribute is considered for all commands that support an element
 142 path. If the target element has been renamed or deleted afterwards, the
 143 command will fail.
 144
 145 Clients should be careful of creating target loops or targets which resolve to
 146 themselves. See the "recursion_depth" configuration parameter for details.
 147
 148
 149 XML DOCUMENT STRUCTURE
 150 ----------------------
 151 When importing an XML data file with the -I command line option, the document
 152 should have the following DTD:
 153
 154     <?xml version="1.0"?>
 155     <!DOCTYPE pwmd [
 156     <!ELEMENT pwmd (element*)>
 157     <!ATTLIST element _name CDATA #REQUIRED>
 158     ]>
 159
 160 The "pwmd" element is the document root node while all other elements of the
 161 document have the name "element" with an attribute "_name" which is used as
 162 the reference to the current "element". It's done this way so commonly used
 163 characters that would normally cause the XML parser to throw an error while
 164 parsing an XML element won't because the element name is stored as an XML
 165 attribute which has more loose restrictions in their values. See THE TARGET
 166 ATTRIBUTE for an example document.
 167
 168
 169 Ben Kibbey <bjk@luxsci.net>
 170 http://bjk.sourceforge.net/pwmd/