<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> <title>BrlAPI: Connecting to BrlAPI</title> <link href="doxygen.css" rel="stylesheet" type="text/css"> <link href="tabs.css" rel="stylesheet" type="text/css"> </head><body> <!-- Generated by Doxygen 1.5.6 --> <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></td></tr> <tr><td colspan="2"><br><h2>Data Structures</h2></td></tr> <tr><td class="memItemLeft" nowrap 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"><br><h2>Defines</h2></td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#gbf6a76636febaac1c0251abb12d0935c">BRLAPI_SOCKETPORTNUM</a> 4101</td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g4f5503ad782017b1e0b323b3ec8a331a">BRLAPI_SOCKETPORT</a> "4101"</td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g056c43c3de93b35970abf896e99a9893">BRLAPI_SOCKETPATH</a> "/var/lib/BrlAPI"</td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g0439f024cb826c67dbe16f7c66fa5a38">BRLAPI_ETCDIR</a> "/etc"</td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g6f87d526cda948b27ca7f503b97561ec">BRLAPI_AUTHKEYFILE</a> "brlapi.key"</td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g1b86dad4b4a50dc0875ab4c037812d5c">BRLAPI_DEFAUTH</a> BRLAPI_ETCDIR "/" BRLAPI_AUTHKEYFILE</td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">#define </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g45d2990108338f4764c4cabde1c3e759">BRLAPI_SETTINGS_INITIALIZER</a> { NULL, NULL }</td></tr> <tr><td colspan="2"><br><h2>Typedefs</h2></td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">typedef int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a></td></tr> <tr><td colspan="2"><br><h2>Functions</h2></td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top"><a class="el" href="group__brlapi__connection.html#g1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> <br> BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#gcd26dc42640bdad09a389be10b9e3618">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" nowrap align="right" valign="top"><a class="el" href="group__brlapi__connection.html#g1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> <br> BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#gb72663955b05e29196285f945f55aa87">brlapi__openConnection</a> (<a class="el" href="group__brlapi__handles.html#g57f2aec62b18f8aefea2ab550744b0c1">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" nowrap align="right" valign="top">void BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g7b2e32ae6b9dddaeea8f2365e37494cb">brlapi_closeConnection</a> (void)</td></tr> <tr><td class="memItemLeft" nowrap align="right" valign="top">void BRLAPI_STDCALL </td><td class="memItemRight" valign="bottom"><a class="el" href="group__brlapi__connection.html#g8fb742c787203548522fc4d0f1edd041">brlapi__closeConnection</a> (<a class="el" href="group__brlapi__handles.html#g57f2aec62b18f8aefea2ab550744b0c1">brlapi_handle_t</a> *handle)</td></tr> </table> <hr><a name="_details"></a><h2>Detailed Description</h2> Before calling any other function of the library, calling <a class="el" href="group__brlapi__connection.html#gcd26dc42640bdad09a389be10b9e3618">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#g7b2e32ae6b9dddaeea8f2365e37494cb">brlapi_closeConnection()</a> must be called to close the connection. <hr><h2>Define Documentation</h2> <a class="anchor" name="g6f87d526cda948b27ca7f503b97561ec"></a><!-- doxytag: member="brlapi.h::BRLAPI_AUTHKEYFILE" ref="g6f87d526cda948b27ca7f503b97561ec" 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> This name is relative to BRLAPI_ETCDIR </div> </div><p> <a class="anchor" name="g1b86dad4b4a50dc0875ab4c037812d5c"></a><!-- doxytag: member="brlapi.h::BRLAPI_DEFAUTH" ref="g1b86dad4b4a50dc0875ab4c037812d5c" 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 </div> </div><p> <a class="anchor" name="g0439f024cb826c67dbe16f7c66fa5a38"></a><!-- doxytag: member="brlapi.h::BRLAPI_ETCDIR" ref="g0439f024cb826c67dbe16f7c66fa5a38" 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> This is where authorization key and driver-dependent key names are found for instance. </div> </div><p> <a class="anchor" name="g45d2990108338f4764c4cabde1c3e759"></a><!-- doxytag: member="brlapi.h::BRLAPI_SETTINGS_INITIALIZER" ref="g45d2990108338f4764c4cabde1c3e759" 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. </div> </div><p> <a class="anchor" name="g056c43c3de93b35970abf896e99a9893"></a><!-- doxytag: member="brlapi.h::BRLAPI_SOCKETPATH" ref="g056c43c3de93b35970abf896e99a9893" 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 </div> </div><p> <a class="anchor" name="g4f5503ad782017b1e0b323b3ec8a331a"></a><!-- doxytag: member="brlapi.h::BRLAPI_SOCKETPORT" ref="g4f5503ad782017b1e0b323b3ec8a331a" 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"> <p> </div> </div><p> <a class="anchor" name="gbf6a76636febaac1c0251abb12d0935c"></a><!-- doxytag: member="brlapi.h::BRLAPI_SOCKETPORTNUM" ref="gbf6a76636febaac1c0251abb12d0935c" 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 </div> </div><p> <hr><h2>Typedef Documentation</h2> <a class="anchor" name="g1273c1f34be592e19c9319e64becd1c0"></a><!-- doxytag: member="brlapi.h::brlapi_fileDescriptor" ref="g1273c1f34be592e19c9319e64becd1c0" args="" --> <div class="memitem"> <div class="memproto"> <table class="memname"> <tr> <td class="memname">typedef int <a class="el" href="group__brlapi__connection.html#g1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> </td> </tr> </table> </div> <div class="memdoc"> <p> </div> </div><p> <hr><h2>Function Documentation</h2> <a class="anchor" name="g8fb742c787203548522fc4d0f1edd041"></a><!-- doxytag: member="brlapi.h::brlapi__closeConnection" ref="g8fb742c787203548522fc4d0f1edd041" 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#g57f2aec62b18f8aefea2ab550744b0c1">brlapi_handle_t</a> * </td> <td class="paramname"> <em>handle</em> </td> <td> ) </td> <td></td> </tr> </table> </div> <div class="memdoc"> <p> </div> </div><p> <a class="anchor" name="gb72663955b05e29196285f945f55aa87"></a><!-- doxytag: member="brlapi.h::brlapi__openConnection" ref="gb72663955b05e29196285f945f55aa87" 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#g1273c1f34be592e19c9319e64becd1c0">brlapi_fileDescriptor</a> BRLAPI_STDCALL brlapi__openConnection </td> <td>(</td> <td class="paramtype"><a class="el" href="group__brlapi__handles.html#g57f2aec62b18f8aefea2ab550744b0c1">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"> <p> </div> </div><p> <a class="anchor" name="g7b2e32ae6b9dddaeea8f2365e37494cb"></a><!-- doxytag: member="brlapi.h::brlapi_closeConnection" ref="g7b2e32ae6b9dddaeea8f2365e37494cb" 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> 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#gcd26dc42640bdad09a389be10b9e3618">brlapi_openConnection()</a> gave has no meaning any more </div> </div><p> <a class="anchor" name="gcd26dc42640bdad09a389be10b9e3618"></a><!-- doxytag: member="brlapi.h::brlapi_openConnection" ref="gcd26dc42640bdad09a389be10b9e3618" 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#g1273c1f34be592e19c9319e64becd1c0">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> 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" compact><dt><b>Returns:</b></dt><dd>the file descriptor, or -1 on error</dd></dl> <dl class="note" compact><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#gcd26dc42640bdad09a389be10b9e3618">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" compact><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#gcd26dc42640bdad09a389be10b9e3618">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#g04c3125a4b0f5af895728f36b3852a27">brlapi_strerror</a>(&<a class="code" href="group__brlapi__error.html#g526102c7af8a8d224165a8063627f815">brlapi_error</a>)); exit(1); } </pre></div></dd></dl> <dl class="user" compact><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 compact><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> </dl> <dl class="see" compact><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#gbc8a0c3fe653b8d44059aee810c5b35a">brlapi_writePacket()</a> <a class="el" href="group__brlapi__protocol.html#g3fa149ae4b0f1adcf8f514ebc9a1f45f">brlapi_readPacketHeader()</a> <a class="el" href="group__brlapi__protocol.html#g6a963be14210e5706f16b57a2f388e6e">brlapi_readPacketContent()</a> <a class="el" href="group__brlapi__protocol.html#g593411f2c9306ff774eb854f78eaa18b">brlapi_readPacket()</a> </dd></dl> </div> </div><p> </div> <hr size="1"><address style="text-align: right;"><small>Generated on Wed Oct 7 22:37:56 2009 for BrlAPI by <a href="http://www.doxygen.org/index.html"> <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6 </small></address> </body> </html>