.TH "Connecting to BrlAPI" 3 "Mon Apr 1 2013" "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\&.