brlapi.h 63 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647
  1. /* Programs/brlapi.h. Generated from brlapi.h.in by configure. */
  2. /*
  3. * libbrlapi - A library providing access to braille terminals for applications.
  4. *
  5. * Copyright (C) 2002-2020 by
  6. * Samuel Thibault <Samuel.Thibault@ens-lyon.org>
  7. * Sébastien Hinderer <Sebastien.Hinderer@ens-lyon.org>
  8. *
  9. * libbrlapi comes with ABSOLUTELY NO WARRANTY.
  10. *
  11. * This is free software, placed under the terms of the
  12. * GNU Lesser General Public License, as published by the Free Software
  13. * Foundation; either version 2.1 of the License, or (at your option) any
  14. * later version. Please see the file LICENSE-LGPL for details.
  15. *
  16. * Web Page: http://brltty.app/
  17. *
  18. * This software is maintained by Dave Mielke <dave@mielke.cc>.
  19. */
  20. /** \file
  21. * \brief Types, defines and functions prototypes for \e BrlAPI's library
  22. */
  23. #ifndef BRLAPI_INCLUDED
  24. #define BRLAPI_INCLUDED
  25. #ifdef __cplusplus
  26. extern "C" {
  27. #endif /* __cplusplus */
  28. /* #undef BRLAPI_WIN32 */
  29. /** \defgroup brlapi_version Version of the BrlAPI library
  30. * @{ */
  31. /** Library version. */
  32. #define BRLAPI_RELEASE "0.8.0"
  33. /** Library major version. */
  34. #define BRLAPI_MAJOR 0
  35. /** Library minor version. */
  36. #define BRLAPI_MINOR 8
  37. /** Library revision. */
  38. #define BRLAPI_REVISION 0
  39. /** Returns the version of the library */
  40. void brlapi_getLibraryVersion(int* major, int* minor, int* revision);
  41. /** @} */
  42. /* Types are defined there */
  43. #include <sys/types.h>
  44. #ifdef BRLAPI_WIN32
  45. #include <windows.h>
  46. #define BRLAPI_STDCALL __stdcall
  47. #else /* BRLAPI_WIN32 */
  48. #define BRLAPI_STDCALL
  49. #endif /* BRLAPI_WIN32 */
  50. #ifdef _MSC_VER
  51. typedef __int64 uint64_t;
  52. typedef __int32 uint32_t;
  53. #define UINT64_C(x) (x##Ui64)
  54. #define PRIx64 "I64x"
  55. typedef signed int ssize_t;
  56. #else /* _MSC_VER */
  57. /* this is for uint*_t */
  58. #include <stdint.h>
  59. /* NULL is defined there */
  60. #include <unistd.h>
  61. #include <inttypes.h> /* For PRIx64 */
  62. #endif /* _MSC_VER */
  63. #include <wchar.h>
  64. /** \defgroup brlapi_handles BrlAPI handles
  65. *
  66. * Each function provided by BrlAPI comes in two versions.
  67. *
  68. * 1. A version whose name is prefixed by brlapi_ for clients opening only
  69. * one simultaneous connection with BrlAPI (most frequen case)
  70. *
  71. * 2. A version whose name is prefixed by brlapi__ for use by clients
  72. * wishing to open more than one connection to BrlAPI.
  73. *
  74. * A function called brlapi__foo is used in exactly the same way as its
  75. * brlapi_foo counterpart, except that it takes an additional argument
  76. * (the first one), which is a handle letting the client refer to a given
  77. * connection in a similar manner to what file descriptors do.
  78. *
  79. * In case you want to check that your code is not erroneously using brlapi_foo
  80. * functions, define BRLAPI_NO_SINGLE_SESSION before including <brlapi.h>: that
  81. * will disable the declaration of all single session functions.
  82. *
  83. * @{ */
  84. /** Type for BrlAPI hanles */
  85. typedef struct brlapi_handle_t brlapi_handle_t;
  86. /** Returns the size of an object of type brlapi_handle_t in bytes */
  87. size_t BRLAPI_STDCALL brlapi_getHandleSize(void);
  88. /** @} */
  89. /** \defgroup brlapi_connection Connecting to BrlAPI
  90. *
  91. * Before calling any other function of the library, calling
  92. * brlapi_openConnection() is needed to establish a connection to
  93. * \e BrlAPI 's server.
  94. * When the connection is not needed any more, brlapi_closeConnection() must be
  95. * called to close the connection.
  96. *
  97. * @{ */
  98. /** Default port number on which connections to \e BrlAPI can be established */
  99. #define BRLAPI_SOCKETPORTNUM 4101
  100. #define BRLAPI_SOCKETPORT "4101"
  101. /** Default unix path on which connections to \e BrlAPI can be established */
  102. #define BRLAPI_SOCKETPATH "/run/brltty/BrlAPI"
  103. /** \e brltty 's settings directory
  104. *
  105. * This is where authorization key and driver-dependent key names are found
  106. * for instance. */
  107. #define BRLAPI_ETCDIR "/etc"
  108. /** Default name of the file containing \e BrlAPI 's authorization key
  109. *
  110. * This name is relative to BRLAPI_ETCDIR */
  111. #define BRLAPI_AUTHKEYFILE "brlapi.key"
  112. /** Default authorization setting */
  113. #ifdef BRLAPI_WIN32
  114. /* No authentication by default on Windows */
  115. #define BRLAPI_DEFAUTH "none"
  116. #else /* BRLAPI_WIN32 */
  117. #define BRLAPI_DEFAUTH_KEYFILE "keyfile:" BRLAPI_ETCDIR "/" BRLAPI_AUTHKEYFILE
  118. #ifdef USE_POLKIT
  119. #define BRLAPI_DEFAUTH_POLKIT "+polkit"
  120. #else /* USE_POLKIT */
  121. #define BRLAPI_DEFAUTH_POLKIT ""
  122. #endif /* USE_POLKIT */
  123. #define BRLAPI_DEFAUTH BRLAPI_DEFAUTH_KEYFILE BRLAPI_DEFAUTH_POLKIT
  124. #endif /* BRLAPI_WIN32 */
  125. #ifdef __MINGW32__
  126. typedef HANDLE brlapi_fileDescriptor;
  127. #else /* __MINGW32__ */
  128. typedef int brlapi_fileDescriptor;
  129. #endif /* __MINGW32__ */
  130. /** \brief Settings structure for \e BrlAPI connection
  131. *
  132. * This structure holds every parameter needed to connect to \e BrlAPI: which
  133. * file the authorization key can be found in and which computer to connect to.
  134. *
  135. * \par Examples:
  136. * \code
  137. * brlapi_connectionSettings_t settings;
  138. *
  139. * settings.auth="/etc/brlapi.key";
  140. * settings.host="foo";
  141. * \endcode
  142. *
  143. * \e libbrlapi will read authorization key from file \p /etc/brlapi.key
  144. * and connect to the machine called "foo", on the default TCP port.
  145. *
  146. * \code
  147. * settings.host="10.1.0.2";
  148. * \endcode
  149. *
  150. * lets directly enter an IP address instead of a machine name.
  151. *
  152. * \code
  153. * settings.host=":1";
  154. * \endcode
  155. *
  156. * lets \e libbrlapi connect to the local computer, on port
  157. * BRLAPI_SOCKETPORTNUM+1
  158. *
  159. * \sa brlapi_openConnection()
  160. */
  161. typedef struct {
  162. /** For security reasons, \e libbrlapi has to get authorized to connect to the
  163. * \e BrlAPI server. This can be done via a secret key, for instance. This is
  164. * the path to the file which holds it; it will hence have to be readable by
  165. * the application.
  166. *
  167. * Setting \c NULL defaults it to local installation setup or to the content
  168. * of the BRLAPI_AUTH environment variable, if it exists. */
  169. const char* auth;
  170. /** This tells where the \e BrlAPI server resides: it might be listening on
  171. * another computer, on any TCP port. It should look like "foo:1", which
  172. * means TCP port number BRLAPI_SOCKETPORTNUM+1 on computer called "foo".
  173. * \note Please check that resolving this name works before complaining
  174. *
  175. * Settings \c NULL defaults it to localhost, using the local installation's
  176. * default TCP port, or to the content of the BRLAPI_HOST environment
  177. * variable, if it exists. */
  178. const char* host;
  179. } brlapi_connectionSettings_t;
  180. /* BRLAPI_SETTINGS_INITIALIZER */
  181. /** Allows to initialize a structure of type \e brlapi_connectionSettings_t *
  182. * with default values. */
  183. #define BRLAPI_SETTINGS_INITIALIZER \
  184. { NULL, NULL }
  185. /* brlapi_openConnection */
  186. /** Open a socket and connect it to \e BrlAPI 's server
  187. *
  188. * This function first loads an authorization key as specified in settings.
  189. * It then creates a TCP socket and connects it to the specified machine, on
  190. * the specified port. It writes the authorization key on the socket and
  191. * waits for acknowledgement.
  192. *
  193. * \return the file descriptor, or -1 on error
  194. *
  195. * \note The file descriptor is returned in case the client wants to
  196. * communicate with the server without using \e libbrlapi functions. If it uses
  197. * them however, it won't have to pass the file descriptor later, since the
  198. * library keeps a copy of it. But that also means that
  199. * brlapi_openConnection() may be called several times, but \e libbrlapi
  200. * functions will always work with the last call's descriptor
  201. *
  202. * \par Example:
  203. * \code
  204. * if (brlapi_openConnection(&settings,&settings)<0) {
  205. * fprintf(stderr,"couldn't connect to BrlAPI at %s: %s\n",
  206. * settings.host, brlapi_strerror(&brlapi_error));
  207. * exit(1);
  208. * }
  209. * \endcode
  210. *
  211. * \par Errors:
  212. * \e BrlAPI might not be on this TCP port, the host name might not be
  213. * resolvable, the authorization may fail,...
  214. *
  215. * \param desiredSettings this gives the desired connection parameters, as
  216. * described in brlapi_connectionSettings_t. If \c NULL, defaults values are
  217. * used, so that it is generally a good idea to give \c NULL as default, and
  218. * only fill a brlapi_connectionSettings_t structure when the user gave
  219. * parameters to the program for instance; \param actualSettings if not \c NULL,
  220. * parameters which were actually used are stored here, if the application ever
  221. * needs them.
  222. *
  223. * \sa
  224. * brlapi_connectionSettings_t
  225. * brlapi_writePacket()
  226. * brlapi_readPacketHeader()
  227. * brlapi_readPacketContent()
  228. * brlapi_readPacket()
  229. */
  230. #ifndef BRLAPI_NO_SINGLE_SESSION
  231. brlapi_fileDescriptor BRLAPI_STDCALL
  232. brlapi_openConnection(const brlapi_connectionSettings_t* desiredSettings,
  233. brlapi_connectionSettings_t* actualSettings);
  234. #endif /* BRLAPI_NO_SINGLE_SESSION */
  235. brlapi_fileDescriptor BRLAPI_STDCALL
  236. brlapi__openConnection(brlapi_handle_t* handle,
  237. const brlapi_connectionSettings_t* desiredSettings,
  238. brlapi_connectionSettings_t* actualSettings);
  239. /* brlapi_closeConnection */
  240. /** Cleanly close the socket
  241. *
  242. * This function locks until a closing acknowledgement is received from the
  243. * server. The socket is then freed, so the file descriptor
  244. * brlapi_openConnection() gave has no meaning any more
  245. */
  246. #ifndef BRLAPI_NO_SINGLE_SESSION
  247. void BRLAPI_STDCALL brlapi_closeConnection(void);
  248. #endif /* BRLAPI_NO_SINGLE_SESSION */
  249. void BRLAPI_STDCALL brlapi__closeConnection(brlapi_handle_t* handle);
  250. /** @} */
  251. /** \defgroup brlapi_clientData Setting and getting client data
  252. *
  253. * Clients can register a pointer to data that can then be used
  254. * e.g. in exception handlers.
  255. * @{ */
  256. /* brlapi__setClientData */
  257. /** Register a pointer to client data
  258. *
  259. * \param data The pointer to the private client data
  260. */
  261. #ifndef BRLAPI_NO_SINGLE_SESSION
  262. void BRLAPI_STDCALL brlapi_setClientData(void* data);
  263. #endif /* BRLAPI_NO_SINGLE_SESSION */
  264. void BRLAPI_STDCALL brlapi__setClientData(brlapi_handle_t* handle, void* data);
  265. /* brlapi__getClientData */
  266. /** Retrieves the pointer to the private client data
  267. *
  268. * \return the pointer to the private client data
  269. */
  270. #ifndef BRLAPI_NO_SINGLE_SESSION
  271. void* BRLAPI_STDCALL brlapi_getClientData(void);
  272. #endif /* BRLAPI_NO_SINGLE_SESSION */
  273. void* BRLAPI_STDCALL brlapi__getClientData(brlapi_handle_t* handle);
  274. /** @} */
  275. /** \defgroup brlapi_info Getting Terminal information
  276. * \brief How to get information about the connected Terminal
  277. *
  278. * Before using Raw mode or key codes, the application should always check the
  279. * type of the connected terminal, to be sure it is really the one it expects.
  280. *
  281. * One should also check for display size, so as to adjust further displaying
  282. * on it.
  283. * @{
  284. */
  285. /** Maximum name length for names embeded in BrlAPI packets, not counting any
  286. * termination \\0 character */
  287. #define BRLAPI_MAXNAMELENGTH 31
  288. /* brlapi_getDriverName */
  289. /** Return the complete name of the driver used by \e brltty
  290. *
  291. * This function fills its argument with the whole name of the braille
  292. * driver if available, terminated with a '\\0'.
  293. *
  294. * \param buffer is the buffer provided by the application;
  295. * \param size is the maximum size for the name buffer.
  296. *
  297. * \return -1 on error, otherwise a positive value giving the size of the needed
  298. * buffer (including '\\0'). If that value is bigger than \p size, the value was
  299. * truncated and the caller should retry with a bigger buffer accordingly.
  300. */
  301. #ifndef BRLAPI_NO_SINGLE_SESSION
  302. int BRLAPI_STDCALL brlapi_getDriverName(char* buffer, size_t size);
  303. #endif /* BRLAPI_NO_SINGLE_SESSION */
  304. int BRLAPI_STDCALL brlapi__getDriverName(brlapi_handle_t* handle,
  305. char* buffer,
  306. size_t size);
  307. /* brlapi_getModelIdentifier */
  308. /** Return an identifier for the device model used by \e brltty
  309. *
  310. * This function fills its argument with the whole identifier of the braille
  311. * device model if available, terminated with a '\\0'.
  312. *
  313. * \param buffer is the buffer given by the application;
  314. * \param size is the maximum size for the identifier buffer.
  315. *
  316. * \return -1 on error, otherwise a positive value giving the size of the needed
  317. * buffer (including '\\0'). If that value is bigger than \p size, the value was
  318. * truncated and the caller should retry with a bigger buffer accordingly.
  319. */
  320. #ifndef BRLAPI_NO_SINGLE_SESSION
  321. int BRLAPI_STDCALL brlapi_getModelIdentifier(char* buffer, size_t size);
  322. #endif /* BRLAPI_NO_SINGLE_SESSION */
  323. int BRLAPI_STDCALL brlapi__getModelIdentifier(brlapi_handle_t* handle,
  324. char* buffer,
  325. size_t size);
  326. /* brlapi_getDisplaySize */
  327. /** Return the size of the braille display */
  328. #ifndef BRLAPI_NO_SINGLE_SESSION
  329. int BRLAPI_STDCALL brlapi_getDisplaySize(unsigned int* x, unsigned int* y);
  330. #endif /* BRLAPI_NO_SINGLE_SESSION */
  331. int BRLAPI_STDCALL brlapi__getDisplaySize(brlapi_handle_t* handle,
  332. unsigned int* x,
  333. unsigned int* y);
  334. /** @} */
  335. /** \defgroup brlapi_tty Entering & leaving tty mode
  336. * \brief How to take control of ttys for direct braille display / read
  337. *
  338. * Before being able to write on the braille display, the application must tell
  339. * the server which tty it will handle.
  340. *
  341. * The application must also specify how braille keys will be delivered to it.
  342. * Two ways are possible: key codes and commands:
  343. *
  344. * - key codes are specific to each braille driver, since the raw key code, as
  345. * defined in the driver will be given for each key press.
  346. * Using them leads to building highly driver-dependent applications, which
  347. * can yet sometimes be useful to mimic existing proprietary applications
  348. * for instance.
  349. * - commands means that applications will get exactly the same values as
  350. * \e brltty. This allows driver-independent clients, which will hopefully
  351. * be nice to use with a lot of different terminals.
  352. * \sa brlapi_readKey()
  353. * @{
  354. */
  355. /* brlapi_enterTtyMode */
  356. /** Ask for some tty, with some key mechanism
  357. *
  358. * \param tty
  359. * - If tty>=0 then take control of the specified tty.
  360. * - If tty==::BRLAPI_TTY_DEFAULT then take control of the default tty.
  361. *
  362. * \param driver tells how the application wants brlapi_readKey() to return
  363. * key presses. NULL or "" means BRLTTY commands are required,
  364. * whereas a driver name means that raw key codes returned by this
  365. * driver are expected.
  366. *
  367. * WINDOWPATH and WINDOWID should be propagated when running remote applications
  368. * via ssh, for instance, along with BRLAPI_HOST and the authorization key (see
  369. * SendEnv in ssh_config(5) and AcceptEnv in sshd_config(5))
  370. *
  371. * \return the used tty number on success, -1 on error
  372. *
  373. * \sa brlapi_leaveTtyMode() brlapi_readKey()
  374. */
  375. #ifndef BRLAPI_NO_SINGLE_SESSION
  376. int BRLAPI_STDCALL brlapi_enterTtyMode(int tty, const char* driver);
  377. #endif /* BRLAPI_NO_SINGLE_SESSION */
  378. int BRLAPI_STDCALL brlapi__enterTtyMode(brlapi_handle_t* handle,
  379. int tty,
  380. const char* driver);
  381. /** Select the default tty.
  382. *
  383. * The library takes the following steps:
  384. * -# Try to get the tty number from the \c WINDOWID environment variable (for
  385. * the \c xterm case).
  386. * -# Try to get the tty number from the \c CONTROLVT environment variable.
  387. * -# Read \c /proc/self/stat (on \c Linux).
  388. *
  389. * \sa brlapi_enterTtyMode()
  390. */
  391. #define BRLAPI_TTY_DEFAULT -1
  392. /* brlapi_enterTtyModeWithPath */
  393. /** Ask for some tty specified by its path in the tty tree, with some key
  394. * mechanism
  395. *
  396. * \param ttys points on the array of ttys representing the tty path to be got.
  397. * Can be NULL if nttys is 0.
  398. * \param count gives the number of elements in ttys.
  399. * \param driver has the same meaning as in brlapi_enterTtyMode()
  400. *
  401. * Providing nttys == 0 means to get the root.
  402. *
  403. * \sa brlapi_enterTtyMode()
  404. */
  405. #ifndef BRLAPI_NO_SINGLE_SESSION
  406. int BRLAPI_STDCALL brlapi_enterTtyModeWithPath(int* ttys,
  407. int count,
  408. const char* driver);
  409. #endif /* BRLAPI_NO_SINGLE_SESSION */
  410. int BRLAPI_STDCALL brlapi__enterTtyModeWithPath(brlapi_handle_t* handle,
  411. int* ttys,
  412. int count,
  413. const char* driver);
  414. /* brlapi_leaveTtyMode */
  415. /** Stop controlling the tty
  416. *
  417. * \return 0 on success, -1 on error.
  418. *
  419. * \sa brlapi_enterTtyMode()
  420. */
  421. #ifndef BRLAPI_NO_SINGLE_SESSION
  422. int BRLAPI_STDCALL brlapi_leaveTtyMode(void);
  423. #endif /* BRLAPI_NO_SINGLE_SESSION */
  424. int BRLAPI_STDCALL brlapi__leaveTtyMode(brlapi_handle_t* handle);
  425. /* brlapi_setFocus */
  426. /** Tell the current tty to brltty
  427. *
  428. * This is intended for focus tellers, such as brltty, xbrlapi, screen, ...
  429. * brlapi_enterTtyMode() must have been called beforehand to tell where this
  430. * focus applies in the tty tree.
  431. *
  432. * \return 0 on success, -1 on error.
  433. *
  434. * \sa brlapi_enterTtyMode() brlapi_leaveTtyMode()
  435. */
  436. #ifndef BRLAPI_NO_SINGLE_SESSION
  437. int BRLAPI_STDCALL brlapi_setFocus(int tty);
  438. #endif /* BRLAPI_NO_SINGLE_SESSION */
  439. int BRLAPI_STDCALL brlapi__setFocus(brlapi_handle_t* handle, int tty);
  440. /** @} */
  441. /** \defgroup brlapi_write Writing on the braille display
  442. * \brief Write text to the braille display
  443. *
  444. * After brlapi_enterTtyMode() has been called, the application can
  445. * call one of these functions to write things on the braille display.
  446. *
  447. * \note Be sure to call brlapi_enterTtyMode() \e before calling brlapi_write(),
  448. * or else you'll get an error. This is particularly not always trivial when
  449. * writing multithreaded applications.
  450. *
  451. * \note Dots are coded as described in ISO/TR 11548-1: a dot pattern is coded
  452. * by a byte in which bit 0 is set iff dot 1 is up, bit 1 is set iff dot 2 is
  453. * up, ... bit 7 is set iff dot 8 is up. This also corresponds to the low-order
  454. * byte of the coding of unicode's braille row U+2800.
  455. *
  456. * \note Text is translated by the server one to one, by just using a simple
  457. * wchar_t to pattern table, i.e. no contraction/expansion is performed, because
  458. * the client would then have no way to know how wide the output would be and
  459. * thus the quantity of text to feed. If contraction/expansion is desired, the
  460. * client should perform it itself (e.g. thanks to liblouis or gnome-braille)
  461. * and send the resulting dot patterns. This is actually exactly the same
  462. * problem as font rendering on a graphical display: for better control,
  463. * nowadays all font rasterization is performed on the client side, and mere
  464. * pixmaps are sent to the X server.
  465. *
  466. * @{ */
  467. /* brlapi_writeText */
  468. /** Write the given \\0-terminated string to the braille display
  469. *
  470. * If the string is too long, it is truncated. If it's too short,
  471. * it is padded with spaces. The text is assumed to be in the current
  472. * locale charset set by setlocale(3) if it was called, or the locale charset
  473. * from the locale environment variables if setlocale(3) was not called.
  474. *
  475. * \param cursor gives the cursor position; if equal to ::BRLAPI_CURSOR_OFF, no
  476. * cursor is shown at all; if cursor==::BRLAPI_CURSOR_LEAVE, the cursor is left
  477. * where it is
  478. *
  479. * \param text points to the string to be displayed.
  480. *
  481. * \return 0 on success, -1 on error.
  482. */
  483. #ifndef BRLAPI_NO_SINGLE_SESSION
  484. int BRLAPI_STDCALL brlapi_writeText(int cursor, const char* text);
  485. #endif /* BRLAPI_NO_SINGLE_SESSION */
  486. int BRLAPI_STDCALL brlapi__writeText(brlapi_handle_t* handle,
  487. int cursor,
  488. const char* text);
  489. /* brlapi_writeWText */
  490. /** Write the given \\0-terminated unicode string to the braille display
  491. *
  492. * If the string is too long, it is truncated. If it's too short,
  493. * it is padded with spaces.
  494. *
  495. * \param cursor gives the cursor position; if equal to ::BRLAPI_CURSOR_OFF, no
  496. * cursor is shown at all; if cursor==::BRLAPI_CURSOR_LEAVE, the cursor is left
  497. * where it is
  498. *
  499. * \param text points to the string to be displayed.
  500. *
  501. * \return 0 on success, -1 on error.
  502. */
  503. #ifndef BRLAPI_NO_SINGLE_SESSION
  504. int BRLAPI_STDCALL brlapi_writeWText(int cursor, const wchar_t* text);
  505. #endif /* BRLAPI_NO_SINGLE_SESSION */
  506. int BRLAPI_STDCALL brlapi__writeWText(brlapi_handle_t* handle,
  507. int cursor,
  508. const wchar_t* text);
  509. /* brlapi_writeDots */
  510. /** Write the given dots array to the display
  511. *
  512. * \param dots points on an array of dot information, one per character. Its
  513. * size must hence be the same as what brlapi_getDisplaySize() returns.
  514. *
  515. * \return 0 on success, -1 on error.
  516. */
  517. #ifndef BRLAPI_NO_SINGLE_SESSION
  518. int BRLAPI_STDCALL brlapi_writeDots(const unsigned char* dots);
  519. #endif /* BRLAPI_NO_SINGLE_SESSION */
  520. int BRLAPI_STDCALL brlapi__writeDots(brlapi_handle_t* handle,
  521. const unsigned char* dots);
  522. /* brlapi_writeArguments_t */
  523. /** Structure containing arguments to be given to brlapi_write() */
  524. typedef struct {
  525. int displayNumber /** Display number ::BRLAPI_DISPLAY_DEFAULT == unspecified
  526. */
  527. ;
  528. unsigned int regionBegin /** Region of display to update, 1st character of
  529. display is 1 */
  530. ;
  531. unsigned int
  532. regionSize /** Number of characters held in text, andMask and orMask. */;
  533. char* text /** Text to display, must hold as many characters as the region
  534. fields expresses. */
  535. ;
  536. int textSize /** Size of text in bytes. If -1, strlen() is used for computing
  537. it. */
  538. ;
  539. unsigned char* andMask /** And attributes; applied first */;
  540. unsigned char* orMask /** Or attributes; applied \e after ANDing */;
  541. int cursor /** ::BRLAPI_CURSOR_LEAVE == don't touch, ::BRLAPI_CURSOR_OFF ==
  542. turn off, 1 = 1st char of display, ... */
  543. ;
  544. char* charset /** Text charset. NULL means it is assumed to be 8bits, and the
  545. same as the server's. "" means current locale's charset. If
  546. no locale was selected, defaults to NULL's meaning. */
  547. ;
  548. } brlapi_writeArguments_t;
  549. /** Write to the default display on the braille device.
  550. *
  551. * \sa brlapi_write() brlapi_writeArguments_t
  552. */
  553. #define BRLAPI_DISPLAY_DEFAULT -1
  554. /** Do not change the cursor's state or position.
  555. *
  556. * \sa brlapi_writeText() brlapi_write() brlapi_writeArguments_t
  557. */
  558. #define BRLAPI_CURSOR_LEAVE -1
  559. /** Do not display the cursor.
  560. *
  561. * \sa brlapi_writeText() brlapi_write() brlapi_writeArguments_t
  562. */
  563. #define BRLAPI_CURSOR_OFF 0
  564. /* BRLAPI_WRITEARGUMENTS_INITIALIZER */
  565. /** Allows to initialize a structure of type \e brlapi_writeArguments_t *
  566. * with default values:
  567. * displayNumber = ::BRLAPI_DISPLAY_DEFAULT; (unspecified)
  568. * regionBegin = regionSize = 0; (update the whole display, DEPRECATED and will
  569. * be forbidden in next release. You must always express the region you wish to
  570. * update)
  571. * text = andMask = orMask = NULL; (no text, no attribute)
  572. * cursor = ::BRLAPI_CURSOR_LEAVE; (don't touch cursor)
  573. */
  574. #define BRLAPI_WRITEARGUMENTS_INITIALIZER \
  575. { \
  576. .displayNumber = BRLAPI_DISPLAY_DEFAULT, .regionBegin = 0, \
  577. .regionSize = 0, .text = NULL, .textSize = -1, .andMask = NULL, \
  578. .orMask = NULL, .cursor = BRLAPI_CURSOR_LEAVE, .charset = NULL \
  579. }
  580. /* brlapi_write */
  581. /** Update a specific region of the braille display and apply and/or masks
  582. *
  583. * \param arguments gives information necessary for the update
  584. *
  585. * regionBegin and regionSize must be filled for specifying which part of the
  586. * display will be updated, as well as the size (in characters, not bytes) of
  587. * the text, andMask and orMask members.
  588. *
  589. * If given, the "text" field holds the text that will be displayed in the
  590. * region. The char string must hold exactly as many characters as the region
  591. * fields express. For multibyte text, this is the number of \e multibyte
  592. * caracters. Notably, combining and double-width caracters count for 1.
  593. *
  594. * The actual length of the text in \e bytes may be specified thanks to
  595. * textSize. If -1 is given, it will be computed thanks to strlen(), so "text"
  596. * must then be a NUL-terminated string.
  597. *
  598. * The "andMask" and "orMask" masks, if present, are then applied on top of
  599. * the text, one byte per character. This hence permits the superimposing of
  600. * attributes over the text. For instance, setting an andMask mask full of
  601. * BRLAPI_DOTS(1,1,1,1,1,1,0,0) will only keep (logical AND) dots 1-6,
  602. * hence dropping dots 7 and 8. On the contrary, setting an orMask full of
  603. * BRLAPI_DOT7|BRLAPI_DOT8 will add (logical OR) dots 7 and 8.
  604. *
  605. * The "charset" field, if present, specifies the charset of the "text" field.
  606. * If it is "", the current locale's charset (if any) is assumed. Else, the
  607. * 8-bit charset of the server is assumed.
  608. *
  609. * A special invocation is with an unmodified initialized structure: this clears
  610. * the client's whole display, letting the display of other applications on
  611. * the same tty or of applications "under" the tty appear. See Concurrency
  612. * management section of the BrlAPI documentation for more details.
  613. *
  614. * \return 0 on success, -1 on error.
  615. */
  616. #ifndef BRLAPI_NO_SINGLE_SESSION
  617. int BRLAPI_STDCALL brlapi_write(const brlapi_writeArguments_t* arguments);
  618. #endif /* BRLAPI_NO_SINGLE_SESSION */
  619. int BRLAPI_STDCALL brlapi__write(brlapi_handle_t* handle,
  620. const brlapi_writeArguments_t* arguments);
  621. /** @} */
  622. #include "brlapi_keycodes.h"
  623. /** \defgroup brlapi_keys Reading key presses
  624. * \brief How to read key presses from the braille terminal
  625. *
  626. * Once brlapi_enterTtyMode() has been called, the application can call
  627. * brlapi_readKey() to read key presses. Either key codes (see \ref
  628. * brlapi_keycodes) or commands will be returned, depending on parameters given
  629. * to brlapi_enterTtyMode().
  630. *
  631. * Key presses are buffered, so that calling brlapi_readKey() in non-blocking
  632. * mode from time to time should suffice.
  633. *
  634. * @{
  635. */
  636. /* brlapi_expandedKeyCode_t */
  637. /** Structure holding the components of a key code as returned by
  638. * brlapi_expandKeyCode() */
  639. typedef struct {
  640. unsigned int type /** the type value */;
  641. unsigned int command /** the command value */;
  642. unsigned int argument /** the argument value */;
  643. unsigned int flags /** the flags value */;
  644. } brlapi_expandedKeyCode_t;
  645. /* brlapi_expandKeyCode */
  646. /** Expand the components of a key code
  647. *
  648. * \param code the key code to be expanded
  649. * \param expansion pointer to the structure that receives the components
  650. *
  651. * \return 0 on success, -1 on error
  652. */
  653. int BRLAPI_STDCALL brlapi_expandKeyCode(brlapi_keyCode_t code,
  654. brlapi_expandedKeyCode_t* expansion);
  655. /* brlapi_describedKeyCode_t */
  656. /** Structure holding the components of a key code as returned by
  657. * brlapi_describeKeyCode() */
  658. typedef struct {
  659. const char* type /** the type name */;
  660. const char* command /** the command name */;
  661. unsigned int argument /** the argument value */;
  662. unsigned int flags /** the flag count */;
  663. const char* flag[64 - BRLAPI_KEY_FLAGS_SHIFT] /** the flag names */;
  664. brlapi_expandedKeyCode_t values /** the actual values of the components */;
  665. } brlapi_describedKeyCode_t;
  666. /* brlapi_describeKeyCode */
  667. /** Describe the components of a key code.
  668. *
  669. * \param code the keycode to be described
  670. * \param description pointer to the structure that receives the description
  671. *
  672. * \return 0 on success, -1 on error
  673. */
  674. int BRLAPI_STDCALL
  675. brlapi_describeKeyCode(brlapi_keyCode_t code,
  676. brlapi_describedKeyCode_t* description);
  677. /** Unicode braille row */
  678. #define BRLAPI_UC_ROW 0x2800UL
  679. /* brlapi_readKey */
  680. /** Read a key from the braille keyboard
  681. *
  682. * This function returns one key press's code.
  683. *
  684. * If NULL or "" was given to brlapi_enterTtyMode(), a \e brltty command is
  685. * returned, as described in the documentation for ::brlapi_keyCode_t . It is
  686. * hence pretty driver-independent, and should be used by default when no other
  687. * option is possible.
  688. *
  689. * By default, all commands but those which restart drivers and switch
  690. * virtual terminals are returned to the application and not to brltty.
  691. * If the application doesn't want to see some command events,
  692. * it should call brlapi_ignoreKeys()
  693. *
  694. * If some driver name was given to brlapi_enterTtyMode(), a raw keycode is
  695. * returned, as specified by the terminal driver, usually in <brltty/brldefs-xy>
  696. * where xy is the driver's code. It generally corresponds to the very code that
  697. * the terminal tells to the driver. This should only be used by applications
  698. * which are dedicated to a particular braille terminal. Hence, checking the
  699. * terminal type thanks to a call to brlapi_getDriverName() before getting tty
  700. * control is a pretty good idea.
  701. *
  702. * By default, all the keypresses will be passed to the client, none will go
  703. * through brltty, so the application will have to handle console switching
  704. * itself for instance.
  705. *
  706. * \param wait tells whether the call should block until a key is pressed (1)
  707. * or should only probe key presses (0);
  708. * \param code holds the key code if a key press is indeed read.
  709. *
  710. * \return -1 on error or signal interrupt and *code is then undefined, 0 if
  711. * block was 0 and no key was pressed so far, or 1 and *code holds the key code.
  712. *
  713. * Programming hints:
  714. *
  715. * If your application is only driven by braille command keypresses, you can
  716. * just call brlapi_readKey(1, &code) so that it keeps blocking, waiting for
  717. * keypresses.
  718. *
  719. * Else, you'll probably want to use the file descriptor returned by
  720. * brlapi_openConnection() in your "big polling loop". For instance:
  721. *
  722. * - in a \c select() loop, just add it to the \c readfds and \c exceptfds file
  723. * descriptor sets;
  724. * - in a gtk or atspi application, use
  725. * \c g_io_add_watch(fileDescriptor, \c G_IO_IN|G_IO_ERR|G_IO_HUP, \c f, \c
  726. * data) for adding a callback called \c f;
  727. * - in an Xt/Xaw/motif-based application, use
  728. * \c XtAppAddInput(app_context, \c fileDescriptor, \c
  729. * XtInputReadMask|XtInputExceptMask, \c f, \c data)
  730. * - etc.
  731. *
  732. * and then, when you detect inbound trafic on the file descriptor, do something
  733. * like this:
  734. *
  735. * while (brlapi_readKey(0, &code) {
  736. * // process keycode code
  737. * // ...
  738. * }
  739. *
  740. * The \c while loop is needed for processing \e all pending key presses, else
  741. * some of them may be left in libbrlapi's internal key buffer and you wouldn't
  742. * get them immediately.
  743. *
  744. * \note If the read is interrupted by a signal, brlapi_readKey() will return
  745. * -1, brlapi_errno will be BRLAPI_ERROR_LIBCERR and errno will be EINTR.
  746. */
  747. #ifndef BRLAPI_NO_SINGLE_SESSION
  748. int BRLAPI_STDCALL brlapi_readKey(int wait, brlapi_keyCode_t* code);
  749. #endif /* BRLAPI_NO_SINGLE_SESSION */
  750. int BRLAPI_STDCALL brlapi__readKey(brlapi_handle_t* handle,
  751. int wait,
  752. brlapi_keyCode_t* code);
  753. /* brlapi_readKeyWithTimeout */
  754. /** Read a key from the braille keyboard, unless a timeout expires
  755. *
  756. * This function works like brlapi_readKey, except that parameter \e wait is
  757. * replaced by a \e timeout_ms parameter
  758. *
  759. * \param timeout_ms specifies how long the function should wait for a keypress.
  760. * \param code holds the key code if a key press is indeed read.
  761. *
  762. * \return -1 on error or signal interrupt and *code is then undefined, 0 if
  763. * the timeout expired and no key was pressed, or 1 and *code holds the key
  764. * code.
  765. *
  766. * If the timeout expires without any key being pressed, 0 is returned.
  767. *
  768. * If timeout_ms is set to 0, this function looks for key events that have been
  769. * already received, but does not wait at all if no event was received.
  770. *
  771. * If timeout_ms is set to a negative value, this function behaves like
  772. * brlapi_readKey, i.e. it uses an infinite timeout.
  773. */
  774. #ifndef BRLAPI_NO_SINGLE_SESSION
  775. int BRLAPI_STDCALL brlapi_readKeyWithTimeout(int timeout_ms,
  776. brlapi_keyCode_t* code);
  777. #endif /* BRLAPI_NO_SINGLE_SESSION */
  778. int BRLAPI_STDCALL brlapi__readKeyWithTimeout(brlapi_handle_t* handle,
  779. int timeout_ms,
  780. brlapi_keyCode_t* code);
  781. /** types of key ranges */
  782. typedef enum {
  783. brlapi_rangeType_all, /**< all keys, code must be 0 */
  784. brlapi_rangeType_type, /**< all keys of a given type */
  785. brlapi_rangeType_command, /**< all keys of a given command block, i.e.
  786. matching the key type and command parts */
  787. brlapi_rangeType_key, /**< a given key with any flags */
  788. brlapi_rangeType_code, /**< a given key code */
  789. } brlapi_rangeType_t;
  790. /* brlapi_ignoreKeys */
  791. /** Ignore some key presses from the braille keyboard
  792. *
  793. * This function asks the server to give the provided keys to \e brltty, rather
  794. * than returning them to the application via brlapi_readKey().
  795. *
  796. * \param type type of keys to be ignored
  797. * \param keys array of keys to be ignored
  798. * \param count number of keys
  799. *
  800. * \note The given codes should be \e brltty commands (NULL or "" was given to
  801. * brlapi_enterTtyMode())
  802. */
  803. #ifndef BRLAPI_NO_SINGLE_SESSION
  804. int BRLAPI_STDCALL brlapi_ignoreKeys(brlapi_rangeType_t type,
  805. const brlapi_keyCode_t keys[],
  806. unsigned int count);
  807. #endif /* BRLAPI_NO_SINGLE_SESSION */
  808. int BRLAPI_STDCALL brlapi__ignoreKeys(brlapi_handle_t* handle,
  809. brlapi_rangeType_t type,
  810. const brlapi_keyCode_t keys[],
  811. unsigned int count);
  812. /* brlapi_acceptKeys */
  813. /** Accept some key presses from the braille keyboard
  814. *
  815. * This function asks the server to give the provided keys to the application,
  816. * and not give them to \e brltty.
  817. *
  818. * \param type type of keys to be ignored
  819. * \param keys array of keys to be ignored
  820. * \param count number of keys
  821. *
  822. * \note The given codes should be \e brltty commands (NULL or "" was given to
  823. * brlapi_enterTtyMode())
  824. */
  825. #ifndef BRLAPI_NO_SINGLE_SESSION
  826. int BRLAPI_STDCALL brlapi_acceptKeys(brlapi_rangeType_t type,
  827. const brlapi_keyCode_t keys[],
  828. unsigned int count);
  829. #endif /* BRLAPI_NO_SINGLE_SESSION */
  830. int BRLAPI_STDCALL brlapi__acceptKeys(brlapi_handle_t* handle,
  831. brlapi_rangeType_t type,
  832. const brlapi_keyCode_t keys[],
  833. unsigned int count);
  834. /* brlapi_ignoreAllKeys */
  835. /** Ignore all key presses from the braille keyboard
  836. *
  837. * This function asks the server to give all keys to \e brltty, rather than
  838. * returning them to the application via brlapi_readKey().
  839. */
  840. #ifndef BRLAPI_NO_SINGLE_SESSION
  841. int BRLAPI_STDCALL brlapi_ignoreAllKeys(void);
  842. #define brlapi_ignoreAllKeys() brlapi_ignoreKeys(brlapi_rangeType_all, NULL, 0)
  843. #endif /* BRLAPI_NO_SINGLE_SESSION */
  844. int BRLAPI_STDCALL brlapi__ignoreAllKeys(brlapi_handle_t* handle);
  845. #define brlapi__ignoreAllKeys(handle) \
  846. brlapi__ignoreKeys(handle, brlapi_rangeType_all, NULL, 0)
  847. /* brlapi_acceptAllKeys */
  848. /** Accept all key presses from the braille keyboard
  849. *
  850. * This function asks the server to give all keys to the application, and not
  851. * give them to \e brltty.
  852. *
  853. * Warning: after calling this function, make sure to call brlapi_ignoreKeys()
  854. * for ignoring important keys like BRL_CMD_SWITCHVT_PREV/NEXT and such.
  855. */
  856. #ifndef BRLAPI_NO_SINGLE_SESSION
  857. int BRLAPI_STDCALL brlapi_acceptAllKeys(void);
  858. #define brlapi_acceptAllKeys() brlapi_acceptKeys(brlapi_rangeType_all, NULL, 0)
  859. #endif /* BRLAPI_NO_SINGLE_SESSION */
  860. int BRLAPI_STDCALL brlapi__acceptAllKeys(brlapi_handle_t* handle);
  861. #define brlapi__acceptAllKeys(handle) \
  862. brlapi__acceptKeys(handle, brlapi_rangeType_all, NULL, 0)
  863. /** Type for raw keycode ranges
  864. *
  865. * Denotes the set of keycodes between \e first and \e last (inclusive)
  866. */
  867. typedef struct {
  868. brlapi_keyCode_t first; /**< first key of the range */
  869. brlapi_keyCode_t last; /**< last key of the range */
  870. } brlapi_range_t;
  871. /* brlapi_ignoreKeyRanges */
  872. /** Ignore some key presses from the braille keyboard
  873. *
  874. * This function asks the server to give the provided key ranges to \e brltty,
  875. * rather than returning them to the application via brlapi_readKey().
  876. *
  877. * \param ranges key ranges, which are inclusive
  878. * \param count number of ranges
  879. *
  880. * \note The given codes should be raw keycodes (i.e. some driver name was given
  881. * to brlapi_enterTtyMode()) */
  882. #ifndef BRLAPI_NO_SINGLE_SESSION
  883. int BRLAPI_STDCALL brlapi_ignoreKeyRanges(const brlapi_range_t ranges[],
  884. unsigned int count);
  885. #endif /* BRLAPI_NO_SINGLE_SESSION */
  886. int BRLAPI_STDCALL brlapi__ignoreKeyRanges(brlapi_handle_t* handle,
  887. const brlapi_range_t ranges[],
  888. unsigned int count);
  889. /* brlapi_acceptKeyRanges */
  890. /** Accept some key presses from the braille keyboard
  891. *
  892. * This function asks the server to return the provided key ranges (inclusive)
  893. * to the application, and not give them to \e brltty.
  894. *
  895. * \param ranges key ranges, which are inclusive
  896. * \param count number of ranges
  897. *
  898. * \note The given codes should be raw keycodes (i.e. some driver name was given
  899. * to brlapi_enterTtyMode()) */
  900. #ifndef BRLAPI_NO_SINGLE_SESSION
  901. int BRLAPI_STDCALL brlapi_acceptKeyRanges(const brlapi_range_t ranges[],
  902. unsigned int count);
  903. #endif /* BRLAPI_NO_SINGLE_SESSION */
  904. int BRLAPI_STDCALL brlapi__acceptKeyRanges(brlapi_handle_t* handle,
  905. const brlapi_range_t ranges[],
  906. unsigned int count);
  907. /** @} */
  908. /** \defgroup brlapi_driverspecific Driver-Specific modes
  909. * \brief Raw and Suspend Modes mechanism
  910. *
  911. * If the application wants to directly talk to the braille terminal, it should
  912. * use Raw Mode. In this special mode, the driver gives the whole control of the
  913. * terminal to it: \e brltty doesn't work any more.
  914. *
  915. * For this, it simply has to call brlapi_enterRawMode(), then brlapi_sendRaw()
  916. * and brlapi_recvRaw(), and finally give control back thanks to
  917. * brlapi_leaveRawMode().
  918. *
  919. * Special care of the terminal should be taken, since one might completely
  920. * trash the terminal's data, or even lock it! The application should always
  921. * check for terminal's type thanks to brlapi_getDriverName().
  922. *
  923. * The client can also make brltty close the driver by using
  924. * brlapi_suspendDriver(), and resume it again with brlapi_resumeDriver(). This
  925. * should not be used if possible: raw mode should be sufficient for any use. If
  926. * not, please ask for features :)
  927. *
  928. * @{
  929. */
  930. /* brlapi_enterRawMode */
  931. /** Switch to Raw mode
  932. * \param driver Specifies the name of the driver for which the raw
  933. * communication will be established.
  934. * \return 0 on success, -1 on error */
  935. #ifndef BRLAPI_NO_SINGLE_SESSION
  936. int BRLAPI_STDCALL brlapi_enterRawMode(const char* driver);
  937. #endif /* BRLAPI_NO_SINGLE_SESSION */
  938. int BRLAPI_STDCALL brlapi__enterRawMode(brlapi_handle_t* handle,
  939. const char* driver);
  940. /* brlapi_leaveRawMode */
  941. /** Leave Raw mode
  942. * \return 0 on success, -1 on error */
  943. #ifndef BRLAPI_NO_SINGLE_SESSION
  944. int BRLAPI_STDCALL brlapi_leaveRawMode(void);
  945. #endif /* BRLAPI_NO_SINGLE_SESSION */
  946. int BRLAPI_STDCALL brlapi__leaveRawMode(brlapi_handle_t* handle);
  947. /* brlapi_sendRaw */
  948. /** Send Raw data
  949. *
  950. * \param buffer points on the data;
  951. * \param size holds the packet size.
  952. * \return size on success, -1 on error */
  953. #ifndef BRLAPI_NO_SINGLE_SESSION
  954. ssize_t BRLAPI_STDCALL brlapi_sendRaw(const void* buffer, size_t size);
  955. #endif /* BRLAPI_NO_SINGLE_SESSION */
  956. ssize_t BRLAPI_STDCALL brlapi__sendRaw(brlapi_handle_t* handle,
  957. const void* buffer,
  958. size_t size);
  959. /* brlapi_recvRaw */
  960. /** Get Raw data
  961. *
  962. * \param buffer points on a buffer where the function will store the received
  963. * data;
  964. * \param size holds the buffer size.
  965. * \return its size, -1 on error or signal interruption */
  966. #ifndef BRLAPI_NO_SINGLE_SESSION
  967. ssize_t BRLAPI_STDCALL brlapi_recvRaw(void* buffer, size_t size);
  968. #endif /* BRLAPI_NO_SINGLE_SESSION */
  969. ssize_t BRLAPI_STDCALL brlapi__recvRaw(brlapi_handle_t* handle,
  970. void* buffer,
  971. size_t size);
  972. /* brlapi_suspendDriver */
  973. /** Suspend braille driver
  974. * \param driver Specifies the name of the driver which will be suspended.
  975. * \return -1 on error
  976. */
  977. #ifndef BRLAPI_NO_SINGLE_SESSION
  978. int BRLAPI_STDCALL brlapi_suspendDriver(const char* driver);
  979. #endif /* BRLAPI_NO_SINGLE_SESSION */
  980. int BRLAPI_STDCALL brlapi__suspendDriver(brlapi_handle_t* handle,
  981. const char* driver);
  982. /* brlapi_resumeDriver */
  983. /** Resume braille driver
  984. * \return -1 on error
  985. */
  986. #ifndef BRLAPI_NO_SINGLE_SESSION
  987. int BRLAPI_STDCALL brlapi_resumeDriver(void);
  988. #endif /* BRLAPI_NO_SINGLE_SESSION */
  989. int BRLAPI_STDCALL brlapi__resumeDriver(brlapi_handle_t* handle);
  990. /** @} */
  991. #include "brlapi_param.h"
  992. /** \defgroup brlapi_parameterManagement Parameter management
  993. * \brief How to manage BrlAPI parameters
  994. *
  995. * There are several kinds of parameters:
  996. * - states associated with the braille device itself, such as its size or
  997. * parameters of the device port
  998. * - states of the BrlAPI connection itself, such as the displaying level or
  999. * key passing preferences.
  1000. * - general states such as the cut buffer,
  1001. * - braille parameters: braille table, contraction, cursor shape, etc,
  1002. * - browse parameters: line skip, beep, etc.
  1003. *
  1004. * Some of them are subdivided in subparameters. Others have only subparameter
  1005. * 0.
  1006. *
  1007. * Some of them are read-only, others are read/write.
  1008. *
  1009. * A client can either request the immediate content of a parameter by
  1010. * using brlapi_getParameter(); set the content of a parameter by using
  1011. * brlapi_setParameter(); or register a callback that may be called immediately
  1012. * and on each change of a given parameter, by using brlapi_watchParameter().
  1013. *
  1014. * @{ */
  1015. /** Flags for parameter requests */
  1016. typedef uint32_t brlapi_param_flags_t;
  1017. #define BRLAPI_PARAMF_LOCAL \
  1018. 0X00 /**< Refer to the value local to the connection instead of the global \
  1019. value */
  1020. #define BRLAPI_PARAMF_GLOBAL \
  1021. 0X01 /**< Refer to the global value instead of the value local to the \
  1022. connection */
  1023. #define BRLAPI_PARAMF_SELF \
  1024. 0X02 /**< Specify whether to receive notifications of value self-changes */
  1025. /* brlapi_getParameter */
  1026. /** Get the content of a parameter
  1027. *
  1028. * brlapi_getParameter gets the current content of a parameter
  1029. *
  1030. * \param parameter is the parameter whose content shall be gotten;
  1031. * \param subparam is a specific instance of the parameter;
  1032. * \param flags specify which value and how it should be returned;
  1033. * \param data is a buffer where content of the parameter shall be stored;
  1034. * \param len is the size of the buffer.
  1035. *
  1036. * \return the real size of the parameter's content. If the parameter does not
  1037. * fit in the provided buffer, it is truncated to len bytes (but the real size
  1038. * of the parameter is still returned). In that case, the client must call
  1039. * brlapi_getParameter again with a big enough buffer.
  1040. */
  1041. #ifndef BRLAPI_NO_SINGLE_SESSION
  1042. ssize_t BRLAPI_STDCALL brlapi_getParameter(brlapi_param_t parameter,
  1043. brlapi_param_subparam_t subparam,
  1044. brlapi_param_flags_t flags,
  1045. void* data,
  1046. size_t len);
  1047. #endif
  1048. ssize_t BRLAPI_STDCALL brlapi__getParameter(brlapi_handle_t* handle,
  1049. brlapi_param_t parameter,
  1050. brlapi_param_subparam_t subparam,
  1051. brlapi_param_flags_t flags,
  1052. void* data,
  1053. size_t len);
  1054. /* brlapi_getParameterAlloc */
  1055. /** Return the content of a parameter
  1056. *
  1057. * brlapi_getParameterAlloc gets the current content of a parameter, by
  1058. * returning it as a newly-allocated buffer. The buffer is allocated to one byte
  1059. * more than the parameter value. This byte is set to zero. This allows, for
  1060. * string parameters, to be able to immediately use it as a C string.
  1061. *
  1062. * \param parameter is the parameter whose content shall be gotten;
  1063. * \param subparam is a specific instance of the parameter;
  1064. * \param flags specify which value and how it should be returned;
  1065. * \param len is the address where to store the size of the parameter value.
  1066. *
  1067. * \return a newly-allocated buffer that contains the value of the parameter.
  1068. * The caller must call free() on it after use. NULL is returned on errors
  1069. */
  1070. #ifndef BRLAPI_NO_SINGLE_SESSION
  1071. void* BRLAPI_STDCALL brlapi_getParameterAlloc(brlapi_param_t parameter,
  1072. brlapi_param_subparam_t subparam,
  1073. brlapi_param_flags_t flags,
  1074. size_t* len);
  1075. #endif
  1076. void* BRLAPI_STDCALL brlapi__getParameterAlloc(brlapi_handle_t* handle,
  1077. brlapi_param_t parameter,
  1078. brlapi_param_subparam_t subparam,
  1079. brlapi_param_flags_t flags,
  1080. size_t* len);
  1081. /* brlapi_setParameter */
  1082. /** Set the content of a parameter
  1083. *
  1084. * brlapi_setParameter sets the content of a parameter
  1085. *
  1086. * \param parameter is the parameter to set;
  1087. * \param subparam is a specific instance of the parameter;
  1088. * \param flags specify which value and how it should be set;
  1089. * \param data is a buffer containing the data to store in the parameter;
  1090. * \param len is the size of the data.
  1091. *
  1092. * \return 0 on success, -1 on error (read-only parameter for instance).
  1093. */
  1094. #ifndef BRLAPI_NO_SINGLE_SESSION
  1095. int BRLAPI_STDCALL brlapi_setParameter(brlapi_param_t parameter,
  1096. brlapi_param_subparam_t subparam,
  1097. brlapi_param_flags_t flags,
  1098. const void* data,
  1099. size_t len);
  1100. #endif
  1101. int BRLAPI_STDCALL brlapi__setParameter(brlapi_handle_t* handle,
  1102. brlapi_param_t parameter,
  1103. brlapi_param_subparam_t subparam,
  1104. brlapi_param_flags_t flags,
  1105. const void* data,
  1106. size_t len);
  1107. /* brlapi_paramCallback_t */
  1108. /** Callback for parameter changes
  1109. *
  1110. * When a parameter gets changed, application-defined callbacks set by the
  1111. * brlapi_watchParameter() function are called.
  1112. *
  1113. * \param parameter is the parameter that changed;
  1114. * \param flags specify which value and how it was changed;
  1115. * \param priv is the void pointer that was passed to the brlapi_watchParameter
  1116. * call which registered the callback; \param data is a buffer containing the
  1117. * new value of the parameter; \param len is the size of the data.
  1118. *
  1119. * This callback only gets called when the application calls some brlapi_
  1120. * function (i.e. BrlAPI gets direct control of the execution).
  1121. */
  1122. typedef void (*brlapi_paramCallback_t)(brlapi_param_t parameter,
  1123. brlapi_param_subparam_t subparam,
  1124. brlapi_param_flags_t flags,
  1125. void* priv,
  1126. const void* data,
  1127. size_t len);
  1128. /* brlapi_paramCallbackDescriptor_t */
  1129. /** Type for callback descriptors
  1130. * This is returned by brlapi_watchParameter, to be passed to
  1131. * brlapi_unwatchParameter.
  1132. */
  1133. typedef void* brlapi_paramCallbackDescriptor_t;
  1134. /* brlapi_watchParameter */
  1135. /** Set a parameter change callback
  1136. *
  1137. * brlapi_watchParameter registers a parameter change callback: whenever the
  1138. * given parameter changes, the given function is called.
  1139. *
  1140. * \param parameter is the parameter to watch;
  1141. * \param subparam is a specific instance of the parameter;
  1142. * \param flags specify which value and how it should be monitored;
  1143. * \param func is the function to call on parameter change;
  1144. * \param priv is a void pointer which will be passed as such to the function;
  1145. * \param data is a buffer where the current content of the parameter shall be
  1146. * stored;
  1147. * \param len is the size of the buffer.
  1148. *
  1149. * \return the callback descriptor (to be passed to brlapi_unwatchParameter to
  1150. * unregister the callback), or NULL on error.
  1151. *
  1152. * \note Default parameter callbacks don't do anything, except the ones for
  1153. * display size which just raise SIGWINCH.
  1154. * \note If data is NULL, the callback will be called immediately by
  1155. * brlapi_watchParameter, for providing the initial value
  1156. */
  1157. #ifndef BRLAPI_NO_SINGLE_SESSION
  1158. brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL
  1159. brlapi_watchParameter(brlapi_param_t parameter,
  1160. brlapi_param_subparam_t subparam,
  1161. brlapi_param_flags_t flags,
  1162. brlapi_paramCallback_t func,
  1163. void* priv,
  1164. void* data,
  1165. size_t len);
  1166. #endif
  1167. brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL
  1168. brlapi__watchParameter(brlapi_handle_t* handle,
  1169. brlapi_param_t parameter,
  1170. brlapi_param_subparam_t subparam,
  1171. brlapi_param_flags_t flags,
  1172. brlapi_paramCallback_t func,
  1173. void* priv,
  1174. void* data,
  1175. size_t len);
  1176. /* brlapi_unwatchParameter */
  1177. /** Clear a parameter change callback
  1178. *
  1179. * brlapi_unwatchParameter unregisters a parameter change callback: the
  1180. * callback function previously registered with brlapi_watchParameter will
  1181. * not be called any longer.
  1182. *
  1183. * \param descriptor refers to the callback to be removed.
  1184. *
  1185. * \return 0 on success, -1 on error.
  1186. */
  1187. #ifndef BRLAPI_NO_SINGLE_SESSION
  1188. int BRLAPI_STDCALL
  1189. brlapi_unwatchParameter(brlapi_paramCallbackDescriptor_t descriptor);
  1190. #endif
  1191. int BRLAPI_STDCALL
  1192. brlapi__unwatchParameter(brlapi_handle_t* handle,
  1193. brlapi_paramCallbackDescriptor_t descriptor);
  1194. /** @} */
  1195. /** \defgroup brlapi_misc Miscellaneous functions
  1196. * @{ */
  1197. /* brlapi_pause */
  1198. /**
  1199. * Waits until an event is received from the BrlAPI server
  1200. * \param timeout_ms specifies an optional timeout which can be zero for
  1201. * polling, or -1 for infinite wait \return nothing
  1202. */
  1203. #ifndef BRLAPI_NO_SINGLE_SESSION
  1204. void BRLAPI_STDCALL brlapi_pause(int timeout_ms);
  1205. #endif
  1206. void BRLAPI_STDCALL brlapi__pause(brlapi_handle_t* handle, int timeout_ms);
  1207. /** @} */
  1208. /** \defgroup brlapi_error Error handling
  1209. * \brief How to handle errors
  1210. *
  1211. * When a function fails, ::brlapi_errno will hold an error
  1212. * code to explain why it failed. It should always be reported somehow.
  1213. *
  1214. * Although most errors are reported that way, some (called exceptions)
  1215. * are reported asynchronously for efficiency reasons, because they always
  1216. * just report a programming error. The affected functions are: brlapi_setFocus,
  1217. * brlapi_write* and brlapi_sendRaw. When they happen, the next call to
  1218. * brlapi_something will close the connection and call the \e exception
  1219. * handler. If the exception handler returns, the brlapi_something function will
  1220. * return an end-of-file error.
  1221. *
  1222. * The default exception handler (brlapi_defaultExceptionHandler()) dumps
  1223. * the guilty packet before abort()ing. It can be replaced by calling
  1224. * brlapi_setExceptionHandler(). For instance, the Java and Python bindings use
  1225. * this for raising a Java or Python exception that may be caught.
  1226. *
  1227. * @{ */
  1228. /* Error codes */
  1229. #define BRLAPI_ERROR_SUCCESS 0 /**< Success */
  1230. #define BRLAPI_ERROR_NOMEM 1 /**< Not enough memory */
  1231. #define BRLAPI_ERROR_TTYBUSY \
  1232. 2 /**< A connection is already running in this tty */
  1233. #define BRLAPI_ERROR_DEVICEBUSY \
  1234. 3 /**< A connection is already using RAW or suspend mode */
  1235. #define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4 /**< Not implemented in protocol */
  1236. #define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5 /**< Forbiden in current mode */
  1237. #define BRLAPI_ERROR_INVALID_PARAMETER 6 /**< Out of range or have no sense */
  1238. #define BRLAPI_ERROR_INVALID_PACKET 7 /**< Invalid size */
  1239. #define BRLAPI_ERROR_CONNREFUSED 8 /**< Connection refused */
  1240. #define BRLAPI_ERROR_OPNOTSUPP 9 /**< Operation not supported */
  1241. #define BRLAPI_ERROR_GAIERR 10 /**< Getaddrinfo error */
  1242. #define BRLAPI_ERROR_LIBCERR 11 /**< Libc error */
  1243. #define BRLAPI_ERROR_UNKNOWNTTY 12 /**< Couldn't find out the tty number */
  1244. #define BRLAPI_ERROR_PROTOCOL_VERSION 13 /**< Bad protocol version */
  1245. #define BRLAPI_ERROR_EOF 14 /**< Unexpected end of file */
  1246. #define BRLAPI_ERROR_EMPTYKEY 15 /**< Key file empty */
  1247. #define BRLAPI_ERROR_DRIVERERROR \
  1248. 16 /**< Packet returned by driver too large \
  1249. */
  1250. #define BRLAPI_ERROR_AUTHENTICATION 17 /**< Authentication failed */
  1251. #define BRLAPI_ERROR_READONLY_PARAMETER \
  1252. 18 /**< Parameter can not be changed \
  1253. */
  1254. /* brlapi_errlist */
  1255. /** Error message list
  1256. *
  1257. * These are the string constants used by brlapi_perror().
  1258. */
  1259. extern const char* brlapi_errlist[];
  1260. /* brlapi_nerr */
  1261. /** Number of error messages */
  1262. extern const int brlapi_nerr;
  1263. /* brlapi_perror */
  1264. /** Print a BrlAPI error message
  1265. *
  1266. * brlapi_perror() reads ::brlapi_error, and acts just like perror().
  1267. */
  1268. void BRLAPI_STDCALL brlapi_perror(const char* s);
  1269. /* brlapi_error_t */
  1270. /** All information that is needed to describe brlapi errors */
  1271. typedef struct {
  1272. int brlerrno;
  1273. int libcerrno;
  1274. int gaierrno;
  1275. const char* errfun;
  1276. } brlapi_error_t;
  1277. /** Get per-thread error location
  1278. *
  1279. * In multithreaded software, ::brlapi_error is thread-specific, so api.h
  1280. * cheats about the brlapi_error token and actually calls
  1281. * brlapi_error_location().
  1282. *
  1283. * This gets the thread specific location of global variable ::brlapi_error
  1284. */
  1285. brlapi_error_t* BRLAPI_STDCALL brlapi_error_location(void);
  1286. /** Global variable brlapi_error
  1287. *
  1288. * ::brlapi_error is a global left-value containing the last error information.
  1289. * Its errno field is not reset to BRLAPI_ERROR_SUCCESS on success.
  1290. *
  1291. * This information may be copied in brlapi_error_t variables for later use
  1292. * with the brlapi_strerror function.
  1293. */
  1294. extern brlapi_error_t brlapi_error;
  1295. /** Shorthand for brlapi_error.errno */
  1296. extern int brlapi_errno;
  1297. /** Shorthand for brlapi_error.libcerrno */
  1298. extern int brlapi_libcerrno;
  1299. /** Shorthand for brlapi_error.gaierrno */
  1300. extern int brlapi_gaierrno;
  1301. /** Shorthand for brlapi_error.errfun */
  1302. extern const char* brlapi_errfun;
  1303. /** Cheat about the brlapi_error C token */
  1304. #define brlapi_error (*brlapi_error_location())
  1305. /** Cheat about the brlapi_errno C token */
  1306. #define brlapi_errno (brlapi_error.brlerrno)
  1307. /** Cheat about the brlapi_libcerrno C token */
  1308. #define brlapi_libcerrno (brlapi_error.libcerrno)
  1309. /** Cheat about the brlapi_gaierrno C token */
  1310. #define brlapi_gaierrno (brlapi_error.gaierrno)
  1311. /** Cheat about the brlapi_errfun C token */
  1312. #define brlapi_errfun (brlapi_error.errfun)
  1313. /* brlapi_strerror */
  1314. /** Get plain error message
  1315. *
  1316. * brlapi_strerror() returns the plain error message corresponding to its
  1317. * argument.
  1318. */
  1319. const char* BRLAPI_STDCALL brlapi_strerror(const brlapi_error_t* error);
  1320. /** Type for packet type. Only unsigned can cross networks, 32bits */
  1321. typedef uint32_t brlapi_packetType_t;
  1322. /* brlapi_getPacketTypeName */
  1323. /** Get plain packet type
  1324. *
  1325. * brlapi_getPacketTypeName() returns the plain packet type name corresponding
  1326. * to its argument.
  1327. */
  1328. const char* BRLAPI_STDCALL brlapi_getPacketTypeName(brlapi_packetType_t type);
  1329. /* brlapi_exceptionHandler_t */
  1330. /** Types for exception handlers
  1331. *
  1332. * Types of exception handlers which are to be given to
  1333. * brlapi_setExceptionHandler() and brlapi__setExceptionHandler().
  1334. *
  1335. * \param handle is the handle corresponding to the guilty connection;
  1336. * \param error is a BRLAPI_ERROR_ error code;
  1337. * \param type is the type of the guilty packet;
  1338. * \param packet points to the content of the guilty packet (might be a little
  1339. * bit truncated); \param size gives the guilty packet's size.
  1340. */
  1341. #ifndef BRLAPI_NO_SINGLE_SESSION
  1342. typedef void(BRLAPI_STDCALL* brlapi_exceptionHandler_t)(
  1343. int error,
  1344. brlapi_packetType_t type,
  1345. const void* packet,
  1346. size_t size);
  1347. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1348. typedef void(BRLAPI_STDCALL* brlapi__exceptionHandler_t)(
  1349. brlapi_handle_t* handle,
  1350. int error,
  1351. brlapi_packetType_t type,
  1352. const void* packet,
  1353. size_t size);
  1354. /* brlapi_strexception */
  1355. /** Describes an exception
  1356. *
  1357. * brlapi_strexception() puts a text describing the given exception in buffer.
  1358. *
  1359. * The beginning of the guilty packet is dumped as a sequence of hex bytes.
  1360. *
  1361. * \return the size of the text describing the exception, following
  1362. * snprintf()'s semantics.
  1363. */
  1364. #ifndef BRLAPI_NO_SINGLE_SESSION
  1365. int BRLAPI_STDCALL brlapi_strexception(char* buffer,
  1366. size_t bufferSize,
  1367. int error,
  1368. brlapi_packetType_t type,
  1369. const void* packet,
  1370. size_t packetSize);
  1371. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1372. int BRLAPI_STDCALL brlapi__strexception(brlapi_handle_t* handle,
  1373. char* buffer,
  1374. size_t bufferSize,
  1375. int error,
  1376. brlapi_packetType_t type,
  1377. const void* packet,
  1378. size_t packetSize);
  1379. /* brlapi_setExceptionHandler */
  1380. /** Set a new exception handler
  1381. *
  1382. * brlapi_setExceptionHandler() replaces the previous exception handler with
  1383. * the handler parameter. The previous exception handler is returned to make
  1384. * chaining error handlers possible.
  1385. *
  1386. * The default handler just prints the exception and abort()s.
  1387. */
  1388. #ifndef BRLAPI_NO_SINGLE_SESSION
  1389. brlapi_exceptionHandler_t BRLAPI_STDCALL
  1390. brlapi_setExceptionHandler(brlapi_exceptionHandler_t handler);
  1391. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1392. brlapi__exceptionHandler_t BRLAPI_STDCALL
  1393. brlapi__setExceptionHandler(brlapi_handle_t* handle,
  1394. brlapi__exceptionHandler_t handler);
  1395. #ifndef BRLAPI_NO_SINGLE_SESSION
  1396. void BRLAPI_STDCALL brlapi_defaultExceptionHandler(int error,
  1397. brlapi_packetType_t type,
  1398. const void* packet,
  1399. size_t size);
  1400. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1401. void BRLAPI_STDCALL brlapi__defaultExceptionHandler(brlapi_handle_t* handle,
  1402. int error,
  1403. brlapi_packetType_t type,
  1404. const void* packet,
  1405. size_t size);
  1406. /** @} */
  1407. /* Windows-specific tricks - don't look at this */
  1408. #ifdef BRLAPI_WIN32
  1409. #ifndef BRLAPI_NO_SINGLE_SESSION
  1410. int BRLAPI_STDCALL brlapi_writeTextWin(int cursor, const void* str, int wide);
  1411. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1412. int BRLAPI_STDCALL brlapi__writeTextWin(brlapi_handle_t* handle,
  1413. int cursor,
  1414. const void* str,
  1415. int wide);
  1416. #ifndef BRLAPI_NO_SINGLE_SESSION
  1417. int BRLAPI_STDCALL brlapi_writeWin(const brlapi_writeArguments_t* s, int wide);
  1418. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1419. int BRLAPI_STDCALL brlapi__writeWin(brlapi_handle_t* handle,
  1420. const brlapi_writeArguments_t* s,
  1421. int wide);
  1422. #ifdef UNICODE
  1423. #ifndef BRLAPI_NO_SINGLE_SESSION
  1424. #define brlapi_writeText(cursor, str) brlapi_writeTextWin(cursor, str, 1)
  1425. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1426. #define brlapi__writeText(handle, cursor, str) \
  1427. brlapi__writeTextWin(handle, cursor, str, 1)
  1428. #ifndef BRLAPI_NO_SINGLE_SESSION
  1429. #define brlapi_write(s) brlapi_writeWin(s, 1)
  1430. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1431. #define brlapi__write(handle, s) brlapi__writeWin(handle, s, 1)
  1432. #else /* UNICODE */
  1433. #ifndef BRLAPI_NO_SINGLE_SESSION
  1434. #define brlapi_writeText(cursor, str) brlapi_writeTextWin(cursor, str, 0)
  1435. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1436. #define brlapi__writeText(handle, cursor, str) \
  1437. brlapi__writeTextWin(handle, cursor, str, 0)
  1438. #ifndef BRLAPI_NO_SINGLE_SESSION
  1439. #define brlapi_write(s) brlapi_writeWin(s, 0)
  1440. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1441. #define brlapi__write(handle, s) brlapi__writeWin(handle, s, 0)
  1442. #endif /* UNICODE */
  1443. #endif /* BRLAPI_WIN32 */
  1444. #ifndef BRLAPI_NO_DEPRECATED
  1445. /** \defgroup brlapi_deprecated Deprecated names
  1446. *
  1447. * With version 0.5.0, BrlAPI is now provided through including <brlapi.h> and
  1448. * got a big renaming pass. Old names are still available through macros, but
  1449. * they are deprecated since they will get dropped in the next release. This
  1450. * documentation is for you to know the new names.
  1451. *
  1452. * For checking that you have completely switched to new names, just define
  1453. * BRLAPI_NO_DEPRECATED: that will disable compatibility macros.
  1454. *
  1455. * @{ */
  1456. #define brlapi_settings_t brlapi_connectionSettings_t
  1457. /** brlapi_writeStruct, replaced by brlapi_writeArguments_t */
  1458. typedef struct {
  1459. int displayNumber;
  1460. unsigned int regionBegin;
  1461. unsigned int regionSize;
  1462. char* text;
  1463. int textSize;
  1464. unsigned char* attrAnd;
  1465. unsigned char* attrOr;
  1466. int cursor;
  1467. char* charset;
  1468. } brlapi_writeStruct;
  1469. #define BRLAPI_WRITESTRUCT_INITIALIZER BRLAPI_WRITEARGUMENTS_INITIALIZER
  1470. #define brl_keycode_t brlapi_keyCode_t
  1471. #define brl_type_t brlapi_packetType_t
  1472. #define BRLCOMMANDS NULL
  1473. #define BRL_KEYCODE_MAX BRLAPI_KEY_MAX
  1474. #ifndef BRLAPI_NO_SINGLE_SESSION
  1475. #define brlapi_initializeConnection brlapi_openConnection
  1476. #define brlapi_getTty brlapi_enterTtyMode
  1477. #define brlapi_getTtyPath brlapi_enterTtyModeWithPath
  1478. #define brlapi_leaveTty brlapi_leaveTtyMode
  1479. #define brlapi_unignoreKeyRange brlapi_acceptKeyRange
  1480. #define brlapi_unignoreKeySet brlapi_acceptKeySet
  1481. #define brlapi_getRaw brlapi_enterRawMode
  1482. #define brlapi_leaveRaw brlapi_leaveRawMode
  1483. #define brlapi_suspend brlapi_suspendDriver
  1484. #define brlapi_resume brlapi_resumeDriver
  1485. #endif /* BRLAPI_NO_SINGLE_SESSION */
  1486. #define BRLERR_SUCCESS BRLAPI_ERROR_SUCCESS
  1487. #define BRLERR_NOMEM BRLAPI_ERROR_NOMEM
  1488. #define BRLERR_TTYBUSY BRLAPI_ERROR_TTYBUSY
  1489. #define BRLERR_DEVICEBUSY BRLAPI_ERROR_DEVICEBUSY
  1490. #define BRLERR_UNKNOWN_INSTRUCTION BRLAPI_ERROR_UNKNOWN_INSTRUCTION
  1491. #define BRLERR_ILLEGAL_INSTRUCTION BRLAPI_ERROR_ILLEGAL_INSTRUCTION
  1492. #define BRLERR_INVALID_PARAMETER BRLAPI_ERROR_INVALID_PARAMETER
  1493. #define BRLERR_INVALID_PACKET BRLAPI_ERROR_INVALID_PACKET
  1494. #define BRLERR_CONNREFUSED BRLAPI_ERROR_CONNREFUSED
  1495. #define BRLERR_OPNOTSUPP BRLAPI_ERROR_OPNOTSUPP
  1496. #define BRLERR_GAIERR BRLAPI_ERROR_GAIERR
  1497. #define BRLERR_LIBCERR BRLAPI_ERROR_LIBCERR
  1498. #define BRLERR_UNKNOWNTTY BRLAPI_ERROR_UNKNOWNTTY
  1499. #define BRLERR_PROTOCOL_VERSION BRLAPI_ERROR_PROTOCOL_VERSION
  1500. #define BRLERR_EOF BRLAPI_ERROR_EOF
  1501. #define BRLERR_EMPTYKEY BRLAPI_ERROR_EMPTYKEY
  1502. #define BRLERR_DRIVERERROR BRLAPI_ERROR_DRIVERERROR
  1503. /** @} */
  1504. #endif /* BRLAPI_NO_DEPRECATED */
  1505. #ifdef __cplusplus
  1506. }
  1507. #endif /* __cplusplus */
  1508. #endif /* BRLAPI_INCLUDED */