docs/buxton-protocol.7

   1 '\" t
   2 .TH "BUXTON\-PROTOCOL" "7" "" "buxton 1" "buxton\-protocol"
   3 .\" -----------------------------------------------------------------
   4 .\" * Define some portability stuff
   5 .\" -----------------------------------------------------------------
   6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   7 .\" http://bugs.debian.org/507673
   8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
   9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10 .ie \n(.g .ds Aq \(aq
  11 .el       .ds Aq '
  12 .\" -----------------------------------------------------------------
  13 .\" * set default formatting
  14 .\" -----------------------------------------------------------------
  15 .\" disable hyphenation
  16 .nh
  17 .\" disable justification (adjust text to left margin only)
  18 .ad l
  19 .\" -----------------------------------------------------------------
  20 .\" * MAIN CONTENT STARTS HERE *
  21 .\" -----------------------------------------------------------------
  22 .SH "NAME"
  23 buxton\-protocol \- The wire protocol for buxton
  24
  25 .SH "DESCRIPTION"
  26 .PP
  27 A buxton client communicates with the buxton daemon
  28 (\fBbuxtond\fR(8)) through a Unix Domain Socket by sending
  29 messages over this socket that adhere to a specific format\&.  Also,
  30 \fBbuxtond\fR(8) may send a response back to the client in a same
  31 format\&. The required rules, formats, and values permitted in this
  32 two-way communication channel is hereafter called the "wire
  33 protocol"\&.
  34
  35 .SH "PROTOCOL SPECIFICATION"
  36 .PP
  37 The following sections detail the specifics of the wire protocol\&.
  38
  39 .SH "MESSAGE FORMAT"
  40 .PP
  41 The messages sent to \fBbuxtond\fR(8) from a client, or vice
  42 versa, adhere to the following format:
  43
  44 .SS "Header"
  45 .PP
  46 Magic (2 bytes)
  47 .RS 4
  48 The magic byte string has hex value 0x672\&.
  49 .RE
  50 .PP
  51 Control code (2 bytes)
  52 .RS 4
  53 All control codes belong to an enum with 13 elements\&. Each code is
  54 cast to a uint16_t value when serialized\&.
  55
  56 For client messages, the accepted control codes are:
  57 BUXTON_CONTROL_SET, BUXTON_CONTROL_SET_LABEL,
  58 BUXTON_CONTROL_CREATE_GROUP, BUXTON_CONTROL_REMOVE_GROUP,
  59 BUXTON_CONTROL_GET, BUXTON_CONTROL_UNSET, BUXTON_CONTROL_NOTIFY, and
  60 BUXTON_CONTROL_UNNOTIFY\&.
  61
  62 For daemon responses, accepted control codes are:
  63 BUXTON_CONTROL_STATUS and BUXTON_CONTROL_CHANGED\&.
  64
  65 .RE
  66 .PP
  67 Message size (4 bytes)
  68 .RS 4
  69 The size on the entire message, with type uint32_t\&.
  70 .RE
  71 .PP
  72 Message ID (8 bytes)
  73 .RS 4
  74 The unique ID for this message, with type uint32_t\&.
  75 .RE
  76 .PP
  77 Parameter count (4 bytes)
  78 .RS 4
  79 The number of parameters in the message body, with contents as
  80 described in the next section\&. This number has type uint32_t\&.
  81 .RE
  82
  83 .SS "Message body"
  84 .PP
  85 The message body contains one or more parameters, each with the
  86 following structure:
  87 .PP
  88 Data type (2 bytes)
  89 .RS 4
  90 All recognized data types belong to an enum with 8 elements\&. Each
  91 type is cast to a uint16_t value when serialized\&.
  92
  93 Accepted types include STRING, INT32, UINT32, INT64, UINT64, FLOAT,
  94 DOUBLE, and BOOLEAN\&.
  95 \&.
  96 .RE
  97 .PP
  98 Data length (4 bytes)
  99 .RS 4
 100 The length the data value, as defined in the next entry\&.
 101 .RE
 102 .PP
 103 Data value (varies depending on data type)
 104 .RS 4
 105 For data with STRING type, the value may range from 0 (zero) bytes to
 106 an arbitrary maximum, as permitted by the maximum message length and
 107 factoring in the overall payload of the message\&. For all other data
 108 types, the value size depends on the data type, with maximum size of
 109 8 bytes\&.
 110 .RE
 111
 112 .SH "NOTES"
 113 .PP
 114 The maximum message length is 32KB (32768 bytes)\&.
 115 .PP
 116 The message byte order is dependent on the endianness of the host
 117 machine\&.
 118
 119 .SH "COPYRIGHT"
 120 .PP
 121 Copyright 2014 Intel Corporation\&. License: Creative Commons
 122 Attribution\-ShareAlike 3.0 Unported\s-2\u[1]\d\s+2\&.
 123
 124 .SH "SEE ALSO"
 125 .PP
 126 \fBbuxton\fR(7),
 127 \fBbuxtonctl\fR(1),
 128 \fBbuxtond\fR(8),
 129 \fBbuxton\-api\fR(7)
 130
 131 .SH "FOOTNOTES"
 132 .IP " 1." 4
 133 Creative Commons Attribution\-ShareAlike 3.0 Unported
 134 .RS 4
 135 \%http://creativecommons.org/licenses/by-sa/3.0/
 136 .RE