1Connecting to BrlAPI(3)             BrlAPI             Connecting to BrlAPI(3)
2
3
4

NAME

6       Connecting to BrlAPI -
7
8   Data Structures
9       struct brlapi_connectionSettings_t
10           Settings structure for BrlAPI connection.
11
12   Defines
13       #define BRLAPI_SOCKETPORTNUM   4101
14       #define BRLAPI_SOCKETPORT   '4101'
15       #define BRLAPI_SOCKETPATH   '/var/lib/BrlAPI'
16       #define BRLAPI_ETCDIR   '/etc'
17       #define BRLAPI_AUTHKEYFILE   'brlapi.key'
18       #define BRLAPI_DEFAUTH   BRLAPI_ETCDIR '/' BRLAPI_AUTHKEYFILE
19       #define BRLAPI_SETTINGS_INITIALIZER   { NULL, NULL }
20
21   Typedefs
22       typedef int brlapi_fileDescriptor
23
24   Functions
25       brlapi_fileDescriptor BRLAPI_STDCALL brlapi_openConnection (const
26           brlapi_connectionSettings_t *desiredSettings,
27           brlapi_connectionSettings_t *actualSettings)
28       brlapi_fileDescriptor BRLAPI_STDCALL brlapi__openConnection
29           (brlapi_handle_t *handle, const brlapi_connectionSettings_t
30           *desiredSettings, brlapi_connectionSettings_t *actualSettings)
31       void BRLAPI_STDCALL brlapi_closeConnection (void)
32       void BRLAPI_STDCALL brlapi__closeConnection (brlapi_handle_t *handle)
33

Detailed Description

35       Before calling any other function of the library, calling
36       brlapi_openConnection() is needed to establish a connection to BrlAPI
37       's server. When the connection is not needed any more,
38       brlapi_closeConnection() must be called to close the connection.
39

Define Documentation

41   #define BRLAPI_AUTHKEYFILE   'brlapi.key'
42       Default name of the file containing BrlAPI 's authorization key
43
44       This name is relative to BRLAPI_ETCDIR
45
46   #define BRLAPI_DEFAUTH   BRLAPI_ETCDIR '/' BRLAPI_AUTHKEYFILE
47       Default authorization setting
48
49   #define BRLAPI_ETCDIR   '/etc'
50       brltty 's settings directory
51
52       This is where authorization key and driver-dependent key names are
53       found for instance.
54
55   #define BRLAPI_SETTINGS_INITIALIZER   { NULL, NULL }
56       Allows to initialize a structure of type brlapi_connectionSettings_t *
57       with default values.
58
59   #define BRLAPI_SOCKETPATH   '/var/lib/BrlAPI'
60       Default unix path on which connections to BrlAPI can be established
61
62   #define BRLAPI_SOCKETPORT   '4101'
63   #define BRLAPI_SOCKETPORTNUM   4101
64       Default port number on which connections to BrlAPI can be established
65

Typedef Documentation

67   typedef int brlapi_fileDescriptor

Function Documentation

69   void BRLAPI_STDCALL brlapi__closeConnection (brlapi_handle_t * handle)
70   brlapi_fileDescriptor BRLAPI_STDCALL brlapi__openConnection
71       (brlapi_handle_t * handle, const brlapi_connectionSettings_t *
72       desiredSettings, brlapi_connectionSettings_t * actualSettings)
73   void BRLAPI_STDCALL brlapi_closeConnection (void)
74       Cleanly close the socket
75
76       This function locks until a closing acknowledgement is received from
77       the server. The socket is then freed, so the file descriptor
78       brlapi_openConnection() gave has no meaning any more
79
80   brlapi_fileDescriptor BRLAPI_STDCALL brlapi_openConnection (const
81       brlapi_connectionSettings_t * desiredSettings,
82       brlapi_connectionSettings_t * actualSettings)
83       Open a socket and connect it to BrlAPI 's server
84
85       This function first loads an authorization key as specified in
86       settings. It then creates a TCP socket and connects it to the specified
87       machine, on the specified port. It writes the authorization key on the
88       socket and waits for acknowledgement.
89
90       Returns:
91           the file descriptor, or -1 on error
92
93       Note:
94           The file descriptor is returned in case the client wants to
95           communicate with the server without using libbrlapi functions. If
96           it uses them however, it won't have to pass the file descriptor
97           later, since the library keeps a copy of it. But that also means
98           that brlapi_openConnection() may be called several times, but
99           libbrlapi functions will always work with the last call's
100           descriptor
101
102       Example:.RS 4
103
104
105        if (brlapi_openConnection(&settings,&settings)<0) {
106         fprintf(stderr,'couldn't connect to BrlAPI at %s: %s0,
107          settings.host, brlapi_strerror(&brlapi_error));
108         exit(1);
109        }
110
111
112       Errors:.RS 4 BrlAPI might not be on this TCP port, the host name might
113       not be resolvable, the authorization may fail,...
114
115       Parameters:
116           desiredSettings this gives the desired connection parameters, as
117           described in brlapi_connectionSettings_t. If NULL, defaults values
118           are used, so that it is generally a good idea to give NULL as
119           default, and only fill a brlapi_connectionSettings_t structure when
120           the user gave parameters to the program for instance;
121           actualSettings if not NULL, parameters which were actually used are
122           stored here, if the application ever needs them.
123
124       See also:
125           brlapi_connectionSettings_t brlapi_writePacket()
126           brlapi_readPacketHeader() brlapi_readPacketContent()
127           brlapi_readPacket()
128
129Version 1.0                       7 Oct 2009           Connecting to BrlAPI(3)
Impressum