314 lines
22 KiB
HTML
314 lines
22 KiB
HTML
|
|
<!doctype html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<html><head><title>Python: module i2p.samclasses</title>
|
|
</head><body bgcolor="#f0f0f8">
|
|
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="heading">
|
|
<tr bgcolor="#7799ee">
|
|
<td valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"> <br><big><big><strong><a href="i2p.html"><font color="#ffffff">i2p</font></a>.samclasses</strong></big></big></font></td
|
|
><td align=right valign=bottom
|
|
><font color="#ffffff" face="helvetica, arial"><a href=".">index</a><br><a href="file:///D|/code/i2p/i2p/samclasses.py">d:\code\i2p\i2p\samclasses.py</a></font></td></tr></table>
|
|
<p><tt>Lower-level SAM API, interfaces with SAM Bridge.<br>
|
|
<br>
|
|
For internal use only.<br>
|
|
<br>
|
|
Use the higher level i2p.sam module for your own programs.<br>
|
|
<br>
|
|
For details on SAM, see "Simple Anonymous Messaging (SAM) v1.0,"<br>
|
|
as published by jrandom.<br>
|
|
<br>
|
|
Class Overview:<br>
|
|
<br>
|
|
<a href="#SAMTerminal">SAMTerminal</a>: Message sender/reader, talks to SAM Bridge<br>
|
|
through a single socket.<br>
|
|
<a href="#StringBuffer">StringBuffer</a>: Queue for character data.<br>
|
|
<a href="#BaseSession">BaseSession</a>: SAM session classes are derived from this.<br>
|
|
<a href="#StreamSession">StreamSession</a>: Manipulate a SAM stream session through a<br>
|
|
threadsafe, high-level interface.<br>
|
|
<a href="#DatagramSession">DatagramSession</a>: SAM datagram session, threadsafe, high level.<br>
|
|
<a href="#RawSession">RawSession</a>: SAM raw session, threadsafe, high level.<br>
|
|
<br>
|
|
Note that a 'None' timeout is an infinite timeout: it<br>
|
|
blocks forever if necessary.<br>
|
|
<br>
|
|
Todo:<br>
|
|
* Error handling is a huge mess. Neaten it up.<br>
|
|
Subclass a ErrorMixin class, then use set_error(e),<br>
|
|
check_error(), get_error().<br>
|
|
* Streams are a huge mess. Neaten them up.<br>
|
|
* This whole interface is a tad confusing. Neaten it up.</tt></p>
|
|
<p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#aa55cc">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#fffff" face="helvetica, arial"><big><strong>Modules</strong></big></font></td></tr>
|
|
|
|
<tr><td bgcolor="#aa55cc"><tt> </tt></td><td> </td>
|
|
<td width="100%"><table width="100%" summary="list"><tr><td width="25%" valign=top><a href="Queue.html">Queue</a><br>
|
|
<a href="i2p.html">i2p</a><br>
|
|
<a href="random.html">random</a><br>
|
|
</td><td width="25%" valign=top><a href="shlex.html">shlex</a><br>
|
|
<a href="socket.html">socket</a><br>
|
|
<a href="string.html">string</a><br>
|
|
</td><td width="25%" valign=top><a href="sys.html">sys</a><br>
|
|
<a href="thread.html">thread</a><br>
|
|
<a href="threading.html">threading</a><br>
|
|
</td><td width="25%" valign=top><a href="time.html">time</a><br>
|
|
<a href="traceback.html">traceback</a><br>
|
|
</td></tr></table></td></tr></table><p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ee77aa">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"><big><strong>Classes</strong></big></font></td></tr>
|
|
|
|
<tr><td bgcolor="#ee77aa"><tt> </tt></td><td> </td>
|
|
<td width="100%"><dl>
|
|
<dt><font face="helvetica, arial"><a href="i2p.samclasses.html#BaseSession">BaseSession</a>
|
|
</font></dt><dd>
|
|
<dl>
|
|
<dt><font face="helvetica, arial"><a href="i2p.samclasses.html#DatagramSession">DatagramSession</a>
|
|
</font></dt><dt><font face="helvetica, arial"><a href="i2p.samclasses.html#RawSession">RawSession</a>
|
|
</font></dt><dt><font face="helvetica, arial"><a href="i2p.samclasses.html#StreamSession">StreamSession</a>
|
|
</font></dt></dl>
|
|
</dd>
|
|
<dt><font face="helvetica, arial"><a href="i2p.samclasses.html#Deque">Deque</a>
|
|
</font></dt><dd>
|
|
<dl>
|
|
<dt><font face="helvetica, arial"><a href="i2p.samclasses.html#StringBuffer">StringBuffer</a>
|
|
</font></dt></dl>
|
|
</dd>
|
|
<dt><font face="helvetica, arial"><a href="i2p.samclasses.html#SAMTerminal">SAMTerminal</a>
|
|
</font></dt><dt><font face="helvetica, arial"><a href="i2p.samclasses.html#Stream">Stream</a>
|
|
</font></dt></dl>
|
|
<p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="BaseSession">class <strong>BaseSession</strong></a></font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>Base session, from which <a href="#StreamSession">StreamSession</a>, <a href="#DatagramSession">DatagramSession</a>,<br>
|
|
and <a href="#RawSession">RawSession</a> are derived.<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="BaseSession-__init__"><strong>__init__</strong></a>(self, addr<font color="#909090">=''</font>)</dt></dl>
|
|
|
|
<dl><dt><a name="BaseSession-close"><strong>close</strong></a>(self)</dt><dd><tt>Close the session.</tt></dd></dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="DatagramSession">class <strong>DatagramSession</strong></a>(<a href="i2p.samclasses.html#BaseSession">BaseSession</a>)</font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>Datagram session. All methods are blocking and threadsafe.<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="DatagramSession-__init__"><strong>__init__</strong></a>(self, name, addr<font color="#909090">=''</font>, **kwargs)</dt></dl>
|
|
|
|
<dl><dt><a name="DatagramSession-__len__"><strong>__len__</strong></a>(self)</dt><dd><tt>Number of packets in read buffer.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="DatagramSession-recv"><strong>recv</strong></a>(self, timeout<font color="#909090">=None</font>, peek<font color="#909090">=False</font>)</dt><dd><tt>Get a single packet. Blocks for up to timeout seconds if<br>
|
|
n > 0 and no packet is available (timeout=None means wait<br>
|
|
forever). If still no packet is available, raises BlockError<br>
|
|
or Timeout. Returns the pair (data, address). If peek is<br>
|
|
True, the data is not removed.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="DatagramSession-send"><strong>send</strong></a>(self, s, dest)</dt><dd><tt>Send packet with contents s to given destination.</tt></dd></dl>
|
|
|
|
<hr>
|
|
Methods inherited from <a href="i2p.samclasses.html#BaseSession">BaseSession</a>:<br>
|
|
<dl><dt><a name="DatagramSession-close"><strong>close</strong></a>(self)</dt><dd><tt>Close the session.</tt></dd></dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="Deque">class <strong>Deque</strong></a></font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>A double-ended queue.<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="Deque-__init__"><strong>__init__</strong></a>(self)</dt></dl>
|
|
|
|
<dl><dt><a name="Deque-__len__"><strong>__len__</strong></a>(self)</dt><dd><tt>Number of items in the deque.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="Deque-pop_first"><strong>pop_first</strong></a>(self)</dt><dd><tt>Pop an item off the beginning of the deque, and return it.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="Deque-pop_last"><strong>pop_last</strong></a>(self)</dt><dd><tt>Pop an item off the end of the deque, and return it.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="Deque-push_first"><strong>push_first</strong></a>(self, obj)</dt><dd><tt>Prepend obj to the beginning of the deque.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="Deque-push_last"><strong>push_last</strong></a>(self, obj)</dt><dd><tt>Append obj to the end of the deque.</tt></dd></dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="RawSession">class <strong>RawSession</strong></a>(<a href="i2p.samclasses.html#BaseSession">BaseSession</a>)</font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>Raw session. All methods are blocking and threadsafe.<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="RawSession-__init__"><strong>__init__</strong></a>(self, name, addr<font color="#909090">=''</font>, **kwargs)</dt></dl>
|
|
|
|
<dl><dt><a name="RawSession-__len__"><strong>__len__</strong></a>(self)</dt><dd><tt>Number of packets in read buffer.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="RawSession-recv"><strong>recv</strong></a>(self, timeout<font color="#909090">=None</font>, peek<font color="#909090">=False</font>)</dt><dd><tt>Identical to DatagramSocket.recv. The from address is an<br>
|
|
empty string.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="RawSession-send"><strong>send</strong></a>(self, s, dest)</dt><dd><tt>Send packet with contents s to given destination.</tt></dd></dl>
|
|
|
|
<hr>
|
|
Methods inherited from <a href="i2p.samclasses.html#BaseSession">BaseSession</a>:<br>
|
|
<dl><dt><a name="RawSession-close"><strong>close</strong></a>(self)</dt><dd><tt>Close the session.</tt></dd></dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="SAMTerminal">class <strong>SAMTerminal</strong></a></font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>Message-by-message communication with SAM through a single<br>
|
|
socket. _on_* messages are dispatched to msgobj.<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="SAMTerminal-__init__"><strong>__init__</strong></a>(self, addr, msgobj)</dt></dl>
|
|
|
|
<dl><dt><a name="SAMTerminal-check"><strong>check</strong></a>(self)</dt><dd><tt>Raise an error if terminal was closed, otherwise do<br>
|
|
nothing.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="SAMTerminal-check_message"><strong>check_message</strong></a>(self, kwargs)</dt><dd><tt>Raises an error if kwargs['RESULT'] != 'OK'.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="SAMTerminal-close"><strong>close</strong></a>(self)</dt><dd><tt>Close the SAM terminal.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="SAMTerminal-on_message"><strong>on_message</strong></a>(self, msg, kwargs)</dt><dd><tt>Process a SAM message that was received. Dispatch to<br>
|
|
_on_MESSAGE_NAME(**kwargs).</tt></dd></dl>
|
|
|
|
<dl><dt><a name="SAMTerminal-queue_get"><strong>queue_get</strong></a>(self, q)</dt><dd><tt>Identical to q.get() unless a call to <a href="#SAMTerminal-check">check</a>() fails,<br>
|
|
in which case the waiting is cut short with an error.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="SAMTerminal-send_message"><strong>send_message</strong></a>(self, msg)</dt><dd><tt>Send a message to the SAM bridge. A newline will be<br>
|
|
automatically added if none is present.</tt></dd></dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="Stream">class <strong>Stream</strong></a></font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>Receives and sends data for an individual stream.<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="Stream-__del__"><strong>__del__</strong></a>(self)</dt></dl>
|
|
|
|
<dl><dt><a name="Stream-__init__"><strong>__init__</strong></a>(self, parent, remotedest, id, didconnect<font color="#909090">=True</font>)</dt></dl>
|
|
|
|
<dl><dt><a name="Stream-__len__"><strong>__len__</strong></a>(self)</dt><dd><tt>Current length of read buffer.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="Stream-close"><strong>close</strong></a>(self)</dt><dd><tt>Close the stream. Threadsafe.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="Stream-on_close"><strong>on_close</strong></a>(self, e)</dt></dl>
|
|
|
|
<dl><dt><a name="Stream-on_receive"><strong>on_receive</strong></a>(self, s)</dt></dl>
|
|
|
|
<dl><dt><a name="Stream-recv"><strong>recv</strong></a>(self, n, timeout<font color="#909090">=None</font>, peek<font color="#909090">=False</font>, waitall<font color="#909090">=False</font>)</dt><dd><tt>Reads up to n bytes in a manner identical to socket.recv.<br>
|
|
Blocks for up to timeout seconds if n > 0 and no data is<br>
|
|
available (timeout=None means wait forever). If still no data<br>
|
|
is available, raises BlockError or Timeout. For a closed<br>
|
|
stream, recv will read the data stored in the buffer until<br>
|
|
EOF, at which point the read data will be truncated. If peek<br>
|
|
is True, the data is not removed. If waitall is True, reads<br>
|
|
exactly n bytes, or raises BlockError or Timeout as<br>
|
|
appropriate. Returns data.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="Stream-send"><strong>send</strong></a>(self, s)</dt><dd><tt>Sends the string s, blocking if necessary.</tt></dd></dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="StreamSession">class <strong>StreamSession</strong></a>(<a href="i2p.samclasses.html#BaseSession">BaseSession</a>)</font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt><a href="#Stream">Stream</a> session. All methods are blocking and threadsafe.<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="StreamSession-__init__"><strong>__init__</strong></a>(self, name, addr<font color="#909090">=''</font>, **kwargs)</dt></dl>
|
|
|
|
<dl><dt><a name="StreamSession-__len__"><strong>__len__</strong></a>(self)</dt><dd><tt>Unconnected session; has no read data available.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StreamSession-accept"><strong>accept</strong></a>(self, timeout<font color="#909090">=None</font>)</dt><dd><tt>Wait for incoming connection, and return a <a href="#Stream">Stream</a> object<br>
|
|
for it.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StreamSession-connect"><strong>connect</strong></a>(self, dest, timeout<font color="#909090">=None</font>)</dt><dd><tt>Create a stream connected to remote destination 'dest'. The<br>
|
|
id is random. If the timeout is exceeded, do NOT raise an<br>
|
|
error; rather, return a <a href="#Stream">Stream</a> object with .didconnect set<br>
|
|
to False.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StreamSession-listen"><strong>listen</strong></a>(self, backlog)</dt><dd><tt>Set maximum number of queued connections.</tt></dd></dl>
|
|
|
|
<hr>
|
|
Methods inherited from <a href="i2p.samclasses.html#BaseSession">BaseSession</a>:<br>
|
|
<dl><dt><a name="StreamSession-close"><strong>close</strong></a>(self)</dt><dd><tt>Close the session.</tt></dd></dl>
|
|
|
|
</td></tr></table> <p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#ffc8d8">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#000000" face="helvetica, arial"><a name="StringBuffer">class <strong>StringBuffer</strong></a>(<a href="i2p.samclasses.html#Deque">Deque</a>)</font></td></tr>
|
|
|
|
<tr bgcolor="#ffc8d8"><td rowspan=2><tt> </tt></td>
|
|
<td colspan=2><tt>A FIFO for characters. Strings can be efficiently<br>
|
|
appended to the end, and read from the beginning.<br>
|
|
<br>
|
|
Example:<br>
|
|
B = <a href="#StringBuffer">StringBuffer</a>('Hello W')<br>
|
|
B.<a href="#StringBuffer-append">append</a>('orld!')<br>
|
|
print B.<a href="#StringBuffer-read">read</a>(5) # 'Hello'<br>
|
|
print B.<a href="#StringBuffer-read">read</a>() # 'World!'<br> </tt></td></tr>
|
|
<tr><td> </td>
|
|
<td width="100%">Methods defined here:<br>
|
|
<dl><dt><a name="StringBuffer-__init__"><strong>__init__</strong></a>(self, s<font color="#909090">=''</font>)</dt></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-__len__"><strong>__len__</strong></a>(self)</dt></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-__repr__"><strong>__repr__</strong></a>(self)</dt></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-__str__"><strong>__str__</strong></a>(self)</dt></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-append"><strong>append</strong></a>(self, s)</dt><dd><tt>Append string data to the end of the buffer.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-peek"><strong>peek</strong></a>(self, n<font color="#909090">=None</font>)</dt><dd><tt>Like <a href="#StringBuffer-read">read</a>(), but do not remove the data that is returned.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-prepend"><strong>prepend</strong></a>(self, s)</dt><dd><tt>Prepend string data to the beginning of the buffer.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-read"><strong>read</strong></a>(self, n<font color="#909090">=None</font>)</dt><dd><tt>Read n bytes of data (or less if less data available) from the<br>
|
|
beginning of the buffer. The data is removed. If n is<br>
|
|
omitted, read the entire buffer.</tt></dd></dl>
|
|
|
|
<hr>
|
|
Methods inherited from <a href="i2p.samclasses.html#Deque">Deque</a>:<br>
|
|
<dl><dt><a name="StringBuffer-pop_first"><strong>pop_first</strong></a>(self)</dt><dd><tt>Pop an item off the beginning of the deque, and return it.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-pop_last"><strong>pop_last</strong></a>(self)</dt><dd><tt>Pop an item off the end of the deque, and return it.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-push_first"><strong>push_first</strong></a>(self, obj)</dt><dd><tt>Prepend obj to the beginning of the deque.</tt></dd></dl>
|
|
|
|
<dl><dt><a name="StringBuffer-push_last"><strong>push_last</strong></a>(self, obj)</dt><dd><tt>Append obj to the end of the deque.</tt></dd></dl>
|
|
|
|
</td></tr></table></td></tr></table><p>
|
|
<table width="100%" cellspacing=0 cellpadding=2 border=0 summary="section">
|
|
<tr bgcolor="#55aa55">
|
|
<td colspan=3 valign=bottom> <br>
|
|
<font color="#ffffff" face="helvetica, arial"><big><strong>Data</strong></big></font></td></tr>
|
|
|
|
<tr><td bgcolor="#55aa55"><tt> </tt></td><td> </td>
|
|
<td width="100%"><strong>sam_log</strong> = False</td></tr></table>
|
|
</body></html> |