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
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
|
.TH "Error handling" 3 "Sat Oct 25 2014" "Version 1.0" "BrlAPI" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Error handling \-
.PP
How to handle errors\&.
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct \fBbrlapi_error_t\fP"
.br
.in -1c
.SS "Macros"
.in +1c
.ti -1c
.RI "#define \fBBRLAPI_ERROR_SUCCESS\fP 0"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_NOMEM\fP 1"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_TTYBUSY\fP 2"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_DEVICEBUSY\fP 3"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_UNKNOWN_INSTRUCTION\fP 4"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_ILLEGAL_INSTRUCTION\fP 5"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_INVALID_PARAMETER\fP 6"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_INVALID_PACKET\fP 7"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_CONNREFUSED\fP 8"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_OPNOTSUPP\fP 9"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_GAIERR\fP 10"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_LIBCERR\fP 11"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_UNKNOWNTTY\fP 12"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_PROTOCOL_VERSION\fP 13"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_EOF\fP 14"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_EMPTYKEY\fP 15"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_DRIVERERROR\fP 16"
.br
.ti -1c
.RI "#define \fBBRLAPI_ERROR_AUTHENTICATION\fP 17"
.br
.ti -1c
.RI "#define \fBbrlapi_error\fP (*\fBbrlapi_error_location\fP())"
.br
.ti -1c
.RI "#define \fBbrlapi_errno\fP (brlapi_error\&.brlerrno)"
.br
.ti -1c
.RI "#define \fBbrlapi_libcerrno\fP (brlapi_error\&.libcerrno)"
.br
.ti -1c
.RI "#define \fBbrlapi_gaierrno\fP (brlapi_error\&.gaierrno)"
.br
.ti -1c
.RI "#define \fBbrlapi_errfun\fP (brlapi_error\&.errfun)"
.br
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef uint32_t \fBbrlapi_packetType_t\fP"
.br
.ti -1c
.RI "typedef void(\fBBRLAPI_STDCALL\fP * \fBbrlapi_exceptionHandler_t\fP )(int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
.br
.ti -1c
.RI "typedef void(\fBBRLAPI_STDCALL\fP * \fBbrlapi__exceptionHandler_t\fP )(\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
.br
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi_perror\fP (const char *s)"
.br
.ti -1c
.RI "\fBbrlapi_error_t\fP *\fBBRLAPI_STDCALL\fP \fBbrlapi_error_location\fP (void)"
.br
.ti -1c
.RI "const char *\fBBRLAPI_STDCALL\fP \fBbrlapi_strerror\fP (const \fBbrlapi_error_t\fP *error)"
.br
.ti -1c
.RI "const char *\fBBRLAPI_STDCALL\fP \fBbrlapi_getPacketTypeName\fP (\fBbrlapi_packetType_t\fP type)"
.br
.ti -1c
.RI "int \fBBRLAPI_STDCALL\fP \fBbrlapi_strexception\fP (char *buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t packetSize)"
.br
.ti -1c
.RI "int \fBBRLAPI_STDCALL\fP \fBbrlapi__strexception\fP (\fBbrlapi_handle_t\fP *handle, char *buffer, size_t bufferSize, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t packetSize)"
.br
.ti -1c
.RI "\fBbrlapi_exceptionHandler_t\fP
.br
\fBBRLAPI_STDCALL\fP \fBbrlapi_setExceptionHandler\fP (\fBbrlapi_exceptionHandler_t\fP handler)"
.br
.ti -1c
.RI "\fBbrlapi__exceptionHandler_t\fP
.br
\fBBRLAPI_STDCALL\fP \fBbrlapi__setExceptionHandler\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi__exceptionHandler_t\fP handler)"
.br
.ti -1c
.RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi_defaultExceptionHandler\fP (int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
.br
.ti -1c
.RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi__defaultExceptionHandler\fP (\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
.br
.in -1c
.SS "Variables"
.in +1c
.ti -1c
.RI "const char * \fBbrlapi_errlist\fP []"
.br
.ti -1c
.RI "const int \fBbrlapi_nerr\fP"
.br
.ti -1c
.RI "\fBbrlapi_error_t\fP \fBbrlapi_error\fP"
.br
.ti -1c
.RI "int \fBbrlapi_errno\fP"
.br
.ti -1c
.RI "int \fBbrlapi_libcerrno\fP"
.br
.ti -1c
.RI "int \fBbrlapi_gaierrno\fP"
.br
.ti -1c
.RI "const char * \fBbrlapi_errfun\fP"
.br
.in -1c
.SH "Detailed Description"
.PP
When a function fails, \fBbrlapi_errno\fP will hold an error code to explain why it failed\&. It should always be reported somehow\&.
.PP
Although most errors are reported that way, some (called exceptions) are reported asynchronously for efficiency reasons, because they always just report a programming error\&. The affected functions are: brlapi_setFocus, brlapi_write* and brlapi_sendRaw\&. When they happen, the next call to brlapi_something will close the connection and call the \fIexception\fP handler\&. If the exception handler returns, the brlapi_something function will return an end-of-file error\&.
.PP
The default exception handler (\fBbrlapi_defaultExceptionHandler()\fP) dumps the guilty packet before abort()ing\&. It can be replaced by calling \fBbrlapi_setExceptionHandler()\fP\&. For instance, the Java and Python bindings use this for raising a Java or Python exception that may be caught\&.
.SH "Macro Definition Documentation"
.PP
.SS "#define brlapi_errfun (brlapi_error\&.errfun)"
Cheat about the brlapi_errfun C token
.SS "#define brlapi_errno (brlapi_error\&.brlerrno)"
Cheat about the brlapi_errno C token
.SS "#define brlapi_error (*\fBbrlapi_error_location\fP())"
Cheat about the brlapi_error C token
.SS "#define BRLAPI_ERROR_AUTHENTICATION 17"
Authentication failed
.SS "#define BRLAPI_ERROR_CONNREFUSED 8"
Connection refused
.SS "#define BRLAPI_ERROR_DEVICEBUSY 3"
A connection is already using RAW or suspend mode
.SS "#define BRLAPI_ERROR_DRIVERERROR 16"
Packet returned by driver too large
.SS "#define BRLAPI_ERROR_EMPTYKEY 15"
Key file empty
.SS "#define BRLAPI_ERROR_EOF 14"
Unexpected end of file
.SS "#define BRLAPI_ERROR_GAIERR 10"
Getaddrinfo error
.SS "#define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5"
Forbiden in current mode
.SS "#define BRLAPI_ERROR_INVALID_PACKET 7"
Invalid size
.SS "#define BRLAPI_ERROR_INVALID_PARAMETER 6"
Out of range or have no sense
.SS "#define BRLAPI_ERROR_LIBCERR 11"
Libc error
.SS "#define BRLAPI_ERROR_NOMEM 1"
Not enough memory
.SS "#define BRLAPI_ERROR_OPNOTSUPP 9"
Operation not supported
.SS "#define BRLAPI_ERROR_PROTOCOL_VERSION 13"
Bad protocol version
.SS "#define BRLAPI_ERROR_SUCCESS 0"
Success
.SS "#define BRLAPI_ERROR_TTYBUSY 2"
A connection is already running in this tty
.SS "#define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4"
Not implemented in protocol
.SS "#define BRLAPI_ERROR_UNKNOWNTTY 12"
Couldn't find out the tty number
.SS "#define brlapi_gaierrno (brlapi_error\&.gaierrno)"
Cheat about the brlapi_gaierrno C token
.SS "#define brlapi_libcerrno (brlapi_error\&.libcerrno)"
Cheat about the brlapi_libcerrno C token
.SH "Typedef Documentation"
.PP
.SS "typedef void(\fBBRLAPI_STDCALL\fP * brlapi__exceptionHandler_t)(\fBbrlapi_handle_t\fP *handle, int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
.SS "typedef void(\fBBRLAPI_STDCALL\fP * brlapi_exceptionHandler_t)(int error, \fBbrlapi_packetType_t\fP type, const void *packet, size_t size)"
Types for exception handlers
.PP
Types of exception handlers which are to be given to \fBbrlapi_setExceptionHandler()\fP and \fBbrlapi__setExceptionHandler()\fP\&.
.PP
\fBParameters:\fP
.RS 4
\fIhandle\fP is the handle corresponding to the guilty connection;
.br
\fIerror\fP is a BRLAPI_ERROR_ error code;
.br
\fItype\fP is the type of the guilty packet;
.br
\fIpacket\fP points to the content of the guilty packet (might be a little bit truncated);
.br
\fIsize\fP gives the guilty packet's size\&.
.RE
.PP
.SS "typedef uint32_t \fBbrlapi_packetType_t\fP"
Type for packet type\&. Only unsigned can cross networks, 32bits
.SH "Function Documentation"
.PP
.SS "void \fBBRLAPI_STDCALL\fP brlapi__defaultExceptionHandler (\fBbrlapi_handle_t\fP *handle, interror, \fBbrlapi_packetType_t\fPtype, const void *packet, size_tsize)"
.SS "\fBbrlapi__exceptionHandler_t\fP \fBBRLAPI_STDCALL\fP brlapi__setExceptionHandler (\fBbrlapi_handle_t\fP *handle, \fBbrlapi__exceptionHandler_t\fPhandler)"
.SS "int \fBBRLAPI_STDCALL\fP brlapi__strexception (\fBbrlapi_handle_t\fP *handle, char *buffer, size_tbufferSize, interror, \fBbrlapi_packetType_t\fPtype, const void *packet, size_tpacketSize)"
.SS "void \fBBRLAPI_STDCALL\fP brlapi_defaultExceptionHandler (interror, \fBbrlapi_packetType_t\fPtype, const void *packet, size_tsize)"
.SS "\fBbrlapi_error_t\fP* \fBBRLAPI_STDCALL\fP brlapi_error_location (void)"
Get per-thread error location
.PP
In multithreaded software, \fBbrlapi_error\fP is thread-specific, so api\&.h cheats about the brlapi_error token and actually calls \fBbrlapi_error_location()\fP\&.
.PP
This gets the thread specific location of global variable \fBbrlapi_error\fP
.SS "const char* \fBBRLAPI_STDCALL\fP brlapi_getPacketTypeName (\fBbrlapi_packetType_t\fPtype)"
Get plain packet type
.PP
\fBbrlapi_getPacketTypeName()\fP returns the plain packet type name corresponding to its argument\&.
.SS "void \fBBRLAPI_STDCALL\fP brlapi_perror (const char *s)"
Print a BrlAPI error message
.PP
\fBbrlapi_perror()\fP reads \fBbrlapi_error\fP, and acts just like perror()\&.
.SS "\fBbrlapi_exceptionHandler_t\fP \fBBRLAPI_STDCALL\fP brlapi_setExceptionHandler (\fBbrlapi_exceptionHandler_t\fPhandler)"
Set a new exception handler
.PP
\fBbrlapi_setExceptionHandler()\fP replaces the previous exception handler with the handler parameter\&. The previous exception handler is returned to make chaining error handlers possible\&.
.PP
The default handler just prints the exception and abort()s\&.
.SS "const char* \fBBRLAPI_STDCALL\fP brlapi_strerror (const \fBbrlapi_error_t\fP *error)"
Get plain error message
.PP
\fBbrlapi_strerror()\fP returns the plain error message corresponding to its argument\&.
.SS "int \fBBRLAPI_STDCALL\fP brlapi_strexception (char *buffer, size_tbufferSize, interror, \fBbrlapi_packetType_t\fPtype, const void *packet, size_tpacketSize)"
Describes an exception
.PP
\fBbrlapi_strexception()\fP puts a text describing the given exception in buffer\&.
.PP
The beginning of the guilty packet is dumped as a sequence of hex bytes\&.
.PP
\fBReturns:\fP
.RS 4
the size of the text describing the exception, following snprintf()'s semantics\&.
.RE
.PP
.SH "Variable Documentation"
.PP
.SS "const char* brlapi_errfun"
Shorthand for brlapi_error\&.errfun
.SS "const char* brlapi_errlist[]"
Error message list
.PP
These are the string constants used by \fBbrlapi_perror()\fP\&.
.SS "int brlapi_errno"
Shorthand for brlapi_error\&.errno
.SS "\fBbrlapi_error_t\fP brlapi_error"
Global variable brlapi_error
.PP
\fBbrlapi_error\fP is a global left-value containing the last error information\&. Its errno field is not reset to BRLAPI_ERROR_SUCCESS on success\&.
.PP
This information may be copied in \fBbrlapi_error_t\fP variables for later use with the brlapi_strerror function\&.
.SS "int brlapi_gaierrno"
Shorthand for brlapi_error\&.gaierrno
.SS "int brlapi_libcerrno"
Shorthand for brlapi_error\&.libcerrno
.SS "const int brlapi_nerr"
Number of error messages
.SH "Author"
.PP
Generated automatically by Doxygen for BrlAPI from the source code\&.
|
