<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>BrlAPI: Connecting to BrlAPI</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="dirs.html"><span>Directories</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>Connecting to BrlAPI</h1><table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Data Structures</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Settings structure for <em>BrlAPI</em> connection. <a href="structbrlapi__connectionSettings__t.html#_details">More...</a><br/></td></tr>
<tr><td colspan="2"><h2>Defines</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#gabf6a76636febaac1c0251abb12d0935c">BRLAPI_SOCKETPORTNUM</a> 4101</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga4f5503ad782017b1e0b323b3ec8a331a">BRLAPI_SOCKETPORT</a> "4101"</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga056c43c3de93b35970abf896e99a9893">BRLAPI_SOCKETPATH</a> "/var/lib/BrlAPI"</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga0439f024cb826c67dbe16f7c66fa5a38">BRLAPI_ETCDIR</a> "/etc"</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga6f87d526cda948b27ca7f503b97561ec">BRLAPI_AUTHKEYFILE</a> "brlapi.key"</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga1b86dad4b4a50dc0875ab4c037812d5c">BRLAPI_DEFAUTH</a> BRLAPI_ETCDIR "/" BRLAPI_AUTHKEYFILE</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga45d2990108338f4764c4cabde1c3e759">BRLAPI_SETTINGS_INITIALIZER</a> { NULL, NULL }</td></tr>
<tr><td colspan="2"><h2>Typedefs</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a></td></tr>
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__brlapi__connection.html#ga1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> <br class="typebreak"/>
BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#gacd26dc42640bdad09a389be10b9e3618">brlapi_openConnection</a> (const <a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> *desiredSettings, <a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> *actualSettings)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__brlapi__connection.html#ga1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> <br class="typebreak"/>
BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#gab72663955b05e29196285f945f55aa87">brlapi__openConnection</a> (<a class="el" href="group__brlapi__handles.html#ga57f2aec62b18f8aefea2ab550744b0c1">brlapi_handle_t</a> *handle, const <a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> *desiredSettings, <a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> *actualSettings)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga7b2e32ae6b9dddaeea8f2365e37494cb">brlapi_closeConnection</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#ga8fb742c787203548522fc4d0f1edd041">brlapi__closeConnection</a> (<a class="el" href="group__brlapi__handles.html#ga57f2aec62b18f8aefea2ab550744b0c1">brlapi_handle_t</a> *handle)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Before calling any other function of the library, calling <a class="el" href="group__brlapi__connection.html#gacd26dc42640bdad09a389be10b9e3618">brlapi_openConnection()</a> is needed to establish a connection to <em>BrlAPI</em> 's server. When the connection is not needed any more, <a class="el" href="group__brlapi__connection.html#ga7b2e32ae6b9dddaeea8f2365e37494cb">brlapi_closeConnection()</a> must be called to close the connection. </p>
<hr/><h2>Define Documentation</h2>
<a class="anchor" id="ga6f87d526cda948b27ca7f503b97561ec"></a><!-- doxytag: member="brlapi.h::BRLAPI_AUTHKEYFILE" ref="ga6f87d526cda948b27ca7f503b97561ec" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BRLAPI_AUTHKEYFILE "brlapi.key"</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Default name of the file containing <em>BrlAPI</em> 's authorization key</p>
<p>This name is relative to BRLAPI_ETCDIR </p>
</div>
</div>
<a class="anchor" id="ga1b86dad4b4a50dc0875ab4c037812d5c"></a><!-- doxytag: member="brlapi.h::BRLAPI_DEFAUTH" ref="ga1b86dad4b4a50dc0875ab4c037812d5c" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BRLAPI_DEFAUTH BRLAPI_ETCDIR "/" BRLAPI_AUTHKEYFILE</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Default authorization setting </p>
</div>
</div>
<a class="anchor" id="ga0439f024cb826c67dbe16f7c66fa5a38"></a><!-- doxytag: member="brlapi.h::BRLAPI_ETCDIR" ref="ga0439f024cb826c67dbe16f7c66fa5a38" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BRLAPI_ETCDIR "/etc"</td>
</tr>
</table>
</div>
<div class="memdoc">
<p><em>brltty</em> 's settings directory</p>
<p>This is where authorization key and driver-dependent key names are found for instance. </p>
</div>
</div>
<a class="anchor" id="ga45d2990108338f4764c4cabde1c3e759"></a><!-- doxytag: member="brlapi.h::BRLAPI_SETTINGS_INITIALIZER" ref="ga45d2990108338f4764c4cabde1c3e759" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BRLAPI_SETTINGS_INITIALIZER { NULL, NULL }</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Allows to initialize a structure of type <em><a class="el" href="structbrlapi__connectionSettings__t.html" title="Settings structure for BrlAPI connection.">brlapi_connectionSettings_t</a></em> * with default values. </p>
</div>
</div>
<a class="anchor" id="ga056c43c3de93b35970abf896e99a9893"></a><!-- doxytag: member="brlapi.h::BRLAPI_SOCKETPATH" ref="ga056c43c3de93b35970abf896e99a9893" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BRLAPI_SOCKETPATH "/var/lib/BrlAPI"</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Default unix path on which connections to <em>BrlAPI</em> can be established </p>
</div>
</div>
<a class="anchor" id="ga4f5503ad782017b1e0b323b3ec8a331a"></a><!-- doxytag: member="brlapi.h::BRLAPI_SOCKETPORT" ref="ga4f5503ad782017b1e0b323b3ec8a331a" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BRLAPI_SOCKETPORT "4101"</td>
</tr>
</table>
</div>
<div class="memdoc">
</div>
</div>
<a class="anchor" id="gabf6a76636febaac1c0251abb12d0935c"></a><!-- doxytag: member="brlapi.h::BRLAPI_SOCKETPORTNUM" ref="gabf6a76636febaac1c0251abb12d0935c" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define BRLAPI_SOCKETPORTNUM 4101</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Default port number on which connections to <em>BrlAPI</em> can be established </p>
</div>
</div>
<hr/><h2>Typedef Documentation</h2>
<a class="anchor" id="ga1273c1f34be592e19c9319e64becd1c0"></a><!-- doxytag: member="brlapi.h::brlapi_fileDescriptor" ref="ga1273c1f34be592e19c9319e64becd1c0" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef int <a class="el" href="group__brlapi__connection.html#ga1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a></td>
</tr>
</table>
</div>
<div class="memdoc">
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga8fb742c787203548522fc4d0f1edd041"></a><!-- doxytag: member="brlapi.h::brlapi__closeConnection" ref="ga8fb742c787203548522fc4d0f1edd041" args="(brlapi_handle_t *handle)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void BRLAPI_STDCALL brlapi__closeConnection </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__brlapi__handles.html#ga57f2aec62b18f8aefea2ab550744b0c1">brlapi_handle_t</a> * </td>
<td class="paramname"> <em>handle</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
</div>
</div>
<a class="anchor" id="gab72663955b05e29196285f945f55aa87"></a><!-- doxytag: member="brlapi.h::brlapi__openConnection" ref="gab72663955b05e29196285f945f55aa87" args="(brlapi_handle_t *handle, const brlapi_connectionSettings_t *desiredSettings, brlapi_connectionSettings_t *actualSettings)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__brlapi__connection.html#ga1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> BRLAPI_STDCALL brlapi__openConnection </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__brlapi__handles.html#ga57f2aec62b18f8aefea2ab550744b0c1">brlapi_handle_t</a> * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const <a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> * </td>
<td class="paramname"> <em>desiredSettings</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> * </td>
<td class="paramname"> <em>actualSettings</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
</div>
</div>
<a class="anchor" id="ga7b2e32ae6b9dddaeea8f2365e37494cb"></a><!-- doxytag: member="brlapi.h::brlapi_closeConnection" ref="ga7b2e32ae6b9dddaeea8f2365e37494cb" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void BRLAPI_STDCALL brlapi_closeConnection </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Cleanly close the socket</p>
<p>This function locks until a closing acknowledgement is received from the server. The socket is then freed, so the file descriptor <a class="el" href="group__brlapi__connection.html#gacd26dc42640bdad09a389be10b9e3618">brlapi_openConnection()</a> gave has no meaning any more </p>
</div>
</div>
<a class="anchor" id="gacd26dc42640bdad09a389be10b9e3618"></a><!-- doxytag: member="brlapi.h::brlapi_openConnection" ref="gacd26dc42640bdad09a389be10b9e3618" args="(const brlapi_connectionSettings_t *desiredSettings, brlapi_connectionSettings_t *actualSettings)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__brlapi__connection.html#ga1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> BRLAPI_STDCALL brlapi_openConnection </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> * </td>
<td class="paramname"> <em>desiredSettings</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="structbrlapi__connectionSettings__t.html">brlapi_connectionSettings_t</a> * </td>
<td class="paramname"> <em>actualSettings</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Open a socket and connect it to <em>BrlAPI</em> 's server</p>
<p>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.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the file descriptor, or -1 on error</dd></dl>
<dl class="note"><dt><b>Note:</b></dt><dd>The file descriptor is returned in case the client wants to communicate with the server without using <em>libbrlapi</em> 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 <a class="el" href="group__brlapi__connection.html#gacd26dc42640bdad09a389be10b9e3618">brlapi_openConnection()</a> may be called several times, but <em>libbrlapi</em> functions will always work with the last call's descriptor</dd></dl>
<dl class="user"><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment"> <span class="keywordflow">if</span> (<a class="code" href="group__brlapi__connection.html#gacd26dc42640bdad09a389be10b9e3618">brlapi_openConnection</a>(&settings,&settings)<0) {
fprintf(stderr,<span class="stringliteral">"couldn't connect to BrlAPI at %s: %s\n"</span>,
settings.host, <a class="code" href="group__brlapi__error.html#ga04c3125a4b0f5af895728f36b3852a27">brlapi_strerror</a>(&<a class="code" href="group__brlapi__error.html#ga526102c7af8a8d224165a8063627f815">brlapi_error</a>));
exit(1);
}
</pre></div></dd></dl>
<dl class="user"><dt><b>Errors:</b></dt><dd><em>BrlAPI</em> might not be on this TCP port, the host name might not be resolvable, the authorization may fail,...</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>desiredSettings</em> </td><td>this gives the desired connection parameters, as described in <a class="el" href="structbrlapi__connectionSettings__t.html" title="Settings structure for BrlAPI connection.">brlapi_connectionSettings_t</a>. If <code>NULL</code>, defaults values are used, so that it is generally a good idea to give <code>NULL</code> as default, and only fill a <a class="el" href="structbrlapi__connectionSettings__t.html" title="Settings structure for BrlAPI connection.">brlapi_connectionSettings_t</a> structure when the user gave parameters to the program for instance; </td></tr>
<tr><td valign="top"></td><td valign="top"><em>actualSettings</em> </td><td>if not <code>NULL</code>, parameters which were actually used are stored here, if the application ever needs them.</td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="structbrlapi__connectionSettings__t.html" title="Settings structure for BrlAPI connection.">brlapi_connectionSettings_t</a> <a class="el" href="group__brlapi__protocol.html#gabc8a0c3fe653b8d44059aee810c5b35a">brlapi_writePacket()</a> <a class="el" href="group__brlapi__protocol.html#ga3fa149ae4b0f1adcf8f514ebc9a1f45f">brlapi_readPacketHeader()</a> <a class="el" href="group__brlapi__protocol.html#ga6a963be14210e5706f16b57a2f388e6e">brlapi_readPacketContent()</a> <a class="el" href="group__brlapi__protocol.html#ga593411f2c9306ff774eb854f78eaa18b">brlapi_readPacket()</a> </dd></dl>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 9 May 2010 for BrlAPI by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
