diff options
Diffstat (limited to 'chromium/third_party/libbrlapi/brlapi.h')
| -rw-r--r-- | chromium/third_party/libbrlapi/brlapi.h | 1647 |
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 */ |