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