connection-ref.html 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236
  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> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <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. If the reply matches the digest of the message using `authkey`
  49. as the key then a welcome message is sent to the other end of
  50. the connection. Otherwise `AuthenticationError` is raised.
  51. `answerChallenge(connection, authkey)`
  52. Receives a message, calculates the digest of the message using
  53. `authkey` as the key, and then sends the digest back.
  54. If a welcome message is not received then
  55. `AuthenticationError` is raised. -->
  56. <p>The module exports two exception types:</p>
  57. <blockquote>
  58. <dl class="docutils">
  59. <dt><strong>exception</strong> <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt></dt>
  60. <dd>Exception raised when there is an authentication error.</dd>
  61. <dt><strong>exception</strong> <tt class="docutils literal"><span class="pre">BufferTooShort</span></tt></dt>
  62. <dd><p class="first">Exception raise by the <tt class="docutils literal"><span class="pre">recvBytesInto()</span></tt> method of a
  63. connection object when the supplied buffer object is too small
  64. for the message read.</p>
  65. <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
  66. give the message as a byte string.</p>
  67. </dd>
  68. </dl>
  69. </blockquote>
  70. </div>
  71. <div class="section">
  72. <h1><a id="listener-objects" name="listener-objects">Listener objects</a></h1>
  73. <p>Instances of <tt class="docutils literal"><span class="pre">Listener</span></tt> have the following methods:</p>
  74. <blockquote>
  75. <dl class="docutils">
  76. <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>
  77. <dd><dl class="first last docutils">
  78. <dt><tt class="docutils literal"><span class="pre">address</span></tt></dt>
  79. <dd>The address to be used by the bound socket
  80. or named pipe of the listener object.</dd>
  81. <dt><tt class="docutils literal"><span class="pre">family</span></tt></dt>
  82. <dd><p class="first">The type of the socket (or named pipe) to use.</p>
  83. <p>This can be one of the strings <tt class="docutils literal"><span class="pre">'AF_INET'</span></tt> (for a TCP
  84. socket), <tt class="docutils literal"><span class="pre">'AF_UNIX'</span></tt> (for a Unix domain socket) or
  85. <tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> (for a Windows named pipe). Of these only
  86. the first is guaranteed to be available.</p>
  87. <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
  88. 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
  89. default is chosen. This default is the family which is
  90. assumed to be the fastest available. See <a class="reference" href="#address-formats">Address
  91. formats</a>.</p>
  92. <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
  93. file will have only be readable/writable by the user
  94. running the current process -- use <tt class="docutils literal"><span class="pre">os.chmod()</span></tt> is you need
  95. to let other users access the socket.</p>
  96. </dd>
  97. <dt><tt class="docutils literal"><span class="pre">backlog</span></tt></dt>
  98. <dd>If the listener object uses a socket then <tt class="docutils literal"><span class="pre">backlog</span></tt> is
  99. passed to the <tt class="docutils literal"><span class="pre">listen()</span></tt> method of the socket once it has
  100. been bound.</dd>
  101. <dt><tt class="docutils literal"><span class="pre">authenticate</span></tt></dt>
  102. <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
  103. digest authentication is used.</dd>
  104. <dt><tt class="docutils literal"><span class="pre">authkey</span></tt></dt>
  105. <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
  106. authentication key; otherwise it must be <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
  107. <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
  108. <tt class="docutils literal"><span class="pre">currentProcess.getAuthKey()</span></tt> is used as the authentication
  109. key.</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">authentication</span></tt> is false then
  111. no authentication is done.</p>
  112. <p class="last">If authentication fails then <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is
  113. raised. See <a class="reference" href="#authentication-keys">Authentication keys</a>.</p>
  114. </dd>
  115. </dl>
  116. </dd>
  117. <dt><tt class="docutils literal"><span class="pre">accept()</span></tt></dt>
  118. <dd><p class="first">Accept a connection on the bound socket or named pipe of the
  119. listener object. If authentication is attempted and fails
  120. then <tt class="docutils literal"><span class="pre">AuthenticationError</span></tt> is raised.</p>
  121. <p class="last">Returns a <tt class="docutils literal"><span class="pre">connection</span> <span class="pre">object</span> <span class="pre">&lt;connection-object.html&gt;</span></tt> object.</p>
  122. </dd>
  123. <dt><tt class="docutils literal"><span class="pre">close()</span></tt></dt>
  124. <dd><p class="first">Close the bound socket or named pipe of the listener object.</p>
  125. <p class="last">This is called automatically when the listener is garbage
  126. collected. However it is advisable to call it explicitly.</p>
  127. </dd>
  128. </dl>
  129. </blockquote>
  130. <p>Listener objects have the following read-only properties:</p>
  131. <blockquote>
  132. <dl class="docutils">
  133. <dt><tt class="docutils literal"><span class="pre">address</span></tt></dt>
  134. <dd>The address which is being used by the listener object.</dd>
  135. <dt><tt class="docutils literal"><span class="pre">last_accepted</span></tt></dt>
  136. <dd><p class="first">The address from which the last accepted connection came.</p>
  137. <p class="last">If this is unavailable then <tt class="docutils literal"><span class="pre">None</span></tt> is returned.</p>
  138. </dd>
  139. </dl>
  140. </blockquote>
  141. </div>
  142. <div class="section">
  143. <h1><a id="address-formats" name="address-formats">Address formats</a></h1>
  144. <ul>
  145. <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>
  146. 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>
  147. </li>
  148. <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
  149. filesystem.</p>
  150. </li>
  151. <li><p class="first">An <tt class="docutils literal"><span class="pre">'AF_PIPE'</span></tt> address is a string of the form
  152. <tt class="docutils literal"><span class="pre">r'\\.\pipe\PipeName'</span></tt>.</p>
  153. <p>To use <tt class="docutils literal"><span class="pre">Client</span></tt> to connect to a named pipe on a remote computer
  154. called <tt class="docutils literal"><span class="pre">ServerName</span></tt> one should use an address of the form
  155. <tt class="docutils literal"><span class="pre">r'\\ServerName\pipe\PipeName'</span></tt> instead.</p>
  156. </li>
  157. </ul>
  158. <p>Note that any string beginning with two backslashes is assumed by
  159. 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>
  160. address.</p>
  161. </div>
  162. <div class="section">
  163. <h1><a id="authentication-keys" name="authentication-keys">Authentication keys</a></h1>
  164. <p>When one uses the <tt class="docutils literal"><span class="pre">recv()</span></tt> method of a connection object, the data
  165. received is automatically unpickled. Unfortunately unpickling data
  166. from an untrusted source is a security risk. Therefore <tt class="docutils literal"><span class="pre">Listener</span></tt> and
  167. <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>
  168. <p>An authentication key is a string which can be thought of as a
  169. password: once a connection is established both ends will demand proof
  170. that the other knows the authentication key. (Demonstrating that both
  171. ends are using the same key does <em>not</em> involve sending the key over
  172. the connection.)</p>
  173. <p>If authentication is requested but do authentication key is specified
  174. then the return value of <tt class="docutils literal"><span class="pre">currentProcess().getAuthKey()</span></tt> is used (see
  175. <a class="reference" href="process-objects.html">Process objects</a>). This value will
  176. automatically inherited by any <tt class="docutils literal"><span class="pre">Process</span></tt> object that the current
  177. process creates. This means that (by default) all processes of a
  178. multi-process program will share a single authentication key which can
  179. be used when setting up connections between the themselves.</p>
  180. <p>Suitable authentication keys can also be generated by using
  181. <tt class="docutils literal"><span class="pre">os.urandom()</span></tt>.</p>
  182. </div>
  183. <div class="section">
  184. <h1><a id="example" name="example">Example</a></h1>
  185. <p>The following server code creates a listener which uses <tt class="docutils literal"><span class="pre">'secret</span>
  186. <span class="pre">password'</span></tt> as an authentication key. It then waits for a connection
  187. and sends some data to the client:</p>
  188. <pre class="literal-block">
  189. from processing.connection import Listener
  190. from array import array
  191. address = ('localhost', 6000) # family is deduced to be 'AF_INET'
  192. listener = Listener(address, authkey='secret password')
  193. conn = listener.accept()
  194. print 'connection accepted from', listener.last_accepted
  195. conn.send([2.25, None, 'junk', float])
  196. conn.sendBytes('hello')
  197. conn.sendBytes(array('i', [42, 1729]))
  198. conn.close()
  199. listener.close()
  200. </pre>
  201. <p>The following code connects to the server and receives some data from
  202. the server:</p>
  203. <pre class="literal-block">
  204. from processing.connection import Client
  205. from array import array
  206. address = ('localhost', 6000)
  207. conn = Client(address, authkey='secret password')
  208. print conn.recv() # =&gt; [2.25, None, 'junk', float]
  209. print conn.recvBytes() # =&gt; 'hello'
  210. arr = array('i', [0, 0, 0, 0, 0])
  211. print conn.recvBytesInto(arr) # =&gt; 8
  212. print arr # =&gt; array('i', [42, 1729, 0, 0, 0])
  213. conn.close()
  214. </pre>
  215. </div>
  216. </div>
  217. <div class="footer">
  218. <hr class="footer" />
  219. <a class="reference" href="sharedctypes.html">Prev</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="processing-ref.html">Up</a> &nbsp; &nbsp; &nbsp; &nbsp; <a class="reference" href="programming-guidelines.html">Next</a>
  220. </div>
  221. </body>
  222. </html>