| 1 |
<?xml version="1.0" encoding="utf-8" ?> |
| 2 |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 3 |
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| 4 |
<head> |
| 5 |
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| 6 |
<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" /> |
| 7 |
<title>Listeners and Clients</title> |
| 8 |
<link rel="stylesheet" href="html4css1.css" type="text/css" /> |
| 9 |
</head> |
| 10 |
<body> |
| 11 |
<div class="header"> |
| 12 |
<a class="reference" href="sharedctypes.html">Prev</a> <a class="reference" href="processing-ref.html">Up</a> <a class="reference" href="programming-guidelines.html">Next</a> |
| 13 |
<hr class="header"/> |
| 14 |
</div> |
| 15 |
<div class="document" id="listeners-and-clients"> |
| 16 |
<h1 class="title">Listeners and Clients</h1> |
| 17 |
<p>Usually message passing between processes is done using queues or by |
| 18 |
using connection objects returned by <tt class="docutils literal"><span class="pre">Pipe()</span></tt>.</p> |
| 19 |
<p>However, the <tt class="docutils literal"><span class="pre">processing.connection</span></tt> module allows some extra |
| 20 |
flexibility. It basically gives a high level API for dealing with |
| 21 |
sockets or Windows named pipes, and also has support for <em>digest |
| 22 |
authentication</em> using the <tt class="docutils literal"><span class="pre">hmac</span></tt> module from the standard library.</p> |
| 23 |
<div class="section"> |
| 24 |
<h1><a id="classes-and-functions" name="classes-and-functions">Classes and functions</a></h1> |
| 25 |
<p>The module defines the following functions:</p> |
| 26 |
<blockquote> |
| 27 |
<dl class="docutils"> |
| 28 |
<dt><tt class="docutils literal"><span class="pre">Listener(address=None,</span> <span class="pre">family=None,</span> <span class="pre">backlog=1,</span> <span class="pre">authenticate=False,</span> <span class="pre">authkey=None)</span></tt></dt> |
| 29 |
<dd>Returns a wrapper for a bound socket or Windows named pipe |
| 30 |
which is 'listening' for connections.</dd> |
| 31 |
<dt><tt class="docutils literal"><span class="pre">Client(address,</span> <span class="pre">family=None,</span> <span class="pre">authenticate=False,</span> <span class="pre">authkey=None)</span></tt></dt> |
| 32 |
<dd><p class="first">Attempts to set up a connection to the listener which is using |
| 33 |
address <tt class="docutils literal"><span class="pre">address</span></tt>, returning a <a class="reference" href="connection-object.html">connection object</a>.</p> |
| 34 |
<p>The type of the connection is determined by <tt class="docutils literal"><span class="pre">family</span></tt> |
| 35 |
argument, but this can generally be omitted since it can |
| 36 |
usually be inferred from the format of <tt class="docutils literal"><span class="pre">address</span></tt>.</p> |
| 37 |
<p class="last">If <tt class="docutils literal"><span class="pre">authentication</span></tt> or <tt class="docutils literal"><span class="pre">authkey</span></tt> is a string then digest |
| 38 |
authentication is used. The key used for authentication will |
| 39 |
be either <tt class="docutils literal"><span class="pre">authkey</span></tt> or <tt class="docutils literal"><span class="pre">currentProcess.getAuthKey()</span></tt> if |
| 40 |
<tt class="docutils literal"><span class="pre">authkey</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt>. If authentication fails then |
| 41 |
<tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is raised. See <a class="reference" href="#authentication-keys">Authentication keys</a>.</p> |
| 42 |
</dd> |
| 43 |
</dl> |
| 44 |
</blockquote> |
| 45 |
<!-- `deliverChallenge(connection, authkey)` |
| 46 |
Sends a randomly generated message to the other end of the |
| 47 |
connection and waits for a reply. |
| 48 |
|
| 49 |
If the reply matches the digest of the message using `authkey` |
| 50 |
as the key then a welcome message is sent to the other end of |
| 51 |
the connection. Otherwise `AuthenticationError` is raised. |
| 52 |
|
| 53 |
`answerChallenge(connection, authkey)` |
| 54 |
Receives a message, calculates the digest of the message using |
| 55 |
`authkey` as the key, and then sends the digest back. |
| 56 |
|
| 57 |
If a welcome message is not received then |
| 58 |
`AuthenticationError` is raised. --> |
| 59 |
<p>The module exports two exception types:</p> |
| 60 |
<blockquote> |
| 61 |
<dl class="docutils"> |
| 62 |
<dt><strong>exception</strong> <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt></dt> |
| 63 |
<dd>Exception raised when there is an authentication error.</dd> |
| 64 |
<dt><strong>exception</strong> <tt class="docutils literal"><span class="pre">BufferTooShort</span></tt></dt> |
| 65 |
<dd><p class="first">Exception raise by the <tt class="docutils literal"><span class="pre">recvBytesInto()</span></tt> method of a |
| 66 |
connection object when the supplied buffer object is too small |
| 67 |
for the message read.</p> |
| 68 |
<p class="last">If <tt class="docutils literal"><span class="pre">e</span></tt> is an instance of <tt class="docutils literal"><span class="pre">BufferTooShort</span></tt> then <tt class="docutils literal"><span class="pre">e.args[0]</span></tt> will |
| 69 |
give the message as a byte string.</p> |
| 70 |
</dd> |
| 71 |
</dl> |
| 72 |
</blockquote> |
| 73 |
</div> |
| 74 |
<div class="section"> |
| 75 |
<h1><a id="listener-objects" name="listener-objects">Listener objects</a></h1> |
| 76 |
<p>Instances of <tt class="docutils literal"><span class="pre">Listener</span></tt> have the following methods:</p> |
| 77 |
<blockquote> |
| 78 |
<dl class="docutils"> |
| 79 |
<dt><tt class="docutils literal"><span class="pre">__init__(address=None,</span> <span class="pre">family=None,</span> <span class="pre">backlog=1,</span> <span class="pre">authenticate=False,</span> <span class="pre">authkey=None)</span></tt></dt> |
| 80 |
<dd><dl class="first last docutils"> |
| 81 |
<dt><tt class="docutils literal"><span class="pre">address</span></tt></dt> |
| 82 |
<dd>The address to be used by the bound socket |
| 83 |
or named pipe of the listener object.</dd> |
| 84 |
<dt><tt class="docutils literal"><span class="pre">family</span></tt></dt> |
| 85 |
<dd><p class="first">The type of the socket (or named pipe) to use.</p> |
| 86 |
<p>This can be one of the strings <tt class="docutils literal"><span class="pre">'AF_INET'</span></tt> (for a TCP |
| 87 |
socket), <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> (for a Unix domain socket) or |
| 88 |
<tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> (for a Windows named pipe). Of these only |
| 89 |
the first is guaranteed to be available.</p> |
| 90 |
<p>If <tt class="docutils literal"><span class="pre">family</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> than the family is inferred from the |
| 91 |
format of <tt class="docutils literal"><span class="pre">address</span></tt>. If <tt class="docutils literal"><span class="pre">address</span></tt> is also <tt class="docutils literal"><span class="pre">None</span></tt> then a |
| 92 |
default is chosen. This default is the family which is |
| 93 |
assumed to be the fastest available. See <a class="reference" href="#address-formats">Address |
| 94 |
formats</a>.</p> |
| 95 |
<p class="last">Note that if <tt class="docutils literal"><span class="pre">family</span></tt> is <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> then the associated |
| 96 |
file will have only be readable/writable by the user |
| 97 |
running the current process -- use <tt class="docutils literal"><span class="pre">os.chmod()</span></tt> is you need |
| 98 |
to let other users access the socket.</p> |
| 99 |
</dd> |
| 100 |
<dt><tt class="docutils literal"><span class="pre">backlog</span></tt></dt> |
| 101 |
<dd>If the listener object uses a socket then <tt class="docutils literal"><span class="pre">backlog</span></tt> is |
| 102 |
passed to the <tt class="docutils literal"><span class="pre">listen()</span></tt> method of the socket once it has |
| 103 |
been bound.</dd> |
| 104 |
<dt><tt class="docutils literal"><span class="pre">authenticate</span></tt></dt> |
| 105 |
<dd>If <tt class="docutils literal"><span class="pre">authenticate</span></tt> is true or <tt class="docutils literal"><span class="pre">authkey</span></tt> is not <tt class="docutils literal"><span class="pre">None</span></tt> then |
| 106 |
digest authentication is used.</dd> |
| 107 |
<dt><tt class="docutils literal"><span class="pre">authkey</span></tt></dt> |
| 108 |
<dd><p class="first">If <tt class="docutils literal"><span class="pre">authkey</span></tt> is a string then it will be used as the |
| 109 |
authentication key; otherwise it must be <tt class="docutils literal"><span class="pre">None</span></tt>.</p> |
| 110 |
<p>If <tt class="docutils literal"><span class="pre">authkey</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> and <tt class="docutils literal"><span class="pre">authenticate</span></tt> is true then |
| 111 |
<tt class="docutils literal"><span class="pre">currentProcess.getAuthKey()</span></tt> is used as the authentication |
| 112 |
key.</p> |
| 113 |
<p>If <tt class="docutils literal"><span class="pre">authkey</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt> and <tt class="docutils literal"><span class="pre">authentication</span></tt> is false then |
| 114 |
no authentication is done.</p> |
| 115 |
<p class="last">If authentication fails then <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is |
| 116 |
raised. See <a class="reference" href="#authentication-keys">Authentication keys</a>.</p> |
| 117 |
</dd> |
| 118 |
</dl> |
| 119 |
</dd> |
| 120 |
<dt><tt class="docutils literal"><span class="pre">accept()</span></tt></dt> |
| 121 |
<dd><p class="first">Accept a connection on the bound socket or named pipe of the |
| 122 |
listener object. If authentication is attempted and fails |
| 123 |
then <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is raised.</p> |
| 124 |
<p class="last">Returns a <tt class="docutils literal"><span class="pre">connection</span> <span class="pre">object</span> <span class="pre"><connection-object.html></span></tt> object.</p> |
| 125 |
</dd> |
| 126 |
<dt><tt class="docutils literal"><span class="pre">close()</span></tt></dt> |
| 127 |
<dd><p class="first">Close the bound socket or named pipe of the listener object.</p> |
| 128 |
<p class="last">This is called automatically when the listener is garbage |
| 129 |
collected. However it is advisable to call it explicitly.</p> |
| 130 |
</dd> |
| 131 |
</dl> |
| 132 |
</blockquote> |
| 133 |
<p>Listener objects have the following read-only properties:</p> |
| 134 |
<blockquote> |
| 135 |
<dl class="docutils"> |
| 136 |
<dt><tt class="docutils literal"><span class="pre">address</span></tt></dt> |
| 137 |
<dd>The address which is being used by the listener object.</dd> |
| 138 |
<dt><tt class="docutils literal"><span class="pre">last_accepted</span></tt></dt> |
| 139 |
<dd><p class="first">The address from which the last accepted connection came.</p> |
| 140 |
<p class="last">If this is unavailable then <tt class="docutils literal"><span class="pre">None</span></tt> is returned.</p> |
| 141 |
</dd> |
| 142 |
</dl> |
| 143 |
</blockquote> |
| 144 |
</div> |
| 145 |
<div class="section"> |
| 146 |
<h1><a id="address-formats" name="address-formats">Address formats</a></h1> |
| 147 |
<ul> |
| 148 |
<li><p class="first">An <tt class="docutils literal"><span class="pre">'AF_INET'</span></tt> address is a tuple of the form <tt class="docutils literal"><span class="pre">(hostname,</span> <span class="pre">port)</span></tt> |
| 149 |
where <tt class="docutils literal"><span class="pre">hostname</span></tt> is a string and <tt class="docutils literal"><span class="pre">port</span></tt> is an integer</p> |
| 150 |
</li> |
| 151 |
<li><p class="first">An <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> address is a string representing a filename on the |
| 152 |
filesystem.</p> |
| 153 |
</li> |
| 154 |
<li><p class="first">An <tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> address is a string of the form |
| 155 |
<tt class="docutils literal"><span class="pre">r'\\.\pipe\PipeName'</span></tt>.</p> |
| 156 |
<p>To use <tt class="docutils literal"><span class="pre">Client</span></tt> to connect to a named pipe on a remote computer |
| 157 |
called <tt class="docutils literal"><span class="pre">ServerName</span></tt> one should use an address of the form |
| 158 |
<tt class="docutils literal"><span class="pre">r'\\ServerName\pipe\PipeName'</span></tt> instead.</p> |
| 159 |
</li> |
| 160 |
</ul> |
| 161 |
<p>Note that any string beginning with two backslashes is assumed by |
| 162 |
default to be an <tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> address rather than an <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> |
| 163 |
address.</p> |
| 164 |
</div> |
| 165 |
<div class="section"> |
| 166 |
<h1><a id="authentication-keys" name="authentication-keys">Authentication keys</a></h1> |
| 167 |
<p>When one uses the <tt class="docutils literal"><span class="pre">recv()</span></tt> method of a connection object, the data |
| 168 |
received is automatically unpickled. Unfortunately unpickling data |
| 169 |
from an untrusted source is a security risk. Therefore <tt class="docutils literal"><span class="pre">Listener</span></tt> and |
| 170 |
<tt class="docutils literal"><span class="pre">Client</span></tt> use the <tt class="docutils literal"><span class="pre">hmac</span></tt> module to provide digest authentication.</p> |
| 171 |
<p>An authentication key is a string which can be thought of as a |
| 172 |
password: once a connection is established both ends will demand proof |
| 173 |
that the other knows the authentication key. (Demonstrating that both |
| 174 |
ends are using the same key does <em>not</em> involve sending the key over |
| 175 |
the connection.)</p> |
| 176 |
<p>If authentication is requested but do authentication key is specified |
| 177 |
then the return value of <tt class="docutils literal"><span class="pre">currentProcess().getAuthKey()</span></tt> is used (see |
| 178 |
<a class="reference" href="process-objects.html">Process objects</a>). This value will |
| 179 |
automatically inherited by any <tt class="docutils literal"><span class="pre">Process</span></tt> object that the current |
| 180 |
process creates. This means that (by default) all processes of a |
| 181 |
multi-process program will share a single authentication key which can |
| 182 |
be used when setting up connections between the themselves.</p> |
| 183 |
<p>Suitable authentication keys can also be generated by using |
| 184 |
<tt class="docutils literal"><span class="pre">os.urandom()</span></tt>.</p> |
| 185 |
</div> |
| 186 |
<div class="section"> |
| 187 |
<h1><a id="example" name="example">Example</a></h1> |
| 188 |
<p>The following server code creates a listener which uses <tt class="docutils literal"><span class="pre">'secret</span> |
| 189 |
<span class="pre">password'</span></tt> as an authentication key. It then waits for a connection |
| 190 |
and sends some data to the client:</p> |
| 191 |
<pre class="literal-block"> |
| 192 |
from processing.connection import Listener |
| 193 |
from array import array |
| 194 |
|
| 195 |
address = ('localhost', 6000) # family is deduced to be 'AF_INET' |
| 196 |
listener = Listener(address, authkey='secret password') |
| 197 |
|
| 198 |
conn = listener.accept() |
| 199 |
print 'connection accepted from', listener.last_accepted |
| 200 |
|
| 201 |
conn.send([2.25, None, 'junk', float]) |
| 202 |
|
| 203 |
conn.sendBytes('hello') |
| 204 |
|
| 205 |
conn.sendBytes(array('i', [42, 1729])) |
| 206 |
|
| 207 |
conn.close() |
| 208 |
listener.close() |
| 209 |
</pre> |
| 210 |
<p>The following code connects to the server and receives some data from |
| 211 |
the server:</p> |
| 212 |
<pre class="literal-block"> |
| 213 |
from processing.connection import Client |
| 214 |
from array import array |
| 215 |
|
| 216 |
address = ('localhost', 6000) |
| 217 |
conn = Client(address, authkey='secret password') |
| 218 |
|
| 219 |
print conn.recv() # => [2.25, None, 'junk', float] |
| 220 |
|
| 221 |
print conn.recvBytes() # => 'hello' |
| 222 |
|
| 223 |
arr = array('i', [0, 0, 0, 0, 0]) |
| 224 |
print conn.recvBytesInto(arr) # => 8 |
| 225 |
print arr # => array('i', [42, 1729, 0, 0, 0]) |
| 226 |
|
| 227 |
conn.close() |
| 228 |
</pre> |
| 229 |
</div> |
| 230 |
</div> |
| 231 |
<div class="footer"> |
| 232 |
<hr class="footer" /> |
| 233 |
<a class="reference" href="sharedctypes.html">Prev</a> <a class="reference" href="processing-ref.html">Up</a> <a class="reference" href="programming-guidelines.html">Next</a> |
| 234 |
</div> |
| 235 |
</body> |
| 236 |
</html> |