Repository navigation
Expand file tree
/
Copy pathipp-usb-api.7
More file actions
247 lines (244 loc) · 5.81 KB
/
Copy pathipp-usb-api.7
File metadata and controls
247 lines (244 loc) · 5.81 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
.\" Generated by scdoc 1.11.3
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "ipp-usb-api" "7" "2026-10-31" "Control API for ipp-usb"
.PP
.SH NAME
.PP
ipp-usb-api - Control API for \fBipp-usb\fR daemon
.PP
.SH DESCRIPTION
.PP
The \fBipp-usb\fR control API provides a way for local client
applications to communicate with the running \fBipp-usb\fR daemon.\&
.PP
The API uses a UNIX domain socket.\&
.PP
.SH PROTOCOL
.PP
.SS Overview
.PP
The control API uses HTTP over a UNIX domain socket.\& Requests are
sent using the HTTP GET and POST methods.\&
.PP
The protocol is versioned independently of the \fBipp-usb\fR software
release.\& The protocol version identifies the \fBipp-usb\fR release in
which the latest protocol changes were introduced.\& It remains
unchanged across software releases that do not change the protocol.\&
.PP
The protocol is backward compatible.\& New endpoints and request
parameters may be introduced in later protocol versions without
breaking existing clients.\&
.PP
The protocol version in which each endpoint and each request or
response field was introduced is documented below.\&
.PP
.SS Authentication
.PP
Information requests are available to everyone.\& Administrative
requests require authentication.\&
.PP
Since all communication takes place over an \fB\fRAF_UNIX\fB\fR socket,
the server uses the \fB\fRSO_PEERCRED\fB\fR socket option to obtain the
UID of the calling user.\&
.PP
To authorize administrative requests, the calling user must be
granted \fB\fRadmin\fB\fR permission in the \fB\fRipp-usb.\&conf\fB\fR file.\&
.PP
See the \fB\fRAuthentication\fB\fR section in \fBipp-usb(8)\fR for details
on configuring authentication.\&
.PP
.SH REQUESTS
.PP
.SS GET /status (since 0.9.22)
.PP
\fBAuthentication required\fR: none
.br
\fBResponse Content-Type:\fR text/plain
.PP
This is a legacy request.\& It returns a formatted status page
containing the same information as the output of the ipp-usb status
command.\&
.PP
.SS GET /version (since 0.9.35)
.PP
\fBAuthentication required\fR: none
.br
\fBResponse Content-Type:\fR text/plain
.PP
Returns the protocol version as a plain-text string.\&
.PP
The version identifies the \fBipp-usb\fR release in which the latest
protocol changes were introduced.\& For example:
.PP
.nf
.RS 4
0\&.9\&.35
.fi
.RE
.PP
The returned version does not necessarily match the version of the
running ipp-usb daemon.\&
.PP
Assume version \fB0.\&9.\&22\fR if \fB404 Not found\fR error is returned.\&
.PP
.SS POST /get/conf (since 0.9.35)
.PP
\fBAuthentication required\fR: none
.br
\fBRequest Content-Type:\fR application/json
.br
\fBResponse Content-Type:\fR application/json
.PP
\fBRequest data:\fR
.nf
.RS 4
{
// Device identification; all fields are optional
"usb_MFG" : "Xerox",
"usb_MDL" : "B235 MFP",
"usb_SN" : "34004H030206H",
"usb_HWID" : "0924&9d3b",
"usb_URI" : "usb://Xerox/B235%20MFP?serial=34004H030206H",
}
.fi
.RE
.PP
\fBError response:\fR
.nf
.RS 4
{
"err": "error message"
}
.fi
.RE
.PP
\fBData response:\fR
.nf
.RS 4
{
// Array of devices, matching the search criteria
"data": [
{
// Device identification
"usb_MFG" : "Xerox",
"usb_MDL" : "B235 MFP",
"usb_SN" : "34004H030206H",
"usb_HWID" : "0924&9d3b",
"usb_URI" : "usb://Xerox/B235%20MFP?serial=34004H030206H",
// Settings
"disabled" : true | false,
},
]
}
.fi
.RE
.PP
This request returns array of per-device configuration records.\&
Parameters of request specify search criteria.\& If no matching
devices were found, empty array is returned.\&
.PP
.SS POST /set/conf (since 0.9.35)
.PP
\fBAuthentication required\fR: admin
.br
\fBRequest Content-Type:\fR application/json
.br
\fBResponse Content-Type:\fR application/json
.PP
\fBRequest data:\fR
.nf
.RS 4
{
// Device identification; all fields are optional
"usb_MFG" : "Xerox",
"usb_MDL" : "B235 MFP",
"usb_SN" : "34004H030206H",
"usb_HWID" : "0924&9d3b",
"usb_URI" : "usb://Xerox/B235%20MFP?serial=34004H030206H",
// Settings -- supply only parameters that
// should be changed\&.
"disabled" : true | false,
}
.fi
.RE
.PP
\fBError response:\fR
.nf
.RS 4
{
"err": "error message"
}
.fi
.RE
.PP
\fBData response:\fR
.nf
.RS 4
{
// Empty
"data": {
// Device identification
"usb_MFG" : "Xerox",
"usb_MDL" : "B235 MFP",
"usb_SN" : "34004H030206H",
"usb_HWID" : "0924&9d3b",
"usb_URI" : "usb://Xerox/B235%20MFP?serial=34004H030206H",
// Settings
"disabled" : true | false,
},
}
.fi
.RE
.PP
Device identification in the request should be unambigous,
which means that at least any combibation of the identification
parameters is provided:
.PP
.PD 0
.IP \(bu 4
usb_MFG + usb_MDL + usb_SN
.IP \(bu 4
usb_HWID + usb_SN
.IP \(bu 4
usb_URI
.PD
.PP
Note, this definition of unambigous identification doesn'\&t
depend on amount of known devices and only depend on
request parameters.\&
.PP
Only those setting parameters that intendent to be changed
should be provided in the request.\& Multiple parameters
can be changed by a single request.\&
.PP
Upon succesful completion, settings are persisted on disk
and the state of already connected devices are updated
appropriately.\&
.PP
This request returns an updated device configuration record.\&
.PP
.SH FILES
.PP
\fB/var/ipp-usb/ctrl\fR
.RS 4
\fBipp-usb\fR control socket
.PP
.RE
.SH COPYRIGHT
.PP
Copyright (c) by Alexander Pevzner (pzz@apevzner.\&com, pzz@pzz.\&msk.\&ru)
.br
All rights reserved.\&
.PP
This program is licensed under 2-Clause BSD license.\&
.br
See LICENSE file for details.\&
.PP
.SS SEE ALSO
.PP
\fBipp-usb(8)\fR