.TH "brlapi_connection" 3 "Version 0.8" "BrlAPI" \" -*- nroff -*- .ad l .nh .SH NAME brlapi_connection \- Connecting to BrlAPI .SH SYNOPSIS .br .PP .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBbrlapi_connectionSettings_t\fP" .br .RI "Settings structure for \fIBrlAPI\fP connection\&. " .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_KEYFILE\fP 'keyfile:' \fBBRLAPI_ETCDIR\fP '/' \fBBRLAPI_AUTHKEYFILE\fP" .br .ti -1c .RI "#define \fBBRLAPI_DEFAUTH_POLKIT\fP ''" .br .ti -1c .RI "#define \fBBRLAPI_DEFAUTH\fP \fBBRLAPI_DEFAUTH_KEYFILE\fP \fBBRLAPI_DEFAUTH_POLKIT\fP" .br .ti -1c .RI "#define \fBBRLAPI_INVALID_FILE_DESCRIPTOR\fP \-1" .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 \fBBRLAPI_STDCALL\fP \fBbrlapi_openConnection\fP (const \fBbrlapi_connectionSettings_t\fP *desiredSettings, \fBbrlapi_connectionSettings_t\fP *actualSettings)" .br .ti -1c .RI "\fBbrlapi_fileDescriptor\fP \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 "\fBbrlapi_fileDescriptor\fP \fBBRLAPI_STDCALL\fP \fBbrlapi_getFileDescriptor\fP (void)" .br .ti -1c .RI "\fBbrlapi_fileDescriptor\fP \fBBRLAPI_STDCALL\fP \fBbrlapi__getFileDescriptor\fP (\fBbrlapi_handle_t\fP *handle)" .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_DEFAUTH_KEYFILE\fP \fBBRLAPI_DEFAUTH_POLKIT\fP" .SS "#define BRLAPI_DEFAUTH_KEYFILE 'keyfile:' \fBBRLAPI_ETCDIR\fP '/' \fBBRLAPI_AUTHKEYFILE\fP" Default authorization setting .SS "#define BRLAPI_DEFAUTH_POLKIT ''" .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_INVALID_FILE_DESCRIPTOR \-1" Invalid value for brlapi_fileDescriptor .PP This is returned by \fBbrlapi_getFileDescriptor()\fP when the connection is closed\&. .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" OS-dependent file descriptor type .PP This is the type for file descriptors returned by \fBbrlapi_openConnection()\fP and \fBbrlapi_getFileDescriptor()\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__getFileDescriptor (\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_getFileDescriptor (void)" Return the file descriptor used by the BrlAPI connection .PP This allows to use it with \fCselect()\fP, \fCg_io_add_watch()\fP, \fCXtAppAddInput()\fP, etc\&. .PP BRLAPI_INVALID_FILE_DESCRIPTOR is returned when the connection was closed\&. .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 BRLAPI_INVALID_FILE_DESCRIPTOR 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\&. Since they are constant strings, or come from a getenv call, these must not be freed by the application\&. .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\&.