brlapi_connectionsettings_t(3) [debian man page]

brlapi_connectionSettings_t(3)					      BrlAPI					    brlapi_connectionSettings_t(3)

NAME

       brlapi_connectionSettings_t -

       Settings structure for BrlAPI connection.

SYNOPSIS

       #include <brlapi.h>

   Data Fields
       char * auth
       char * host

Detailed Description
       This structure holds every parameter needed to connect to BrlAPI: which file the authorization key can be found in and which computer to
       connect to.

       Examples:

	   brlapi_connectionSettings_t settings;

	   settings.auth='/etc/brlapi.key';
	   settings.host='foo';

       libbrlapi will read authorization key from file /etc/brlapi.key and connect to the machine called 'foo', on the default TCP port.

       settings.host='10.1.0.2';

       lets directly enter an IP address instead of a machine name.

       settings.host=':1';

       lets libbrlapi connect to the local computer, on port BRLAPI_SOCKETPORTNUM+1

       See Also:
	   brlapi_openConnection()

Field Documentation
   char* brlapi_connectionSettings_t::auth
       For security reasons, libbrlapi has to get authorized to connect to the 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 NULL defaults it to local installation setup or to the content of the BRLAPI_AUTH environment variable, if it exists.

   char* brlapi_connectionSettings_t::host
       This tells where the 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 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.

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

Version 1.0							  Fri Jun 7 2013				    brlapi_connectionSettings_t(3)

Connecting to BrlAPI(3) 					      BrlAPI						   Connecting to BrlAPI(3)

NAME

       Connecting to BrlAPI -

   Data Structures
       struct brlapi_connectionSettings_t
	   Settings structure for BrlAPI connection.

   Macros
       #define BRLAPI_SOCKETPORTNUM   4101
       #define BRLAPI_SOCKETPORT   '4101'
       #define BRLAPI_SOCKETPATH   '/var/lib/BrlAPI'
       #define BRLAPI_ETCDIR   '/etc'
       #define BRLAPI_AUTHKEYFILE   'brlapi.key'
       #define BRLAPI_DEFAUTH	BRLAPI_ETCDIR '/' BRLAPI_AUTHKEYFILE
       #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)"
       void BRLAPI_STDCALL brlapi_closeConnection (void)
       void BRLAPI_STDCALL brlapi__closeConnection (brlapi_handle_t *handle)

Detailed Description
       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.

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   BRLAPI_ETCDIR '/' BRLAPI_AUTHKEYFILE
       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_SETTINGS_INITIALIZER	 { NULL, NULL }
       Allows to initialize a structure of type brlapi_connectionSettings_t * with default values.

   #define BRLAPI_SOCKETPATH   '/var/lib/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
Function Documentation
   void BRLAPI_STDCALL brlapi__closeConnection (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_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 -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_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.

       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 1.0							  Fri Jun 7 2013					   Connecting to BrlAPI(3)