BASELINE: Update Chromium to 85.0.4183.14085-based

Change-Id: Iaa42f4680837c57725b1344f108c0196741f6057
Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>

1 files changed, 1647 insertions, 0 deletions

diff --git a/chromium/third_party/libbrlapi/brlapi.h b/chromium/third_party/libbrlapi/brlapi.h
new file mode 100644
index 00000000000..29b543f5a55
--- /dev/null
+++ b/chromium/third_party/libbrlapi/brlapi.h
@@ -0,0 +1,1647 @@
+/* Programs/brlapi.h.  Generated from brlapi.h.in by configure.  */
+/*
+ * libbrlapi - A library providing access to braille terminals for applications.
+ *
+ * Copyright (C) 2002-2020 by
+ *   Samuel Thibault <Samuel.Thibault@ens-lyon.org>
+ *   Sébastien Hinderer <Sebastien.Hinderer@ens-lyon.org>
+ *
+ * libbrlapi comes with ABSOLUTELY NO WARRANTY.
+ *
+ * This is free software, placed under the terms of the
+ * GNU Lesser General Public License, as published by the Free Software
+ * Foundation; either version 2.1 of the License, or (at your option) any
+ * later version. Please see the file LICENSE-LGPL for details.
+ *
+ * Web Page: http://brltty.app/
+ *
+ * This software is maintained by Dave Mielke <dave@mielke.cc>.
+ */
+
+/** \file
+ * \brief Types, defines and functions prototypes for \e BrlAPI's library
+ */
+
+#ifndef BRLAPI_INCLUDED
+#define BRLAPI_INCLUDED
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+/* #undef BRLAPI_WIN32 */
+
+/** \defgroup brlapi_version Version of the BrlAPI library
+ * @{ */
+
+/** Library version. */
+#define BRLAPI_RELEASE "0.8.0"
+
+/** Library major version. */
+#define BRLAPI_MAJOR 0
+
+/** Library minor version. */
+#define BRLAPI_MINOR 8
+
+/** Library revision. */
+#define BRLAPI_REVISION 0
+
+/** Returns the version of the library */
+void brlapi_getLibraryVersion(int* major, int* minor, int* revision);
+
+/** @} */
+
+/* Types are defined there */
+#include <sys/types.h>
+
+#ifdef BRLAPI_WIN32
+#include <windows.h>
+#define BRLAPI_STDCALL __stdcall
+#else /* BRLAPI_WIN32 */
+#define BRLAPI_STDCALL
+#endif /* BRLAPI_WIN32 */
+
+#ifdef _MSC_VER
+typedef __int64 uint64_t;
+typedef __int32 uint32_t;
+#define UINT64_C(x) (x##Ui64)
+#define PRIx64 "I64x"
+typedef signed int ssize_t;
+#else /* _MSC_VER */
+
+/* this is for uint*_t */
+#include <stdint.h>
+
+/* NULL is defined there */
+#include <unistd.h>
+
+#include <inttypes.h> /* For PRIx64 */
+#endif                /* _MSC_VER */
+
+#include <wchar.h>
+
+/** \defgroup brlapi_handles BrlAPI handles
+ *
+ * Each function provided by BrlAPI comes in two versions.
+ *
+ * 1. A version whose name is prefixed by brlapi_ for clients opening only
+ * one simultaneous connection with BrlAPI (most frequen case)
+ *
+ * 2. A version whose name is prefixed by brlapi__ for use by clients
+ * wishing to open more than one connection to BrlAPI.
+ *
+ * A function called brlapi__foo is used in exactly the same way as its
+ * brlapi_foo counterpart, except that it takes an additional argument
+ * (the first one), which is a handle letting the client refer to a given
+ * connection in a similar manner to what file descriptors do.
+ *
+ * In case you want to check that your code is not erroneously using brlapi_foo
+ * functions, define BRLAPI_NO_SINGLE_SESSION before including <brlapi.h>: that
+ * will disable the declaration of all single session functions.
+ *
+ * @{ */
+
+/** Type for BrlAPI hanles */
+typedef struct brlapi_handle_t brlapi_handle_t;
+
+/** Returns the size of an object of type brlapi_handle_t in bytes */
+size_t BRLAPI_STDCALL brlapi_getHandleSize(void);
+
+/** @} */
+
+/** \defgroup brlapi_connection Connecting to BrlAPI
+ *
+ * Before calling any other function of the library, calling
+ * brlapi_openConnection() is needed to establish a connection to
+ * \e BrlAPI 's server.
+ * When the connection is not needed any more, brlapi_closeConnection() must be
+ * called to close the connection.
+ *
+ * @{ */
+
+/** Default port number on which connections to \e BrlAPI can be established */
+#define BRLAPI_SOCKETPORTNUM 4101
+#define BRLAPI_SOCKETPORT "4101"
+
+/** Default unix path on which connections to \e BrlAPI can be established */
+#define BRLAPI_SOCKETPATH "/run/brltty/BrlAPI"
+
+/** \e brltty 's settings directory
+ *
+ * This is where authorization key and driver-dependent key names are found
+ * for instance. */
+#define BRLAPI_ETCDIR "/etc"
+
+/** Default name of the file containing \e BrlAPI 's authorization key
+ *
+ * This name is relative to BRLAPI_ETCDIR */
+#define BRLAPI_AUTHKEYFILE "brlapi.key"
+
+/** Default authorization setting */
+#ifdef BRLAPI_WIN32
+/* No authentication by default on Windows */
+#define BRLAPI_DEFAUTH "none"
+#else /* BRLAPI_WIN32 */
+#define BRLAPI_DEFAUTH_KEYFILE "keyfile:" BRLAPI_ETCDIR "/" BRLAPI_AUTHKEYFILE
+
+#ifdef USE_POLKIT
+#define BRLAPI_DEFAUTH_POLKIT "+polkit"
+#else /* USE_POLKIT */
+#define BRLAPI_DEFAUTH_POLKIT ""
+#endif /* USE_POLKIT */
+
+#define BRLAPI_DEFAUTH BRLAPI_DEFAUTH_KEYFILE BRLAPI_DEFAUTH_POLKIT
+#endif /* BRLAPI_WIN32 */
+
+#ifdef __MINGW32__
+typedef HANDLE brlapi_fileDescriptor;
+#else  /* __MINGW32__ */
+typedef int brlapi_fileDescriptor;
+#endif /* __MINGW32__ */
+
+/** \brief Settings structure for \e BrlAPI connection
+ *
+ * This structure holds every parameter needed to connect to \e BrlAPI: which
+ * file the authorization key can be found in and which computer to connect to.
+ *
+ * \par Examples:
+ * \code
+ * brlapi_connectionSettings_t settings;
+ *
+ * settings.auth="/etc/brlapi.key";
+ * settings.host="foo";
+ * \endcode
+ *
+ * \e libbrlapi will read authorization key from file \p /etc/brlapi.key
+ * and connect to the machine called "foo", on the default TCP port.
+ *
+ * \code
+ * settings.host="10.1.0.2";
+ * \endcode
+ *
+ * lets directly enter an IP address instead of a machine name.
+ *
+ * \code
+ * settings.host=":1";
+ * \endcode
+ *
+ * lets \e libbrlapi connect to the local computer, on port
+ * BRLAPI_SOCKETPORTNUM+1
+ *
+ * \sa brlapi_openConnection()
+ */
+typedef struct {
+  /** For security reasons, \e libbrlapi has to get authorized to connect to the
+   * \e BrlAPI server. This can be done via a secret key, for instance. This is
+   * the path to the file which holds it; it will hence have to be readable by
+   * the application.
+   *
+   * Setting \c NULL defaults it to local installation setup or to the content
+   * of the BRLAPI_AUTH environment variable, if it exists. */
+  const char* auth;
+
+  /** This tells where the \e BrlAPI server resides: it might be listening on
+   * another computer, on any TCP port. It should look like "foo:1", which
+   * means TCP port number BRLAPI_SOCKETPORTNUM+1 on computer called "foo".
+   * \note Please check that resolving this name works before complaining
+   *
+   * Settings \c NULL defaults it to localhost, using the local installation's
+   * default TCP port, or to the content of the BRLAPI_HOST environment
+   * variable, if it exists. */
+  const char* host;
+} brlapi_connectionSettings_t;
+
+/* BRLAPI_SETTINGS_INITIALIZER */
+/** Allows to initialize a structure of type \e brlapi_connectionSettings_t *
+ * with default values. */
+#define BRLAPI_SETTINGS_INITIALIZER \
+  { NULL, NULL }
+
+/* brlapi_openConnection */
+/** Open a socket and connect it to \e BrlAPI 's server
+ *
+ * This function first loads an authorization key as specified in settings.
+ * It then creates a TCP socket and connects it to the specified machine, on
+ * the specified port. It writes the authorization key on the socket and
+ * waits for acknowledgement.
+ *
+ * \return the file descriptor, or -1 on error
+ *
+ * \note The file descriptor is returned in case the client wants to
+ * communicate with the server without using \e libbrlapi functions. If it uses
+ * them however, it won't have to pass the file descriptor later, since the
+ * library keeps a copy of it. But that also means that
+ * brlapi_openConnection() may be called several times, but \e libbrlapi
+ * functions will always work with the last call's descriptor
+ *
+ * \par Example:
+ * \code
+ * if (brlapi_openConnection(&settings,&settings)<0) {
+ *  fprintf(stderr,"couldn't connect to BrlAPI at %s: %s\n",
+ *   settings.host, brlapi_strerror(&brlapi_error));
+ *  exit(1);
+ * }
+ * \endcode
+ *
+ * \par Errors:
+ * \e BrlAPI might not be on this TCP port, the host name might not be
+ * resolvable, the authorization may fail,...
+ *
+ * \param desiredSettings this gives the desired connection parameters, as
+ * described in brlapi_connectionSettings_t. If \c NULL, defaults values are
+ * used, so that it is generally a good idea to give \c NULL as default, and
+ * only fill a brlapi_connectionSettings_t structure when the user gave
+ * parameters to the program for instance; \param actualSettings if not \c NULL,
+ * parameters which were actually used are stored here, if the application ever
+ * needs them.
+ *
+ * \sa
+ * brlapi_connectionSettings_t
+ * brlapi_writePacket()
+ * brlapi_readPacketHeader()
+ * brlapi_readPacketContent()
+ * brlapi_readPacket()
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+brlapi_fileDescriptor BRLAPI_STDCALL
+brlapi_openConnection(const brlapi_connectionSettings_t* desiredSettings,
+                      brlapi_connectionSettings_t* actualSettings);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+brlapi_fileDescriptor BRLAPI_STDCALL
+brlapi__openConnection(brlapi_handle_t* handle,
+                       const brlapi_connectionSettings_t* desiredSettings,
+                       brlapi_connectionSettings_t* actualSettings);
+
+/* brlapi_closeConnection */
+/** Cleanly close the socket
+ *
+ * This function locks until a closing acknowledgement is received from the
+ * server. The socket is then freed, so the file descriptor
+ * brlapi_openConnection() gave has no meaning any more
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+void BRLAPI_STDCALL brlapi_closeConnection(void);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+void BRLAPI_STDCALL brlapi__closeConnection(brlapi_handle_t* handle);
+
+/** @} */
+
+/** \defgroup brlapi_clientData Setting and getting client data
+ *
+ * Clients can register a pointer to data that can then be used
+ * e.g. in exception handlers.
+ * @{ */
+
+/* brlapi__setClientData */
+/** Register a pointer to client data
+ *
+ * \param data The pointer to the private client data
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+void BRLAPI_STDCALL brlapi_setClientData(void* data);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+void BRLAPI_STDCALL brlapi__setClientData(brlapi_handle_t* handle, void* data);
+
+/* brlapi__getClientData */
+/** Retrieves the pointer to the private client data
+ *
+ * \return the pointer to the private client data
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+void* BRLAPI_STDCALL brlapi_getClientData(void);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+void* BRLAPI_STDCALL brlapi__getClientData(brlapi_handle_t* handle);
+
+/** @} */
+
+/** \defgroup brlapi_info Getting Terminal information
+ * \brief How to get information about the connected Terminal
+ *
+ * Before using Raw mode or key codes, the application should always check the
+ * type of the connected terminal, to be sure it is really the one it expects.
+ *
+ * One should also check for display size, so as to adjust further displaying
+ * on it.
+ * @{
+ */
+
+/** Maximum name length for names embeded in BrlAPI packets, not counting any
+ * termination \\0 character */
+#define BRLAPI_MAXNAMELENGTH 31
+
+/* brlapi_getDriverName */
+/** Return the complete name of the driver used by \e brltty
+ *
+ * This function fills its argument with the whole name of the braille
+ * driver if available, terminated with a '\\0'.
+ *
+ * \param buffer is the buffer provided by the application;
+ * \param size is the maximum size for the name buffer.
+ *
+ * \return -1 on error, otherwise a positive value giving the size of the needed
+ * buffer (including '\\0'). If that value is bigger than \p size, the value was
+ * truncated and the caller should retry with a bigger buffer accordingly.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_getDriverName(char* buffer, size_t size);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__getDriverName(brlapi_handle_t* handle,
+                                         char* buffer,
+                                         size_t size);
+
+/* brlapi_getModelIdentifier */
+/** Return an identifier for the device model used by \e brltty
+ *
+ * This function fills its argument with the whole identifier of the braille
+ * device model if available, terminated with a '\\0'.
+ *
+ * \param buffer is the buffer given by the application;
+ * \param size is the maximum size for the identifier buffer.
+ *
+ * \return -1 on error, otherwise a positive value giving the size of the needed
+ * buffer (including '\\0'). If that value is bigger than \p size, the value was
+ * truncated and the caller should retry with a bigger buffer accordingly.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_getModelIdentifier(char* buffer, size_t size);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__getModelIdentifier(brlapi_handle_t* handle,
+                                              char* buffer,
+                                              size_t size);
+
+/* brlapi_getDisplaySize */
+/** Return the size of the braille display */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_getDisplaySize(unsigned int* x, unsigned int* y);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__getDisplaySize(brlapi_handle_t* handle,
+                                          unsigned int* x,
+                                          unsigned int* y);
+
+/** @} */
+
+/** \defgroup brlapi_tty Entering & leaving tty mode
+ * \brief How to take control of ttys for direct braille display / read
+ *
+ * Before being able to write on the braille display, the application must tell
+ * the server which tty it will handle.
+ *
+ * The application must also specify how braille keys will be delivered to it.
+ * Two ways are possible: key codes and commands:
+ *
+ * - key codes are specific to each braille driver, since the raw key code, as
+ *   defined in the driver will be given for each key press.
+ *   Using them leads to building highly driver-dependent applications, which
+ *   can yet sometimes be useful to mimic existing proprietary applications
+ *   for instance.
+ * - commands means that applications will get exactly the same values as
+ *   \e brltty. This allows driver-independent clients, which will hopefully
+ *   be nice to use with a lot of different terminals.
+ * \sa brlapi_readKey()
+ * @{
+ */
+
+/* brlapi_enterTtyMode */
+/** Ask for some tty, with some key mechanism
+ *
+ * \param tty
+ * - If tty>=0 then take control of the specified tty.
+ * - If tty==::BRLAPI_TTY_DEFAULT then take control of the default tty.
+ *
+ * \param driver tells how the application wants brlapi_readKey() to return
+ * key presses. NULL or "" means BRLTTY commands are required,
+ * whereas a driver name means that raw key codes returned by this
+ * driver are expected.
+ *
+ * WINDOWPATH and WINDOWID should be propagated when running remote applications
+ * via ssh, for instance, along with BRLAPI_HOST and the authorization key (see
+ * SendEnv in ssh_config(5) and AcceptEnv in sshd_config(5))
+ *
+ * \return the used tty number on success, -1 on error
+ *
+ * \sa brlapi_leaveTtyMode() brlapi_readKey()
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_enterTtyMode(int tty, const char* driver);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__enterTtyMode(brlapi_handle_t* handle,
+                                        int tty,
+                                        const char* driver);
+
+/** Select the default tty.
+ *
+ * The library takes the following steps:
+ * -# Try to get the tty number from the \c WINDOWID environment variable (for
+ * the \c xterm case).
+ * -# Try to get the tty number from the \c CONTROLVT environment variable.
+ * -# Read \c /proc/self/stat (on \c Linux).
+ *
+ * \sa brlapi_enterTtyMode()
+ */
+#define BRLAPI_TTY_DEFAULT -1
+
+/* brlapi_enterTtyModeWithPath */
+/** Ask for some tty specified by its path in the tty tree, with some key
+ * mechanism
+ *
+ * \param ttys points on the array of ttys representing the tty path to be got.
+ * Can be NULL if nttys is 0.
+ * \param count gives the number of elements in ttys.
+ * \param driver has the same meaning as in brlapi_enterTtyMode()
+ *
+ * Providing nttys == 0 means to get the root.
+ *
+ * \sa brlapi_enterTtyMode()
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_enterTtyModeWithPath(int* ttys,
+                                               int count,
+                                               const char* driver);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__enterTtyModeWithPath(brlapi_handle_t* handle,
+                                                int* ttys,
+                                                int count,
+                                                const char* driver);
+
+/* brlapi_leaveTtyMode */
+/** Stop controlling the tty
+ *
+ * \return 0 on success, -1 on error.
+ *
+ * \sa brlapi_enterTtyMode()
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_leaveTtyMode(void);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__leaveTtyMode(brlapi_handle_t* handle);
+
+/* brlapi_setFocus */
+/** Tell the current tty to brltty
+ *
+ * This is intended for focus tellers, such as brltty, xbrlapi, screen, ...
+ * brlapi_enterTtyMode() must have been called beforehand to tell where this
+ * focus applies in the tty tree.
+ *
+ * \return 0 on success, -1 on error.
+ *
+ * \sa brlapi_enterTtyMode() brlapi_leaveTtyMode()
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_setFocus(int tty);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__setFocus(brlapi_handle_t* handle, int tty);
+
+/** @} */
+
+/** \defgroup brlapi_write Writing on the braille display
+ * \brief Write text to the braille display
+ *
+ * After brlapi_enterTtyMode() has been called, the application can
+ * call one of these functions to write things on the braille display.
+ *
+ * \note Be sure to call brlapi_enterTtyMode() \e before calling brlapi_write(),
+ * or else you'll get an error. This is particularly not always trivial when
+ * writing multithreaded applications.
+ *
+ * \note Dots are coded as described in ISO/TR 11548-1: a dot pattern is coded
+ * by a byte in which bit 0 is set iff dot 1 is up, bit 1 is set iff dot 2 is
+ * up, ... bit 7 is set iff dot 8 is up. This also corresponds to the low-order
+ * byte of the coding of unicode's braille row U+2800.
+ *
+ * \note Text is translated by the server one to one, by just using a simple
+ * wchar_t to pattern table, i.e. no contraction/expansion is performed, because
+ * the client would then have no way to know how wide the output would be and
+ * thus the quantity of text to feed.  If contraction/expansion is desired, the
+ * client should perform it itself (e.g. thanks to liblouis or gnome-braille)
+ * and send the resulting dot patterns.  This is actually exactly the same
+ * problem as font rendering on a graphical display: for better control,
+ * nowadays all font rasterization is performed on the client side, and mere
+ * pixmaps are sent to the X server.
+ *
+ * @{ */
+
+/* brlapi_writeText */
+/** Write the given \\0-terminated string to the braille display
+ *
+ * If the string is too long, it is truncated. If it's too short,
+ * it is padded with spaces. The text is assumed to be in the current
+ * locale charset set by setlocale(3) if it was called, or the locale charset
+ * from the locale environment variables if setlocale(3) was not called.
+ *
+ * \param cursor gives the cursor position; if equal to ::BRLAPI_CURSOR_OFF, no
+ * cursor is shown at all; if cursor==::BRLAPI_CURSOR_LEAVE, the cursor is left
+ * where it is
+ *
+ * \param text points to the string to be displayed.
+ *
+ * \return 0 on success, -1 on error.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_writeText(int cursor, const char* text);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__writeText(brlapi_handle_t* handle,
+                                     int cursor,
+                                     const char* text);
+
+/* brlapi_writeWText */
+/** Write the given \\0-terminated unicode string to the braille display
+ *
+ * If the string is too long, it is truncated. If it's too short,
+ * it is padded with spaces.
+ *
+ * \param cursor gives the cursor position; if equal to ::BRLAPI_CURSOR_OFF, no
+ * cursor is shown at all; if cursor==::BRLAPI_CURSOR_LEAVE, the cursor is left
+ * where it is
+ *
+ * \param text points to the string to be displayed.
+ *
+ * \return 0 on success, -1 on error.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_writeWText(int cursor, const wchar_t* text);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__writeWText(brlapi_handle_t* handle,
+                                      int cursor,
+                                      const wchar_t* text);
+
+/* brlapi_writeDots */
+/** Write the given dots array to the display
+ *
+ * \param dots points on an array of dot information, one per character. Its
+ * size must hence be the same as what brlapi_getDisplaySize() returns.
+ *
+ * \return 0 on success, -1 on error.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_writeDots(const unsigned char* dots);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__writeDots(brlapi_handle_t* handle,
+                                     const unsigned char* dots);
+
+/* brlapi_writeArguments_t */
+/** Structure containing arguments to be given to brlapi_write() */
+typedef struct {
+  int displayNumber /** Display number ::BRLAPI_DISPLAY_DEFAULT == unspecified
+                     */
+      ;
+  unsigned int regionBegin /** Region of display to update, 1st character of
+                              display is 1 */
+      ;
+  unsigned int
+      regionSize /** Number of characters held in text, andMask and orMask. */;
+  char* text /** Text to display, must hold as many characters as the region
+                fields expresses. */
+      ;
+  int textSize /** Size of text in bytes. If -1, strlen() is used for computing
+                  it. */
+      ;
+  unsigned char* andMask /** And attributes; applied first */;
+  unsigned char* orMask /** Or attributes; applied \e after ANDing */;
+  int cursor /** ::BRLAPI_CURSOR_LEAVE == don't touch, ::BRLAPI_CURSOR_OFF ==
+                turn off, 1 = 1st char of display, ... */
+      ;
+  char* charset /** Text charset. NULL means it is assumed to be 8bits, and the
+                   same as the server's. "" means current locale's charset. If
+                   no locale was selected, defaults to NULL's meaning. */
+      ;
+} brlapi_writeArguments_t;
+
+/** Write to the default display on the braille device.
+ *
+ * \sa brlapi_write() brlapi_writeArguments_t
+ */
+#define BRLAPI_DISPLAY_DEFAULT -1
+
+/** Do not change the cursor's state or position.
+ *
+ * \sa brlapi_writeText() brlapi_write() brlapi_writeArguments_t
+ */
+#define BRLAPI_CURSOR_LEAVE -1
+
+/** Do not display the cursor.
+ *
+ * \sa brlapi_writeText() brlapi_write() brlapi_writeArguments_t
+ */
+#define BRLAPI_CURSOR_OFF 0
+
+/* BRLAPI_WRITEARGUMENTS_INITIALIZER */
+/** Allows to initialize a structure of type \e brlapi_writeArguments_t *
+ * with default values:
+ * displayNumber = ::BRLAPI_DISPLAY_DEFAULT; (unspecified)
+ * regionBegin = regionSize = 0; (update the whole display, DEPRECATED and will
+ * be forbidden in next release. You must always express the region you wish to
+ * update)
+ * text = andMask = orMask = NULL; (no text, no attribute)
+ * cursor = ::BRLAPI_CURSOR_LEAVE; (don't touch cursor)
+ */
+#define BRLAPI_WRITEARGUMENTS_INITIALIZER                           \
+  {                                                                 \
+    .displayNumber = BRLAPI_DISPLAY_DEFAULT, .regionBegin = 0,      \
+    .regionSize = 0, .text = NULL, .textSize = -1, .andMask = NULL, \
+    .orMask = NULL, .cursor = BRLAPI_CURSOR_LEAVE, .charset = NULL  \
+  }
+
+/* brlapi_write */
+/** Update a specific region of the braille display and apply and/or masks
+ *
+ * \param arguments gives information necessary for the update
+ *
+ * regionBegin and regionSize must be filled for specifying which part of the
+ * display will be updated, as well as the size (in characters, not bytes) of
+ * the text, andMask and orMask members.
+ *
+ * If given, the "text" field holds the text that will be displayed in the
+ * region.  The char string must hold exactly as many characters as the region
+ * fields express.  For multibyte text, this is the number of \e multibyte
+ * caracters.  Notably, combining and double-width caracters count for 1.
+ *
+ * The actual length of the text in \e bytes may be specified thanks to
+ * textSize.  If -1 is given, it will be computed thanks to strlen(), so "text"
+ * must then be a NUL-terminated string.
+ *
+ * The "andMask" and "orMask" masks, if present, are then applied on top of
+ * the text, one byte per character.  This hence permits the superimposing of
+ * attributes over the text.  For instance, setting an andMask mask full of
+ * BRLAPI_DOTS(1,1,1,1,1,1,0,0) will only keep (logical AND) dots 1-6,
+ * hence dropping dots 7 and 8.  On the contrary, setting an orMask full of
+ * BRLAPI_DOT7|BRLAPI_DOT8 will add (logical OR) dots 7 and 8.
+ *
+ * The "charset" field, if present, specifies the charset of the "text" field.
+ * If it is "", the current locale's charset (if any) is assumed.  Else, the
+ * 8-bit charset of the server is assumed.
+ *
+ * A special invocation is with an unmodified initialized structure: this clears
+ * the client's whole display, letting the display of other applications on
+ * the same tty or of applications "under" the tty appear. See Concurrency
+ * management section of the BrlAPI documentation for more details.
+ *
+ * \return 0 on success, -1 on error.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_write(const brlapi_writeArguments_t* arguments);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__write(brlapi_handle_t* handle,
+                                 const brlapi_writeArguments_t* arguments);
+
+/** @} */
+
+#include "brlapi_keycodes.h"
+
+/** \defgroup brlapi_keys Reading key presses
+ * \brief How to read key presses from the braille terminal
+ *
+ * Once brlapi_enterTtyMode() has been called, the application can call
+ * brlapi_readKey() to read key presses. Either key codes (see \ref
+ * brlapi_keycodes) or commands will be returned, depending on parameters given
+ * to brlapi_enterTtyMode().
+ *
+ * Key presses are buffered, so that calling brlapi_readKey() in non-blocking
+ * mode from time to time should suffice.
+ *
+ * @{
+ */
+
+/* brlapi_expandedKeyCode_t */
+/** Structure holding the components of a key code as returned by
+ * brlapi_expandKeyCode() */
+typedef struct {
+  unsigned int type /** the type value */;
+  unsigned int command /** the command value */;
+  unsigned int argument /** the argument value */;
+  unsigned int flags /** the flags value */;
+} brlapi_expandedKeyCode_t;
+
+/* brlapi_expandKeyCode */
+/** Expand the components of a key code
+ *
+ * \param code the key code to be expanded
+ * \param expansion pointer to the structure that receives the components
+ *
+ * \return 0 on success, -1 on error
+ */
+int BRLAPI_STDCALL brlapi_expandKeyCode(brlapi_keyCode_t code,
+                                        brlapi_expandedKeyCode_t* expansion);
+
+/* brlapi_describedKeyCode_t */
+/** Structure holding the components of a key code as returned by
+ * brlapi_describeKeyCode() */
+typedef struct {
+  const char* type /** the  type name */;
+  const char* command /** the command name */;
+  unsigned int argument /** the argument value */;
+  unsigned int flags /** the flag count */;
+  const char* flag[64 - BRLAPI_KEY_FLAGS_SHIFT] /** the flag names */;
+  brlapi_expandedKeyCode_t values /** the actual values of the components */;
+} brlapi_describedKeyCode_t;
+
+/* brlapi_describeKeyCode */
+/** Describe the components of a key code.
+ *
+ * \param code the keycode to be described
+ * \param description pointer to the structure that receives the description
+ *
+ * \return 0 on success, -1 on error
+ */
+int BRLAPI_STDCALL
+brlapi_describeKeyCode(brlapi_keyCode_t code,
+                       brlapi_describedKeyCode_t* description);
+
+/** Unicode braille row */
+#define BRLAPI_UC_ROW 0x2800UL
+
+/* brlapi_readKey */
+/** Read a key from the braille keyboard
+ *
+ * This function returns one key press's code.
+ *
+ * If NULL or "" was given to brlapi_enterTtyMode(), a \e brltty command is
+ * returned, as described in the documentation for ::brlapi_keyCode_t . It is
+ * hence pretty driver-independent, and should be used by default when no other
+ * option is possible.
+ *
+ * By default, all commands but those which restart drivers and switch
+ * virtual terminals are returned to the application and not to brltty.
+ * If the application doesn't want to see some command events,
+ * it should call brlapi_ignoreKeys()
+ *
+ * If some driver name was given to brlapi_enterTtyMode(), a raw keycode is
+ * returned, as specified by the terminal driver, usually in <brltty/brldefs-xy>
+ * where xy is the driver's code. It generally corresponds to the very code that
+ * the terminal tells to the driver. This should only be used by applications
+ * which are dedicated to a particular braille terminal. Hence, checking the
+ * terminal type thanks to a call to brlapi_getDriverName() before getting tty
+ * control is a pretty good idea.
+ *
+ * By default, all the keypresses will be passed to the client, none will go
+ * through brltty, so the application will have to handle console switching
+ * itself for instance.
+ *
+ * \param wait tells whether the call should block until a key is pressed (1)
+ *  or should only probe key presses (0);
+ * \param code holds the key code if a key press is indeed read.
+ *
+ * \return -1 on error or signal interrupt and *code is then undefined, 0 if
+ * block was 0 and no key was pressed so far, or 1 and *code holds the key code.
+ *
+ * Programming hints:
+ *
+ * If your application is only driven by braille command keypresses, you can
+ * just call brlapi_readKey(1, &code) so that it keeps blocking, waiting for
+ * keypresses.
+ *
+ * Else, you'll probably want to use the file descriptor returned by
+ * brlapi_openConnection() in your "big polling loop". For instance:
+ *
+ * - in a \c select() loop, just add it to the \c readfds and \c exceptfds file
+ *   descriptor sets;
+ * - in a gtk or atspi application, use
+ *   \c g_io_add_watch(fileDescriptor, \c G_IO_IN|G_IO_ERR|G_IO_HUP, \c f, \c
+ * data) for adding a callback called \c f;
+ * - in an Xt/Xaw/motif-based application, use
+ *   \c XtAppAddInput(app_context, \c fileDescriptor, \c
+ * XtInputReadMask|XtInputExceptMask, \c f, \c data)
+ * - etc.
+ *
+ * and then, when you detect inbound trafic on the file descriptor, do something
+ * like this:
+ *
+ * while (brlapi_readKey(0, &code) {
+ *    // process keycode code
+ *    // ...
+ * }
+ *
+ * The \c while loop is needed for processing \e all pending key presses, else
+ * some of them may be left in libbrlapi's internal key buffer and you wouldn't
+ * get them immediately.
+ *
+ * \note If the read is interrupted by a signal, brlapi_readKey() will return
+ * -1, brlapi_errno will be BRLAPI_ERROR_LIBCERR and errno will be EINTR.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_readKey(int wait, brlapi_keyCode_t* code);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__readKey(brlapi_handle_t* handle,
+                                   int wait,
+                                   brlapi_keyCode_t* code);
+
+/* brlapi_readKeyWithTimeout */
+/** Read a key from the braille keyboard, unless a timeout expires
+ *
+ * This function works like brlapi_readKey, except that parameter \e wait is
+ * replaced by a \e timeout_ms parameter
+ *
+ * \param timeout_ms specifies how long the function should wait for a keypress.
+ * \param code holds the key code if a key press is indeed read.
+ *
+ * \return -1 on error or signal interrupt and *code is then undefined, 0 if
+ * the timeout expired and no key was pressed, or 1 and *code holds the key
+ * code.
+ *
+ * If the timeout expires without any key being pressed, 0 is returned.
+ *
+ * If timeout_ms is set to 0, this function looks for key events that have been
+ * already received, but does not wait at all if no event was received.
+ *
+ * If timeout_ms is set to a negative value, this function behaves like
+ * brlapi_readKey, i.e. it uses an infinite timeout.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_readKeyWithTimeout(int timeout_ms,
+                                             brlapi_keyCode_t* code);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__readKeyWithTimeout(brlapi_handle_t* handle,
+                                              int timeout_ms,
+                                              brlapi_keyCode_t* code);
+
+/** types of key ranges */
+typedef enum {
+  brlapi_rangeType_all,     /**< all keys, code must be 0 */
+  brlapi_rangeType_type,    /**< all keys of a given type */
+  brlapi_rangeType_command, /**< all keys of a given command block, i.e.
+                               matching the key type and command parts */
+  brlapi_rangeType_key,     /**< a given key with any flags */
+  brlapi_rangeType_code,    /**< a given key code */
+} brlapi_rangeType_t;
+
+/* brlapi_ignoreKeys */
+/** Ignore some key presses from the braille keyboard
+ *
+ * This function asks the server to give the provided keys to \e brltty, rather
+ * than returning them to the application via brlapi_readKey().
+ *
+ * \param type type of keys to be ignored
+ * \param keys array of keys to be ignored
+ * \param count number of keys
+ *
+ * \note The given codes should be \e brltty commands (NULL or "" was given to
+ * brlapi_enterTtyMode())
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_ignoreKeys(brlapi_rangeType_t type,
+                                     const brlapi_keyCode_t keys[],
+                                     unsigned int count);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__ignoreKeys(brlapi_handle_t* handle,
+                                      brlapi_rangeType_t type,
+                                      const brlapi_keyCode_t keys[],
+                                      unsigned int count);
+
+/* brlapi_acceptKeys */
+/** Accept some key presses from the braille keyboard
+ *
+ * This function asks the server to give the provided keys to the application,
+ * and not give them to \e brltty.
+ *
+ * \param type type of keys to be ignored
+ * \param keys array of keys to be ignored
+ * \param count number of keys
+ *
+ * \note The given codes should be \e brltty commands (NULL or "" was given to
+ * brlapi_enterTtyMode())
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_acceptKeys(brlapi_rangeType_t type,
+                                     const brlapi_keyCode_t keys[],
+                                     unsigned int count);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__acceptKeys(brlapi_handle_t* handle,
+                                      brlapi_rangeType_t type,
+                                      const brlapi_keyCode_t keys[],
+                                      unsigned int count);
+
+/* brlapi_ignoreAllKeys */
+/** Ignore all key presses from the braille keyboard
+ *
+ * This function asks the server to give all keys to \e brltty, rather than
+ * returning them to the application via brlapi_readKey().
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_ignoreAllKeys(void);
+#define brlapi_ignoreAllKeys() brlapi_ignoreKeys(brlapi_rangeType_all, NULL, 0)
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__ignoreAllKeys(brlapi_handle_t* handle);
+#define brlapi__ignoreAllKeys(handle) \
+  brlapi__ignoreKeys(handle, brlapi_rangeType_all, NULL, 0)
+
+/* brlapi_acceptAllKeys */
+/** Accept all key presses from the braille keyboard
+ *
+ * This function asks the server to give all keys to the application, and not
+ * give them to \e brltty.
+ *
+ * Warning: after calling this function, make sure to call brlapi_ignoreKeys()
+ * for ignoring important keys like BRL_CMD_SWITCHVT_PREV/NEXT and such.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_acceptAllKeys(void);
+#define brlapi_acceptAllKeys() brlapi_acceptKeys(brlapi_rangeType_all, NULL, 0)
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__acceptAllKeys(brlapi_handle_t* handle);
+#define brlapi__acceptAllKeys(handle) \
+  brlapi__acceptKeys(handle, brlapi_rangeType_all, NULL, 0)
+
+/** Type for raw keycode ranges
+ *
+ * Denotes the set of keycodes between \e first and \e last (inclusive)
+ */
+typedef struct {
+  brlapi_keyCode_t first; /**< first key of the range */
+  brlapi_keyCode_t last;  /**< last key of the range */
+} brlapi_range_t;
+
+/* brlapi_ignoreKeyRanges */
+/** Ignore some key presses from the braille keyboard
+ *
+ * This function asks the server to give the provided key ranges to \e brltty,
+ * rather than returning them to the application via brlapi_readKey().
+ *
+ * \param ranges key ranges, which are inclusive
+ * \param count number of ranges
+ *
+ * \note The given codes should be raw keycodes (i.e. some driver name was given
+ * to brlapi_enterTtyMode()) */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_ignoreKeyRanges(const brlapi_range_t ranges[],
+                                          unsigned int count);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__ignoreKeyRanges(brlapi_handle_t* handle,
+                                           const brlapi_range_t ranges[],
+                                           unsigned int count);
+
+/* brlapi_acceptKeyRanges */
+/** Accept some key presses from the braille keyboard
+ *
+ * This function asks the server to return the provided key ranges (inclusive)
+ * to the application, and not give them to \e brltty.
+ *
+ * \param ranges key ranges, which are inclusive
+ * \param count number of ranges
+ *
+ * \note The given codes should be raw keycodes (i.e. some driver name was given
+ * to brlapi_enterTtyMode()) */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_acceptKeyRanges(const brlapi_range_t ranges[],
+                                          unsigned int count);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__acceptKeyRanges(brlapi_handle_t* handle,
+                                           const brlapi_range_t ranges[],
+                                           unsigned int count);
+/** @} */
+
+/** \defgroup brlapi_driverspecific Driver-Specific modes
+ * \brief Raw and Suspend Modes mechanism
+ *
+ * If the application wants to directly talk to the braille terminal, it should
+ * use Raw Mode. In this special mode, the driver gives the whole control of the
+ * terminal to it: \e brltty doesn't work any more.
+ *
+ * For this, it simply has to call brlapi_enterRawMode(), then brlapi_sendRaw()
+ * and brlapi_recvRaw(), and finally give control back thanks to
+ * brlapi_leaveRawMode().
+ *
+ * Special care of the terminal should be taken, since one might completely
+ * trash the terminal's data, or even lock it! The application should always
+ * check for terminal's type thanks to brlapi_getDriverName().
+ *
+ * The client can also make brltty close the driver by using
+ * brlapi_suspendDriver(), and resume it again with brlapi_resumeDriver().  This
+ * should not be used if possible: raw mode should be sufficient for any use. If
+ * not, please ask for features :)
+ *
+ * @{
+ */
+
+/* brlapi_enterRawMode */
+/** Switch to Raw mode
+ * \param driver Specifies the name of the driver for which the raw
+ * communication will be established.
+ * \return 0 on success, -1 on error */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_enterRawMode(const char* driver);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__enterRawMode(brlapi_handle_t* handle,
+                                        const char* driver);
+
+/* brlapi_leaveRawMode */
+/** Leave Raw mode
+ * \return 0 on success, -1 on error */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_leaveRawMode(void);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__leaveRawMode(brlapi_handle_t* handle);
+
+/* brlapi_sendRaw */
+/** Send Raw data
+ *
+ * \param buffer points on the data;
+ * \param size holds the packet size.
+ * \return size on success, -1 on error */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+ssize_t BRLAPI_STDCALL brlapi_sendRaw(const void* buffer, size_t size);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+ssize_t BRLAPI_STDCALL brlapi__sendRaw(brlapi_handle_t* handle,
+                                       const void* buffer,
+                                       size_t size);
+
+/* brlapi_recvRaw */
+/** Get Raw data
+ *
+ * \param buffer points on a buffer where the function will store the received
+ * data;
+ * \param size holds the buffer size.
+ * \return its size, -1 on error or signal interruption */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+ssize_t BRLAPI_STDCALL brlapi_recvRaw(void* buffer, size_t size);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+ssize_t BRLAPI_STDCALL brlapi__recvRaw(brlapi_handle_t* handle,
+                                       void* buffer,
+                                       size_t size);
+
+/* brlapi_suspendDriver */
+/** Suspend braille driver
+ * \param driver Specifies the name of the driver which will be suspended.
+ * \return -1 on error
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_suspendDriver(const char* driver);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__suspendDriver(brlapi_handle_t* handle,
+                                         const char* driver);
+
+/* brlapi_resumeDriver */
+/** Resume braille driver
+ * \return -1 on error
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_resumeDriver(void);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__resumeDriver(brlapi_handle_t* handle);
+/** @} */
+
+#include "brlapi_param.h"
+
+/** \defgroup brlapi_parameterManagement Parameter management
+ * \brief How to manage BrlAPI parameters
+ *
+ * There are several kinds of parameters:
+ * - states associated with the braille device itself, such as its size or
+ * parameters of the device port
+ * - states of the BrlAPI connection itself, such as the displaying level or
+ * key passing preferences.
+ * - general states such as the cut buffer,
+ * - braille parameters: braille table, contraction, cursor shape, etc,
+ * - browse parameters: line skip, beep, etc.
+ *
+ * Some of them are subdivided in subparameters.  Others have only subparameter
+ * 0.
+ *
+ * Some of them are read-only, others are read/write.
+ *
+ * A client can either request the immediate content of a parameter by
+ * using brlapi_getParameter(); set the content of a parameter by using
+ * brlapi_setParameter(); or register a callback that may be called immediately
+ * and on each change of a given parameter, by using brlapi_watchParameter().
+ *
+ * @{ */
+
+/** Flags for parameter requests */
+typedef uint32_t brlapi_param_flags_t;
+#define BRLAPI_PARAMF_LOCAL                                                  \
+  0X00 /**< Refer to the value local to the connection instead of the global \
+          value */
+#define BRLAPI_PARAMF_GLOBAL                                            \
+  0X01 /**< Refer to the global value instead of the value local to the \
+          connection */
+#define BRLAPI_PARAMF_SELF \
+  0X02 /**< Specify whether to receive notifications of value self-changes */
+
+/* brlapi_getParameter */
+/** Get the content of a parameter
+ *
+ * brlapi_getParameter gets the current content of a parameter
+ *
+ * \param parameter is the parameter whose content shall be gotten;
+ * \param subparam is a specific instance of the parameter;
+ * \param flags specify which value and how it should be returned;
+ * \param data is a buffer where content of the parameter shall be stored;
+ * \param len is the size of the buffer.
+ *
+ * \return the real size of the parameter's content. If the parameter does not
+ * fit in the provided buffer, it is truncated to len bytes (but the real size
+ * of the parameter is still returned). In that case, the client must call
+ * brlapi_getParameter again with a big enough buffer.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+ssize_t BRLAPI_STDCALL brlapi_getParameter(brlapi_param_t parameter,
+                                           brlapi_param_subparam_t subparam,
+                                           brlapi_param_flags_t flags,
+                                           void* data,
+                                           size_t len);
+#endif
+ssize_t BRLAPI_STDCALL brlapi__getParameter(brlapi_handle_t* handle,
+                                            brlapi_param_t parameter,
+                                            brlapi_param_subparam_t subparam,
+                                            brlapi_param_flags_t flags,
+                                            void* data,
+                                            size_t len);
+
+/* brlapi_getParameterAlloc */
+/** Return the content of a parameter
+ *
+ * brlapi_getParameterAlloc gets the current content of a parameter, by
+ * returning it as a newly-allocated buffer. The buffer is allocated to one byte
+ * more than the parameter value. This byte is set to zero. This allows, for
+ * string parameters, to be able to immediately use it as a C string.
+ *
+ * \param parameter is the parameter whose content shall be gotten;
+ * \param subparam is a specific instance of the parameter;
+ * \param flags specify which value and how it should be returned;
+ * \param len is the address where to store the size of the parameter value.
+ *
+ * \return a newly-allocated buffer that contains the value of the parameter.
+ * The caller must call free() on it after use. NULL is returned on errors
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+void* BRLAPI_STDCALL brlapi_getParameterAlloc(brlapi_param_t parameter,
+                                              brlapi_param_subparam_t subparam,
+                                              brlapi_param_flags_t flags,
+                                              size_t* len);
+#endif
+void* BRLAPI_STDCALL brlapi__getParameterAlloc(brlapi_handle_t* handle,
+                                               brlapi_param_t parameter,
+                                               brlapi_param_subparam_t subparam,
+                                               brlapi_param_flags_t flags,
+                                               size_t* len);
+
+/* brlapi_setParameter */
+/** Set the content of a parameter
+ *
+ * brlapi_setParameter sets the content of a parameter
+ *
+ * \param parameter is the parameter to set;
+ * \param subparam is a specific instance of the parameter;
+ * \param flags specify which value and how it should be set;
+ * \param data is a buffer containing the data to store in the parameter;
+ * \param len is the size of the data.
+ *
+ * \return 0 on success, -1 on error (read-only parameter for instance).
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_setParameter(brlapi_param_t parameter,
+                                       brlapi_param_subparam_t subparam,
+                                       brlapi_param_flags_t flags,
+                                       const void* data,
+                                       size_t len);
+#endif
+int BRLAPI_STDCALL brlapi__setParameter(brlapi_handle_t* handle,
+                                        brlapi_param_t parameter,
+                                        brlapi_param_subparam_t subparam,
+                                        brlapi_param_flags_t flags,
+                                        const void* data,
+                                        size_t len);
+
+/* brlapi_paramCallback_t */
+/** Callback for parameter changes
+ *
+ * When a parameter gets changed, application-defined callbacks set by the
+ * brlapi_watchParameter() function are called.
+ *
+ * \param parameter is the parameter that changed;
+ * \param flags specify which value and how it was changed;
+ * \param priv is the void pointer that was passed to the brlapi_watchParameter
+ * call which registered the callback; \param data is a buffer containing the
+ * new value of the parameter; \param len is the size of the data.
+ *
+ * This callback only gets called when the application calls some brlapi_
+ * function (i.e. BrlAPI gets direct control of the execution).
+ */
+typedef void (*brlapi_paramCallback_t)(brlapi_param_t parameter,
+                                       brlapi_param_subparam_t subparam,
+                                       brlapi_param_flags_t flags,
+                                       void* priv,
+                                       const void* data,
+                                       size_t len);
+
+/* brlapi_paramCallbackDescriptor_t */
+/** Type for callback descriptors
+ * This is returned by brlapi_watchParameter, to be passed to
+ * brlapi_unwatchParameter.
+ */
+typedef void* brlapi_paramCallbackDescriptor_t;
+
+/* brlapi_watchParameter */
+/** Set a parameter change callback
+ *
+ * brlapi_watchParameter registers a parameter change callback: whenever the
+ * given parameter changes, the given function is called.
+ *
+ * \param parameter is the parameter to watch;
+ * \param subparam is a specific instance of the parameter;
+ * \param flags specify which value and how it should be monitored;
+ * \param func is the function to call on parameter change;
+ * \param priv is a void pointer which will be passed as such to the function;
+ * \param data is a buffer where the current content of the parameter shall be
+ * stored;
+ * \param len is the size of the buffer.
+ *
+ * \return the callback descriptor (to be passed to brlapi_unwatchParameter to
+ * unregister the callback), or NULL on error.
+ *
+ * \note Default parameter callbacks don't do anything, except the ones for
+ * display size which just raise SIGWINCH.
+ * \note If data is NULL, the callback will be called immediately by
+ * brlapi_watchParameter, for providing the initial value
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL
+brlapi_watchParameter(brlapi_param_t parameter,
+                      brlapi_param_subparam_t subparam,
+                      brlapi_param_flags_t flags,
+                      brlapi_paramCallback_t func,
+                      void* priv,
+                      void* data,
+                      size_t len);
+#endif
+brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL
+brlapi__watchParameter(brlapi_handle_t* handle,
+                       brlapi_param_t parameter,
+                       brlapi_param_subparam_t subparam,
+                       brlapi_param_flags_t flags,
+                       brlapi_paramCallback_t func,
+                       void* priv,
+                       void* data,
+                       size_t len);
+
+/* brlapi_unwatchParameter */
+/** Clear a parameter change callback
+ *
+ * brlapi_unwatchParameter unregisters a parameter change callback: the
+ * callback function previously registered with brlapi_watchParameter will
+ * not be called any longer.
+ *
+ * \param descriptor refers to the callback to be removed.
+ *
+ * \return 0 on success, -1 on error.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL
+brlapi_unwatchParameter(brlapi_paramCallbackDescriptor_t descriptor);
+#endif
+int BRLAPI_STDCALL
+brlapi__unwatchParameter(brlapi_handle_t* handle,
+                         brlapi_paramCallbackDescriptor_t descriptor);
+
+/** @} */
+
+/** \defgroup brlapi_misc Miscellaneous functions
+ * @{ */
+
+/* brlapi_pause */
+/**
+ * Waits until an event is received from the BrlAPI server
+ * \param timeout_ms specifies an optional timeout which can be zero for
+ * polling, or -1 for infinite wait \return nothing
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+void BRLAPI_STDCALL brlapi_pause(int timeout_ms);
+#endif
+void BRLAPI_STDCALL brlapi__pause(brlapi_handle_t* handle, int timeout_ms);
+
+/** @} */
+
+/** \defgroup brlapi_error Error handling
+ * \brief How to handle errors
+ *
+ * When a function fails, ::brlapi_errno will hold an error
+ * code to explain why it failed. It should always be reported somehow.
+ *
+ * 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 \e exception
+ * handler. If the exception handler returns, the brlapi_something function will
+ * return an end-of-file error.
+ *
+ * The default exception handler (brlapi_defaultExceptionHandler()) dumps
+ * the guilty packet before abort()ing.  It can be replaced by calling
+ * brlapi_setExceptionHandler().  For instance, the Java and Python bindings use
+ * this for raising a Java or Python exception that may be caught.
+ *
+ * @{ */
+
+/* Error codes */
+#define BRLAPI_ERROR_SUCCESS 0 /**< Success */
+#define BRLAPI_ERROR_NOMEM 1   /**< Not enough memory */
+#define BRLAPI_ERROR_TTYBUSY \
+  2 /**< A connection is already running in this tty */
+#define BRLAPI_ERROR_DEVICEBUSY \
+  3 /**< A connection is already using RAW or suspend mode */
+#define BRLAPI_ERROR_UNKNOWN_INSTRUCTION 4 /**< Not implemented in protocol */
+#define BRLAPI_ERROR_ILLEGAL_INSTRUCTION 5 /**< Forbiden in current mode */
+#define BRLAPI_ERROR_INVALID_PARAMETER 6   /**< Out of range or have no sense */
+#define BRLAPI_ERROR_INVALID_PACKET 7      /**< Invalid size */
+#define BRLAPI_ERROR_CONNREFUSED 8         /**< Connection refused */
+#define BRLAPI_ERROR_OPNOTSUPP 9           /**< Operation not supported */
+#define BRLAPI_ERROR_GAIERR 10             /**< Getaddrinfo error */
+#define BRLAPI_ERROR_LIBCERR 11            /**< Libc error */
+#define BRLAPI_ERROR_UNKNOWNTTY 12 /**< Couldn't find out the tty number */
+#define BRLAPI_ERROR_PROTOCOL_VERSION 13 /**< Bad protocol version */
+#define BRLAPI_ERROR_EOF 14              /**< Unexpected end of file */
+#define BRLAPI_ERROR_EMPTYKEY 15         /**< Key file empty */
+#define BRLAPI_ERROR_DRIVERERROR              \
+  16 /**< Packet returned by driver too large \
+      */
+#define BRLAPI_ERROR_AUTHENTICATION 17 /**< Authentication failed */
+#define BRLAPI_ERROR_READONLY_PARAMETER \
+  18 /**< Parameter can not be changed  \
+      */
+
+/* brlapi_errlist */
+/** Error message list
+ *
+ * These are the string constants used by brlapi_perror().
+ */
+extern const char* brlapi_errlist[];
+
+/* brlapi_nerr */
+/** Number of error messages */
+extern const int brlapi_nerr;
+
+/* brlapi_perror */
+/** Print a BrlAPI error message
+ *
+ * brlapi_perror() reads ::brlapi_error, and acts just like perror().
+ */
+void BRLAPI_STDCALL brlapi_perror(const char* s);
+
+/* brlapi_error_t */
+/** All information that is needed to describe brlapi errors */
+typedef struct {
+  int brlerrno;
+  int libcerrno;
+  int gaierrno;
+  const char* errfun;
+} brlapi_error_t;
+
+/** Get per-thread error location
+ *
+ * In multithreaded software, ::brlapi_error is thread-specific, so api.h
+ * cheats about the brlapi_error token and actually calls
+ * brlapi_error_location().
+ *
+ * This gets the thread specific location of global variable ::brlapi_error
+ */
+brlapi_error_t* BRLAPI_STDCALL brlapi_error_location(void);
+
+/** Global variable brlapi_error
+ *
+ * ::brlapi_error is a global left-value containing the last error information.
+ * Its errno field is not reset to BRLAPI_ERROR_SUCCESS on success.
+ *
+ * This information may be copied in brlapi_error_t variables for later use
+ * with the brlapi_strerror function.
+ */
+extern brlapi_error_t brlapi_error;
+
+/** Shorthand for brlapi_error.errno */
+extern int brlapi_errno;
+/** Shorthand for brlapi_error.libcerrno */
+extern int brlapi_libcerrno;
+/** Shorthand for brlapi_error.gaierrno */
+extern int brlapi_gaierrno;
+/** Shorthand for brlapi_error.errfun */
+extern const char* brlapi_errfun;
+
+/** Cheat about the brlapi_error C token */
+#define brlapi_error (*brlapi_error_location())
+/** Cheat about the brlapi_errno C token */
+#define brlapi_errno (brlapi_error.brlerrno)
+/** Cheat about the brlapi_libcerrno C token */
+#define brlapi_libcerrno (brlapi_error.libcerrno)
+/** Cheat about the brlapi_gaierrno C token */
+#define brlapi_gaierrno (brlapi_error.gaierrno)
+/** Cheat about the brlapi_errfun C token */
+#define brlapi_errfun (brlapi_error.errfun)
+
+/* brlapi_strerror */
+/** Get plain error message
+ *
+ * brlapi_strerror() returns the plain error message corresponding to its
+ * argument.
+ */
+const char* BRLAPI_STDCALL brlapi_strerror(const brlapi_error_t* error);
+
+/** Type for packet type. Only unsigned can cross networks, 32bits */
+typedef uint32_t brlapi_packetType_t;
+
+/* brlapi_getPacketTypeName */
+/** Get plain packet type
+ *
+ * brlapi_getPacketTypeName() returns the plain packet type name corresponding
+ * to its argument.
+ */
+const char* BRLAPI_STDCALL brlapi_getPacketTypeName(brlapi_packetType_t type);
+
+/* brlapi_exceptionHandler_t */
+/** Types for exception handlers
+ *
+ * Types of exception handlers which are to be given to
+ * brlapi_setExceptionHandler() and brlapi__setExceptionHandler().
+ *
+ * \param handle is the handle corresponding to the guilty connection;
+ * \param error is a BRLAPI_ERROR_ error code;
+ * \param type is the type of the guilty packet;
+ * \param packet points to the content of the guilty packet (might be a little
+ * bit truncated); \param size gives the guilty packet's size.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+typedef void(BRLAPI_STDCALL* brlapi_exceptionHandler_t)(
+    int error,
+    brlapi_packetType_t type,
+    const void* packet,
+    size_t size);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+typedef void(BRLAPI_STDCALL* brlapi__exceptionHandler_t)(
+    brlapi_handle_t* handle,
+    int error,
+    brlapi_packetType_t type,
+    const void* packet,
+    size_t size);
+
+/* brlapi_strexception */
+/** Describes an exception
+ *
+ * brlapi_strexception() puts a text describing the given exception in buffer.
+ *
+ * The beginning of the guilty packet is dumped as a sequence of hex bytes.
+ *
+ * \return the size of the text describing the exception, following
+ * snprintf()'s semantics.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_strexception(char* buffer,
+                                       size_t bufferSize,
+                                       int error,
+                                       brlapi_packetType_t type,
+                                       const void* packet,
+                                       size_t packetSize);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__strexception(brlapi_handle_t* handle,
+                                        char* buffer,
+                                        size_t bufferSize,
+                                        int error,
+                                        brlapi_packetType_t type,
+                                        const void* packet,
+                                        size_t packetSize);
+
+/* brlapi_setExceptionHandler */
+/** Set a new exception handler
+ *
+ * brlapi_setExceptionHandler() replaces the previous exception handler with
+ * the handler parameter. The previous exception handler is returned to make
+ * chaining error handlers possible.
+ *
+ * The default handler just prints the exception and abort()s.
+ */
+#ifndef BRLAPI_NO_SINGLE_SESSION
+brlapi_exceptionHandler_t BRLAPI_STDCALL
+brlapi_setExceptionHandler(brlapi_exceptionHandler_t handler);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+brlapi__exceptionHandler_t BRLAPI_STDCALL
+brlapi__setExceptionHandler(brlapi_handle_t* handle,
+                            brlapi__exceptionHandler_t handler);
+
+#ifndef BRLAPI_NO_SINGLE_SESSION
+void BRLAPI_STDCALL brlapi_defaultExceptionHandler(int error,
+                                                   brlapi_packetType_t type,
+                                                   const void* packet,
+                                                   size_t size);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+void BRLAPI_STDCALL brlapi__defaultExceptionHandler(brlapi_handle_t* handle,
+                                                    int error,
+                                                    brlapi_packetType_t type,
+                                                    const void* packet,
+                                                    size_t size);
+
+/** @} */
+
+/* Windows-specific tricks - don't look at this */
+#ifdef BRLAPI_WIN32
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_writeTextWin(int cursor, const void* str, int wide);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__writeTextWin(brlapi_handle_t* handle,
+                                        int cursor,
+                                        const void* str,
+                                        int wide);
+
+#ifndef BRLAPI_NO_SINGLE_SESSION
+int BRLAPI_STDCALL brlapi_writeWin(const brlapi_writeArguments_t* s, int wide);
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+int BRLAPI_STDCALL brlapi__writeWin(brlapi_handle_t* handle,
+                                    const brlapi_writeArguments_t* s,
+                                    int wide);
+
+#ifdef UNICODE
+#ifndef BRLAPI_NO_SINGLE_SESSION
+#define brlapi_writeText(cursor, str) brlapi_writeTextWin(cursor, str, 1)
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+#define brlapi__writeText(handle, cursor, str) \
+  brlapi__writeTextWin(handle, cursor, str, 1)
+
+#ifndef BRLAPI_NO_SINGLE_SESSION
+#define brlapi_write(s) brlapi_writeWin(s, 1)
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+#define brlapi__write(handle, s) brlapi__writeWin(handle, s, 1)
+
+#else /* UNICODE */
+
+#ifndef BRLAPI_NO_SINGLE_SESSION
+#define brlapi_writeText(cursor, str) brlapi_writeTextWin(cursor, str, 0)
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+#define brlapi__writeText(handle, cursor, str) \
+  brlapi__writeTextWin(handle, cursor, str, 0)
+
+#ifndef BRLAPI_NO_SINGLE_SESSION
+#define brlapi_write(s) brlapi_writeWin(s, 0)
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+#define brlapi__write(handle, s) brlapi__writeWin(handle, s, 0)
+
+#endif /* UNICODE */
+#endif /* BRLAPI_WIN32 */
+
+#ifndef BRLAPI_NO_DEPRECATED
+/** \defgroup brlapi_deprecated Deprecated names
+ *
+ * With version 0.5.0, BrlAPI is now provided through including <brlapi.h> and
+ * got a big renaming pass. Old names are still available through macros, but
+ * they are deprecated since they will get dropped in the next release. This
+ * documentation is for you to know the new names.
+ *
+ * For checking that you have completely switched to new names, just define
+ * BRLAPI_NO_DEPRECATED: that will disable compatibility macros.
+ *
+ * @{ */
+
+#define brlapi_settings_t brlapi_connectionSettings_t
+
+/** brlapi_writeStruct, replaced by brlapi_writeArguments_t */
+typedef struct {
+  int displayNumber;
+  unsigned int regionBegin;
+  unsigned int regionSize;
+  char* text;
+  int textSize;
+  unsigned char* attrAnd;
+  unsigned char* attrOr;
+  int cursor;
+  char* charset;
+} brlapi_writeStruct;
+#define BRLAPI_WRITESTRUCT_INITIALIZER BRLAPI_WRITEARGUMENTS_INITIALIZER
+
+#define brl_keycode_t brlapi_keyCode_t
+#define brl_type_t brlapi_packetType_t
+
+#define BRLCOMMANDS NULL
+#define BRL_KEYCODE_MAX BRLAPI_KEY_MAX
+
+#ifndef BRLAPI_NO_SINGLE_SESSION
+#define brlapi_initializeConnection brlapi_openConnection
+#define brlapi_getTty brlapi_enterTtyMode
+#define brlapi_getTtyPath brlapi_enterTtyModeWithPath
+#define brlapi_leaveTty brlapi_leaveTtyMode
+#define brlapi_unignoreKeyRange brlapi_acceptKeyRange
+#define brlapi_unignoreKeySet brlapi_acceptKeySet
+#define brlapi_getRaw brlapi_enterRawMode
+#define brlapi_leaveRaw brlapi_leaveRawMode
+#define brlapi_suspend brlapi_suspendDriver
+#define brlapi_resume brlapi_resumeDriver
+#endif /* BRLAPI_NO_SINGLE_SESSION */
+
+#define BRLERR_SUCCESS BRLAPI_ERROR_SUCCESS
+#define BRLERR_NOMEM BRLAPI_ERROR_NOMEM
+#define BRLERR_TTYBUSY BRLAPI_ERROR_TTYBUSY
+#define BRLERR_DEVICEBUSY BRLAPI_ERROR_DEVICEBUSY
+#define BRLERR_UNKNOWN_INSTRUCTION BRLAPI_ERROR_UNKNOWN_INSTRUCTION
+#define BRLERR_ILLEGAL_INSTRUCTION BRLAPI_ERROR_ILLEGAL_INSTRUCTION
+#define BRLERR_INVALID_PARAMETER BRLAPI_ERROR_INVALID_PARAMETER
+#define BRLERR_INVALID_PACKET BRLAPI_ERROR_INVALID_PACKET
+#define BRLERR_CONNREFUSED BRLAPI_ERROR_CONNREFUSED
+#define BRLERR_OPNOTSUPP BRLAPI_ERROR_OPNOTSUPP
+#define BRLERR_GAIERR BRLAPI_ERROR_GAIERR
+#define BRLERR_LIBCERR BRLAPI_ERROR_LIBCERR
+#define BRLERR_UNKNOWNTTY BRLAPI_ERROR_UNKNOWNTTY
+#define BRLERR_PROTOCOL_VERSION BRLAPI_ERROR_PROTOCOL_VERSION
+#define BRLERR_EOF BRLAPI_ERROR_EOF
+#define BRLERR_EMPTYKEY BRLAPI_ERROR_EMPTYKEY
+#define BRLERR_DRIVERERROR BRLAPI_ERROR_DRIVERERROR
+
+/** @} */
+#endif /* BRLAPI_NO_DEPRECATED */
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+#endif /* BRLAPI_INCLUDED */