1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
.TH "Connecting to BrlAPI" 3 "Sat Oct 25 2014" "Version 1.0" "BrlAPI" \" -*- nroff -*-
.ad l
.nh
.SH NAME
Connecting to BrlAPI \-
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct \fBbrlapi_connectionSettings_t\fP"
.br
.RI "\fISettings structure for \fIBrlAPI\fP connection\&. \fP"
.in -1c
.SS "Macros"
.in +1c
.ti -1c
.RI "#define \fBBRLAPI_SOCKETPORTNUM\fP 4101"
.br
.ti -1c
.RI "#define \fBBRLAPI_SOCKETPORT\fP '4101'"
.br
.ti -1c
.RI "#define \fBBRLAPI_SOCKETPATH\fP '/var/lib/BrlAPI'"
.br
.ti -1c
.RI "#define \fBBRLAPI_ETCDIR\fP '/etc'"
.br
.ti -1c
.RI "#define \fBBRLAPI_AUTHKEYFILE\fP 'brlapi\&.key'"
.br
.ti -1c
.RI "#define \fBBRLAPI_DEFAUTH\fP \fBBRLAPI_ETCDIR\fP '/' \fBBRLAPI_AUTHKEYFILE\fP"
.br
.ti -1c
.RI "#define \fBBRLAPI_SETTINGS_INITIALIZER\fP { NULL, NULL }"
.br
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef int \fBbrlapi_fileDescriptor\fP"
.br
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "\fBbrlapi_fileDescriptor\fP
.br
\fBBRLAPI_STDCALL\fP \fBbrlapi_openConnection\fP (const \fBbrlapi_connectionSettings_t\fP *desiredSettings, \fBbrlapi_connectionSettings_t\fP *actualSettings)"
.br
.ti -1c
.RI "\fBbrlapi_fileDescriptor\fP
.br
\fBBRLAPI_STDCALL\fP \fBbrlapi__openConnection\fP (\fBbrlapi_handle_t\fP *handle, const \fBbrlapi_connectionSettings_t\fP *desiredSettings, \fBbrlapi_connectionSettings_t\fP *actualSettings)"
.br
.ti -1c
.RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi_closeConnection\fP (void)"
.br
.ti -1c
.RI "void \fBBRLAPI_STDCALL\fP \fBbrlapi__closeConnection\fP (\fBbrlapi_handle_t\fP *handle)"
.br
.in -1c
.SH "Detailed Description"
.PP
Before calling any other function of the library, calling \fBbrlapi_openConnection()\fP is needed to establish a connection to \fIBrlAPI\fP 's server\&. When the connection is not needed any more, \fBbrlapi_closeConnection()\fP must be called to close the connection\&.
.SH "Macro Definition Documentation"
.PP
.SS "#define BRLAPI_AUTHKEYFILE 'brlapi\&.key'"
Default name of the file containing \fIBrlAPI\fP 's authorization key
.PP
This name is relative to BRLAPI_ETCDIR
.SS "#define BRLAPI_DEFAUTH \fBBRLAPI_ETCDIR\fP '/' \fBBRLAPI_AUTHKEYFILE\fP"
Default authorization setting
.SS "#define BRLAPI_ETCDIR '/etc'"
\fIbrltty\fP 's settings directory
.PP
This is where authorization key and driver-dependent key names are found for instance\&.
.SS "#define BRLAPI_SETTINGS_INITIALIZER { NULL, NULL }"
Allows to initialize a structure of type \fI\fBbrlapi_connectionSettings_t\fP\fP * with default values\&.
.SS "#define BRLAPI_SOCKETPATH '/var/lib/BrlAPI'"
Default unix path on which connections to \fIBrlAPI\fP can be established
.SS "#define BRLAPI_SOCKETPORT '4101'"
.SS "#define BRLAPI_SOCKETPORTNUM 4101"
Default port number on which connections to \fIBrlAPI\fP can be established
.SH "Typedef Documentation"
.PP
.SS "typedef int \fBbrlapi_fileDescriptor\fP"
.SH "Function Documentation"
.PP
.SS "void \fBBRLAPI_STDCALL\fP brlapi__closeConnection (\fBbrlapi_handle_t\fP *handle)"
.SS "\fBbrlapi_fileDescriptor\fP \fBBRLAPI_STDCALL\fP brlapi__openConnection (\fBbrlapi_handle_t\fP *handle, const \fBbrlapi_connectionSettings_t\fP *desiredSettings, \fBbrlapi_connectionSettings_t\fP *actualSettings)"
.SS "void \fBBRLAPI_STDCALL\fP brlapi_closeConnection (void)"
Cleanly close the socket
.PP
This function locks until a closing acknowledgement is received from the server\&. The socket is then freed, so the file descriptor \fBbrlapi_openConnection()\fP gave has no meaning any more
.SS "\fBbrlapi_fileDescriptor\fP \fBBRLAPI_STDCALL\fP brlapi_openConnection (const \fBbrlapi_connectionSettings_t\fP *desiredSettings, \fBbrlapi_connectionSettings_t\fP *actualSettings)"
Open a socket and connect it to \fIBrlAPI\fP 's server
.PP
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\&.
.PP
\fBReturns:\fP
.RS 4
the file descriptor, or -1 on error
.RE
.PP
\fBNote:\fP
.RS 4
The file descriptor is returned in case the client wants to communicate with the server without using \fIlibbrlapi\fP 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 \fBbrlapi_openConnection()\fP may be called several times, but \fIlibbrlapi\fP functions will always work with the last call's descriptor
.RE
.PP
\fBExample:\fP
.RS 4
.PP
.nf
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);
}
.fi
.PP
.RE
.PP
\fBErrors:\fP
.RS 4
\fIBrlAPI\fP might not be on this TCP port, the host name might not be resolvable, the authorization may fail,\&.\&.\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIdesiredSettings\fP this gives the desired connection parameters, as described in \fBbrlapi_connectionSettings_t\fP\&. If \fCNULL\fP, defaults values are used, so that it is generally a good idea to give \fCNULL\fP as default, and only fill a \fBbrlapi_connectionSettings_t\fP structure when the user gave parameters to the program for instance;
.br
\fIactualSettings\fP if not \fCNULL\fP, parameters which were actually used are stored here, if the application ever needs them\&.
.RE
.PP
\fBSee also:\fP
.RS 4
\fBbrlapi_connectionSettings_t\fP \fBbrlapi_writePacket()\fP \fBbrlapi_readPacketHeader()\fP \fBbrlapi_readPacketContent()\fP \fBbrlapi_readPacket()\fP
.RE
.PP
.SH "Author"
.PP
Generated automatically by Doxygen for BrlAPI from the source code\&.
|
