<!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>
distrib
>
Mandriva
>
2010.1
>
x86_64
>
media
>
main-release
>
by-pkgid
>
78cff6a8ec39f0e621e35b5f5c351f9d
>
files
>
40
