Connecting to BrlAPI(3)   OpenBSD Programmer's Manual  Connecting to BrlAPI(3)



NAME
       Connecting to BrlAPI -

   Data Structures
       struct brlapi_settings_t
           Settings structure for BrlAPI connection.

   Defines
       #define BRLAPI_SOCKETPORT   '35751'
       #define BRLAPI_ETCDIR   '/etc'
       #define BRLAPI_AUTHFILE   'brlapi.key'
       #define BRLAPI_DEFAUTHPATH   BRLAPI_ETCDIR '/' BRLAPI_AUTHFILE

   Functions
       int brlapi_initializeConnection (const brlapi_settings_t
           *clientSettings, brlapi_settings_t *usedSettings)
       void brlapi_closeConnection (void)
       int brlapi_loadAuthKey (const char *filename, size_t *authlength, void
           *auth)

DETAILED DESCRIPTION
       Before calling any other function of the library, calling
       brlapi_initializeConnection() 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.

DEFINE DOCUMENTATION
   #define BRLAPI_AUTHFILE   'brlapi.key'
       Default name of the file containing BrlAPI 's authentication key

       This name is relative to BRLAPI_ETCDIR

   #define BRLAPI_DEFAUTHPATH   BRLAPI_ETCDIR '/' BRLAPI_AUTHFILE
       Final path for default authentication key file

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

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

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

FUNCTION DOCUMENTATION
   void 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_initializeConnection() gave has no meaning any more

   int brlapi_initializeConnection (const brlapi_settings_t * clientSettings,
       brlapi_settings_t * usedSettings)
       open a socket and connect it to BrlAPI 's server

       This function first loads an authentication 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 authentication key on the
       socket and waits for acknowledgement.

       Returns:
           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 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_initializeConnection() may be called several times, but
           libbrlapi functions will always work with the last call's
           descriptor

       Example:


        if (brlapi_initializeConnection(&settings,&settings)<0) {
         fprintf(stderr,'couldn't connect to BrlAPI at %s: %s0,
          settings.hostName, brlapi_strerror());
         exit(1);
        }
       Errors:
            BrlAPI might not be on this TCP port, the host name might not be
           resolvable, the authentication may fail,...

       Parameters:

       clientSettings
              this gives the connection parameters, as described in
              brlapi_settings_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_settings_t structure when the user gave parameters to
              the program for instance.

       usedSettings
              if not NULL, parameters which were actually used are stored
              here, if the application ever needs them.

       See also:
            brlapi_settings_t brlapi_loadAuthKey() brlapi_writePacket()
           brlapi_readPacket()

   int brlapi_loadAuthKey (const char * filename, size_t * authlength, void *
       auth)
       Load an authentication key from the given file

       Calling this function shouldn't be needed if
       brlapi_initializeConnection is used.

       Parameters:

       filename
              gives the full path of the file ;

       authlength
              gives the size of the auth buffer ;

       auth   is a buffer where the function will store the authentication key

       Returns:
           0, -1 on error

       See also:
           brlapi_settings_t, brlapi_initializeConnection



BrlAPI                            13 Jul 2004          Connecting to BrlAPI(3)
