brlapi_connection(3)                BrlAPI                brlapi_connection(3)



NAME
       brlapi_connection - Before calling any other function of the library,
       calling brlapi_openConnection() is needed to establish a connection to
       BrlAPI 's server. When the connection is not needed any more,
       brlapi_closeConnection() must be called to close the connection.


SYNOPSIS
   Data Structures
       struct brlapi_connectionSettings_t
           Settings structure for BrlAPI connection.

   Macros
       #define BRLAPI_SOCKETPORTNUM   4101
       #define BRLAPI_SOCKETPORT   '4101'
       #define BRLAPI_SOCKETPATH   '\.ipe0
       #define BRLAPI_ETCDIR   '//etc'
       #define BRLAPI_AUTHKEYFILE   'brlapi.key'
       #define BRLAPI_DEFAUTH   'none'
       #define BRLAPI_INVALID_FILE_DESCRIPTOR   -1
       #define BRLAPI_SETTINGS_INITIALIZER   { NULL, NULL }

   Typedefs
       typedef int brlapi_fileDescriptor

   Functions
       brlapi_fileDescriptor BRLAPI_STDCALL brlapi_openConnection (const
           brlapi_connectionSettings_t *desiredSettings,
           brlapi_connectionSettings_t *actualSettings)
       brlapi_fileDescriptor BRLAPI_STDCALL brlapi__openConnection
           (brlapi_handle_t *handle, const brlapi_connectionSettings_t
           *desiredSettings, brlapi_connectionSettings_t *actualSettings)
       brlapi_fileDescriptor BRLAPI_STDCALL brlapi_getFileDescriptor (void)
       brlapi_fileDescriptor BRLAPI_STDCALL brlapi__getFileDescriptor
           (brlapi_handle_t *handle)
       void BRLAPI_STDCALL brlapi_closeConnection (void)
       void BRLAPI_STDCALL brlapi__closeConnection (brlapi_handle_t *handle)

Detailed Description
Macro Definition Documentation
   #define BRLAPI_AUTHKEYFILE   'brlapi.key'
       Default name of the file containing BrlAPI 's authorization key

       This name is relative to BRLAPI_ETCDIR

   #define BRLAPI_DEFAUTH   'none'
       Default authorization setting

   #define BRLAPI_ETCDIR   '//etc'
       brltty 's settings directory

       This is where authorization key and driver-dependent key names are
       found for instance.

   #define BRLAPI_INVALID_FILE_DESCRIPTOR   -1
       Invalid value for brlapi_fileDescriptor

       This is returned by brlapi_getFileDescriptor() when the connection is
       closed.

   #define BRLAPI_SETTINGS_INITIALIZER   { NULL, NULL }
       Allows to initialize a structure of type brlapi_connectionSettings_t *
       with default values.

   #define BRLAPI_SOCKETPATH   '\\.\pipe\BrlAPI'
       Default unix path on which connections to BrlAPI can be established

   #define BRLAPI_SOCKETPORT   '4101'
   #define BRLAPI_SOCKETPORTNUM   4101
       Default port number on which connections to BrlAPI can be established

Typedef Documentation
   typedef int brlapi_fileDescriptor
       OS-dependent file descriptor type

       This is the type for file descriptors returned by
       brlapi_openConnection() and brlapi_getFileDescriptor().

Function Documentation
   void BRLAPI_STDCALL brlapi__closeConnection (brlapi_handle_t * handle)
   brlapi_fileDescriptor BRLAPI_STDCALL brlapi__getFileDescriptor
       (brlapi_handle_t * handle)
   brlapi_fileDescriptor BRLAPI_STDCALL brlapi__openConnection
       (brlapi_handle_t * handle, const brlapi_connectionSettings_t *
       desiredSettings, brlapi_connectionSettings_t * actualSettings)
   void BRLAPI_STDCALL brlapi_closeConnection (void)
       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

   brlapi_fileDescriptor BRLAPI_STDCALL brlapi_getFileDescriptor (void)
       Return the file descriptor used by the BrlAPI connection

       This allows to use it with select(), g_io_add_watch(), XtAppAddInput(),
       etc.

       BRLAPI_INVALID_FILE_DESCRIPTOR is returned when the connection was
       closed.

   brlapi_fileDescriptor BRLAPI_STDCALL brlapi_openConnection (const
       brlapi_connectionSettings_t * desiredSettings,
       brlapi_connectionSettings_t * actualSettings)
       Open a socket and connect it to 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.

       Returns
           the file descriptor, or BRLAPI_INVALID_FILE_DESCRIPTOR on error

       Note
           The file descriptor is returned in case the client wants to
           communicate with the server without using 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
           libbrlapi functions will always work with the last call's
           descriptor

       Example:


           if (brlapi_openConnection(&settings,&settings)<0) {
            fprintf(stderr,"couldn't connect to BrlAPI at %s: %s0,
             settings.host, brlapi_strerror(&brlapi_error));
            exit(1);
           }


       Errors:
           BrlAPI might not be on this TCP port, the host name might not be
           resolvable, the authorization may fail,...

       Parameters
           desiredSettings this gives the desired connection parameters, as
           described in brlapi_connectionSettings_t. If NULL, defaults values
           are used, so that it is generally a good idea to give NULL as
           default, and only fill a brlapi_connectionSettings_t structure when
           the user gave parameters to the program for instance;
           actualSettings if not NULL, parameters which were actually used are
           stored here, if the application ever needs them. Since they are
           constant strings, or come from a getenv call, these must not be
           freed by the application.

       See also
           brlapi_connectionSettings_t brlapi_writePacket()
           brlapi_readPacketHeader() brlapi_readPacketContent()
           brlapi_readPacket()

Author
       Generated automatically by Doxygen for BrlAPI from the source code.



Version 0.8                     Mon Apr 6 2026            brlapi_connection(3)
