Source

pyliblo / doc / API.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html lang="en">

<head>
  <title>pyliblo - API Documentation</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <style type="text/css">
    body { max-width: 60em; font-size: 90%; font-family: sans-serif; }
    h1 { font-size: 130%; color: #333; background: #eee; padding: 4px 0.7em; }
    h2 { font-size: 110%; color: #fff; background: #667; padding: 4px 0.7em; margin-top: 1.5em; }
    h3 { font-size: 100%; color: #333; padding-left: 0.5em; margin-bottom: 0.4em; }
    p,table,pre { margin-left: 0.8em; margin-top: 0.4em; }
    b { color: #333; }
    pre { font-size: 110%; }
    table { border: 1px solid #333; border-collapse: collapse; }
    th, td { border: 1px solid #333; padding: 0em 0.3em; }
    th { color: #333; text-align: left; background: #eee; }
  </style>
</head>

<body>

<h1>pyliblo 0.8 - API Documentation</h1>

<p>
For the most part, pyliblo is just a thin wrapper around liblo, which does all the real work.
For questions not answered here, also see the
<a href="http://liblo.sourceforge.net/docs/modules.html">liblo documentation</a>.
</p>

<p>
The Python module is simply called <b>liblo</b>.
</p>


<h2>functions</h2>

<h3>send(target, message)<br>
send(target, bundle)<br>
send(target, path[, arg, ...])</h3>
<p>
Sends a message or bundle to the the given target, without requiring a server.<br>
target may be an <b>Address</b> object, a port number, a (hostname, port) tuple, or a URL.<br>
Exceptions: <b>AddressError</b>
</p>

<h3>time()</h3>
<p>
Returns the current time as a float in OSC format, that is, the number of seconds since
the epoch (January 1, 1900).
</p>


<h2>class Server</h2>

<h3>Server([port[, proto[, **kwargs]]])</h3>
<p>
Creates a new <b>Server</b> object, which can receive OSC messages.<br>
port may be a decimal port number or a UNIX socket path.
If omitted, an arbitrary free UDP port will be used.<br>
proto can be one of the constants UDP, TCP, UNIX.<br>
Optional keyword arguments:<br>
<b>reg_methods</b>: False if you don't want the init function to automatically
register callbacks defined with the @make_method decorator.<br>
Exceptions: <b>ServerError</b>
</p>

<h3>add_method(path, typespec, callback_func[, user_data])</h3>
<p>
Registers a callback function for OSC messages with matching path and argument types.<br>
For both path and typespec, None may be used as a wildcard.<br>
The optional user_data will be passed on to the callback function.
callback_func may be a global function or a class method, pyliblo will know what to do either way.
</p>

<h3>@make_method(path, typespec[, user_data])</h3>
<p>
Decorator function that basically serves the same purpose as add_method().
Decorators require Python 2.4 or later.<br>
Note that @make_method is defined at module scope, and not a member of class Server.
</p>

<h3>register_methods([obj])</h3>
<p>
Calls add_method() for all methods of obj decorated with @make_method. obj defaults to
the Server object itself.<br>
This function is called automatically by the Server's init function, unless its reg_methods
parameter is False.
</p>

<h3>my_callback(path, args[, types[, src[, user_data]]])<br>
my_callback(self, path, args[, types[, src[, user_data]]])</h3>
<p>
User-defined callback function, to be registered using add_method() or @make_method;
called when a matching OSC message is received.<br>
args will be a list of message arguments, using appropriate built-in Python data types.
types is a string with the typespec of the message.
src is an <b>Address</b> object, containing the address the message came from.
types, src and user_data may be omitted if not needed.<br>
The callback should return zero (or nothing/None) if the message has been dealt with correctly,
or non-zero to look for another matching message handler.
</p>

<h3>recv([timeout])</h3>
<p>
Receives and dispatches one OSC message.
Blocking by default, unless timeout (in ms) is specified.<br>
timeout may be 0, in which case recv() returns immediately.
Returns True if a message was received, False otherwise.
</p>

<h3>send(target, message)<br>
send(target, bundle)<br>
send(target, path[, arg, ...])</h3>
<p>
Sends a message or bundle from this server to the the given target.<br>
target may be an <b>Address</b> object, a port number, a (hostname, port) tuple, or a URL.<br>
Exceptions: <b>AddressError</b>
</p>

<h3>get_url()</h3>
<p>
Returns the server's URL.
</p>

<h3>get_port()</h3>
<p>
Returns the server's port number.
</p>

<h3>get_protocol()</h3>
<p>
Returns the server's protocol (one of the constants UDP, TCP, UNIX).
</p>


<h2>class ServerThread</h2>
<p>
Unlike <b>Server</b>, <b>ServerThread</b> uses its own thread which runs in the background
to dispatch messages. Note that callback methods will not be run in the main Python thread!<br>
<b>ServerThread</b> has the same methods as <b>Server</b>, with the exception of recv().
Instead, it defines these two methods:
</p>

<h3>start()</h3>
<p>
Starts the server thread, liblo will now start to dispatch any messages it receives.
</p>

<h3>stop()</h3>
<p>
Stops the server thread.
</p>


<h2>class Address</h2>

<h3>Address(hostname, port)<br>
Address(port)<br>
Address(url)</h3>
<p>
Creates a new <b>Address</b> object from the given hostname/port or URL.<br>
Exceptions: <b>AddressError</b>
</p>

<h3>get_url()</h3>
<p>
Returns the address' URL.
</p>

<h3>get_hostname()</h3>
<p>
Returns the address' hostname.
</p>

<h3>get_port()</h3>
<p>
Returns the address' port number.
</p>

<h3>get_protocol()</h3>
<p>
Returns the address' protocol (one of the constants UDP, TCP, UNIX).
</p>


<h2>class Message</h2>

<h3>Message(path[, arg, ...])</h3>
<p>
Creates a new <b>Message</b> object.
</p>

<h3>add(arg[, ...])</h3>
<p>
Appends the given argument(s) to the message.
</p>


<h2>class Bundle</h2>

<h3>Bundle([timetag, ][message, ...])</h3>
<p>
Creates a new <b>Bundle</b> object. You can optionally specify a time at which the messages should
be dispatched (as an OSC timetag float), and any number of messages to be included in the bundle.<br>
</p>

<h3>add(message[, ...])<br>
add(path[, arg, ...])</h3>
<p>
Adds one or more messages to the bundle.
</p>

<h2>mapping between OSC and Python data types</h2>
<p>
When constructing a message, pyliblo tries to automatically convert arguments to an appropriate
OSC data type, depending on the Python argument.
To explicitly specify the OSC data type to be transmitted, pass a (typetag, data) tuple.
Some types can't be unambiguously recognized, so they can only be sent that way.<br>
Callback functions always receive their arguments according to the following table:
</p>
<table border="1">
  <tr><th>typetag</th><th>OSC data type</th><th>Python data type</th></tr>
  <tr><td>'i'</td><td>int32</td><td>int</td></tr>
  <tr><td>'h'</td><td>int64</td><td>long</td></tr>
  <tr><td>'f'</td><td>float</td><td>float</td></tr>
  <tr><td>'d'</td><td>double</td><td>float</td></tr>
  <tr><td>'c'</td><td>char</td><td>single-character string</td></tr>
  <tr><td>'s'</td><td>string</td><td>string</td></tr>
  <tr><td>'S'</td><td>symbol</td><td>string</td></tr>
  <tr><td>'m'</td><td>midi</td><td>4-tuple of ints</td></tr>
  <tr><td>'t'</td><td>timetag</td><td>float</td></tr>
  <tr><td>'T'</td><td>true</td><td>-</td></tr>
  <tr><td>'F'</td><td>false</td><td>-</td></tr>
  <tr><td>'N'</td><td>nil</td><td>-</td></tr>
  <tr><td>'I'</td><td>infinitum</td><td>-</td></tr>
  <tr><td>'b'</td><td>blob</td><td>list of ints</td></tr>
</table>

</body>

</html>