OSC.py Extrait de help
De Centre de Ressources Numériques - Association Labomedia
Extrait de run 'pydoc OSC' from within the 'pyOSC' directory Version de 2008
DESCRIPTION
This module contains an OpenSoundControl implementation (in Pure Python), based (somewhat) on the
good old 'SimpleOSC' implementation by Daniel Holth & Clinton McChesney.
This implementation is intended to still be 'Simple' to the user, but much more complete
(with OSCServer & OSCClient classes) and much more powerful
(the OSCMultiClient supports subscriptions & message-filtering,
OSCMessage & OSCBundle are now proper container-types)
================
OpenSoundControl
================
OpenSoundControl is a network-protocol for sending (small) packets of addressed data over network sockets.
This OSC-implementation uses the UDP/IP protocol for sending and receiving packets.
(Although it is theoretically possible to send OSC-packets over TCP, almost all known implementations use UDP)
OSC-packets come in two kinds
- OSC-messages consist of an 'address'-string (not to be confused with a (hostport) network-address!),
followed by a string of 'typetags' associated with the message's arguments (ie. 'payload'),
and finally the arguments themselves, encoded in an OSC-specific way.
The OSCMessage class makes it easy to create & manipulate OSC-messages of this kind in a 'pythonesque' way
(that is, OSCMessage-objects behave a lot like lists)
- OSC-bundles are a special type of OSC-message containing only OSC-messages as 'payload'. Recursively.
(meaning; an OSC-bundle could contain other OSC-bundles, containing OSC-bundles etc.)
OSC-bundles start with the special keyword '#bundle' and do not have an OSC-address. (but the OSC-messages
a bundle contains will have OSC-addresses!)
Also, an OSC-bundle can have a timetag, essentially telling the receiving Server to 'hold' the bundle until
the specified time.
The OSCBundle class allows easy cration & manipulation of OSC-bundles.
see also http//opensoundcontrol.org/spec-1_0
---------
To send OSC-messages, you need an OSCClient, and to receive OSC-messages you need an OSCServer.
The OSCClient uses an 'AF_INET / SOCK_DGRAM' type socket (see the 'socket' module) to send
binary representations of OSC-messages to a remote hostport address.
The OSCServer listens on an 'AF_INET / SOCK_DGRAM' type socket bound to a local port, and handles
incoming requests. Either one-after-the-other (OSCServer) or in a multi-threaded / multi-process fashion
(ThreadingOSCServer / ForkingOSCServer). If the Server has a callback-function (a.k.a. handler) registered
to 'deal with' (i.e. handle) the received message's OSC-address, that function is called, passing it the (decoded) message
The different OSCServers implemented here all support the (recursive) un-bundling of OSC-bundles,
and OSC-bundle timetags.
In fact, this implementation supports
- OSC-messages with 'i' (int32), 'f' (float32), 's' (string) and 'b' (blob / binary data) types
- OSC-bundles, including timetag-support
- OSC-address patterns including '*', '?', '{,}' and '[]' wildcards.
(please *do* read the OSC-spec! http//opensoundcontrol.org/spec-1_0 it explains what these things mean.)
In addition, the OSCMultiClient supports
- Sending a specific OSC-message to multiple remote servers
- Remote server subscription / unsubscription (through OSC-messages, of course)
- Message-address filtering.
---------
Stock, V2_Lab, Rotterdam, 2008
----------
Changelog
----------
v0.3.0 - 27 Dec. 2007
Started out to extend the 'SimpleOSC' implementation (v0.2.3) by Daniel Holth & Clinton McChesney.
Rewrote OSCMessage
Added OSCBundle
v0.3.1 - 3 Jan. 2008
Added OSClient
Added OSCRequestHandler, loosely based on the original CallbackManager
Added OSCServer
Removed original CallbackManager
Adapted testing-script (the 'if __name__ == "__main__"' block at the end) to use new Server & Client
v0.3.2 - 5 Jan. 2008
Added 'container-type emulation' methods (getitem(), setitem(), __iter__() & friends) to OSCMessage
Added ThreadingOSCServer & ForkingOSCServer
- 6 Jan. 2008
Added OSCMultiClient
Added command-line options to testing-script (try 'python OSC.py --help')
v0.3.3 - 9 Jan. 2008
Added OSC-timetag support to OSCBundle & OSCRequestHandler
Added ThreadingOSCRequestHandler
v0.3.4 - 13 Jan. 2008
Added message-filtering to OSCMultiClient
Added subscription-handler to OSCServer
Added support fon numpy/scipy int & float types. (these get converted to 'standard' 32-bit OSC ints / floats!)
Cleaned-up and added more Docstrings
v0.3.5 - 14 aug. 2008
Added OSCServer.reportErr(...) method
-----------------
Original Comments
-----------------
> Open SoundControl for Python
> Copyright (C) 2002 Daniel Holth, Clinton McChesney
>
> This library is free software; you can redistribute it and/or modify it under
> the terms of the GNU Lesser General Public License as published by the Free
> Software Foundation; either version 2.1 of the License, or (at your option) any
> later version.
>
> This library is distributed in the hope that it will be useful, but WITHOUT ANY
> WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
> PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
> details.
> You should have received a copy of the GNU Lesser General Public License along
> with this library; if not, write to the Free Software Foundation, Inc., 59
> Temple Place, Suite 330, Boston, MA 02111-1307 USA
> For questions regarding this module contact Daniel Holth <dholth@stetson.edu>
> or visit http//www.stetson.edu/~ProctoLogic/
> Changelog
> 15 Nov. 2001
> Removed dependency on Python 2.0 features.
> - dwh
> 13 Feb. 2002
> Added a generic callback handler.
> - dwh
CLASSES
SocketServer.DatagramRequestHandler(SocketServer.BaseRequestHandler)
OSCRequestHandler
ThreadingOSCRequestHandler
SocketServer.ForkingMixIn
ForkingOSCServer(SocketServer.ForkingMixIn, OSCServer)
SocketServer.ThreadingMixIn
ThreadingOSCServer(SocketServer.ThreadingMixIn, OSCServer)
SocketServer.UDPServer(SocketServer.TCPServer)
OSCServer
ForkingOSCServer(SocketServer.ForkingMixIn, OSCServer)
ThreadingOSCServer(SocketServer.ThreadingMixIn, OSCServer)
__builtin__.object
OSCClient
OSCMultiClient
OSCMessage
OSCBundle
exceptions.Exception(exceptions.BaseException)
OSCError
OSCClientError
NotSubscribedError
OSCServerError
NoCallbackError
class ForkingOSCServer(SocketServer.ForkingMixIn, OSCServer)
| An Asynchronous OSCServer.
| This server forks a new process to handle each incoming request.
|
| Method resolution order
| ForkingOSCServer
| SocketServer.ForkingMixIn
| OSCServer
| SocketServer.UDPServer
| SocketServer.TCPServer
| SocketServer.BaseServer
|
| Data and other attributes defined here
|
| RequestHandlerClass = <class OSC.ThreadingOSCRequestHandler>
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.ForkingMixIn
|
| collect_children(self)
| Internal routine to wait for children that have exited.
|
| handle_timeout(self)
| Wait for zombies after self.timeout seconds of inactivity.
|
| May be extended, do not override.
|
| process_request(self, request, client_address)
| Fork a new subprocess to process the request.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.ForkingMixIn
|
| active_children = None
|
| max_children = 40
|
| timeout = 300
|
| ----------------------------------------------------------------------
| Methods inherited from OSCServer
|
| addDefaultHandlers(self, prefix='', info_prefix='/info', error_prefix='/error')
| Register a default set of OSC-address handlers with this Server
| - 'default' -> noCallback_handler
| the given prefix is prepended to all other callbacks registered by this method
| - '<prefix><info_prefix' -> serverInfo_handler
| - '<prefix><error_prefix> -> msgPrinter_handler
| - '<prefix>/print' -> msgPrinter_handler
| and, if the used Client supports it;
| - '<prefix>/subscribe' -> subscription_handler
| - '<prefix>/unsubscribe' -> subscription_handler
|
| Note the given 'error_prefix' argument is also set as default 'error_prefix' for error-messages
| *sent from* this server. This is ok, because error-messages generally do not elicit a reply from the receiver.
|
| To do this with the serverInfo-prefixes would be a bad idea, because if a request received on '/info' (for example)
| would send replies to '/info', this could potentially cause a never-ending loop of messages!
| Do *not* set the 'info_prefix' here (for incoming serverinfo requests) to the same value as given to
| the setSrvInfoPrefix() method (for *replies* to incoming serverinfo requests).
| For example, use '/info' for incoming requests, and '/inforeply' or '/serverinfo' or even just '/print' as the
| info-reply prefix.
|
| addMsgHandler(self, address, callback)
| Register a handler for an OSC-address
| - 'address' is the OSC address-string.
| the address-string should start with '/' and may not contain '*'
| - 'callback' is the function called for incoming OSCMessages that match 'address'.
| The callback-function will be called with the same arguments as the 'msgPrinter_handler' below
|
| address(self)
| Returns a (host,port) tuple of the local address this server is bound to,
| or None if not bound to any address.
|
| close(self)
| Stops serving requests, closes server (socket), closes used client
|
| delMsgHandler(self, address)
| Remove the registered handler for the given OSC-address
|
| getOSCAddressSpace(self)
| Returns a list containing all OSC-addresses registerd with this Server.
|
| handle_error(self, request, client_address)
| Handle an exception in the Server's callbacks gracefully.
| Writes the error to sys.stderr and, if the error_prefix (see setSrvErrorPrefix()) is set,
| sends the error-message as reply to the client
|
| msgPrinter_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler prints the received message.
| Returns None
|
| noCallback_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler prints a "No callback registered to handle ..." message.
| Returns None
|
| printErr(self, txt)
| Writes 'OSCServer txt' to sys.stderr
|
| reportErr(self, txt, client_address)
| Writes 'OSCServer txt' to sys.stderr
| If self.error_prefix is defined, sends 'txt' as an OSC error-message to the client(s)
| (see printErr() and sendOSCerror())
|
| sendOSCerror(self, txt, client_address)
| Sends 'txt', encapsulated in an OSCMessage to the default 'error_prefix' OSC-addres.
| Message is sent to the given client_address, with the default 'return_port' overriding
| the client_address' port, if defined.
|
| sendOSCinfo(self, txt, client_address)
| Sends 'txt', encapsulated in an OSCMessage to the default 'info_prefix' OSC-addres.
| Message is sent to the given client_address, with the default 'return_port' overriding
| the client_address' port, if defined.
|
| serve_forever(self)
| Handle one request at a time until server is closed.
|
| serverInfo_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler returns a reply to the client, which can contain various bits of information
| about this server, depending on the first argument of the received OSC-message
| - 'help' | 'info' Reply contains server type & version info, plus a list of
| available 'commands' understood by this handler
| - 'list' | 'ls' Reply is a bundle of 'address <string>' messages, listing the server's
| OSC address-space.
| - 'clients' | 'targets' Reply is a bundle of 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| messages, listing the local Client-instance's subscribed remote clients.
|
| setClient(self, client)
| Associate this Server with a new local Client instance, closing the Client this Server is currently using.
|
| setReturnPort(self, port)
| Set the destination UDP-port for replies returning from this server to the remote client
|
| setSrvErrorPrefix(self, pattern='')
| Set the OSC-address (pattern) this server will use to report errors occuring during
| received message handling to the remote client.
|
| If pattern is empty (default), server-errors are not reported back to the client.
|
| setSrvInfoPrefix(self, pattern)
| Set the first part of OSC-address (pattern) this server will use to reply to server-info requests.
|
| subscription_handler(self, addr, tags, data, client_address)
| Handle 'subscribe' / 'unsubscribe' requests from remote hosts,
| if the local Client supports this (i.e. OSCMultiClient).
|
| Supported commands
| - 'help' | 'info' Reply contains server type & version info, plus a list of
| available 'commands' understood by this handler
| - 'list' | 'ls' Reply is a bundle of 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| messages, listing the local Client-instance's subscribed remote clients.
| - '[subscribe | listen | sendto | target] <url> [<filter> ...] Subscribe remote client/server at <url>,
| and/or set message-filters for messages being sent to the subscribed host, with the optional <filter>
| arguments. Filters are given as OSC-addresses (or '*') prefixed by a '+' (send matching messages) or
| a '-' (don't send matching messages). The wildcard '*', '+*' or '+/*' means 'send all' / 'filter none',
| and '-*' or '-/*' means 'send none' / 'filter all' (which is not the same as unsubscribing!)
| Reply is an OSCMessage with the (new) subscription; 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| - '[unsubscribe | silence | nosend | deltarget] <url> Unsubscribe remote client/server at <url>
| If the given <url> isn't subscribed, a NotSubscribedError-message is printed (and possibly sent)
|
| The <url> given to the subscribe/unsubscribe handler should be of the form
| '[osc//][<host>][<port>][<prefix>]', where any or all components can be omitted.
|
| If <host> is not specified, the IP-address of the message's source is used.
| If <port> is not specified, the <host> is first looked up in the list of subscribed hosts, and if found,
| the associated port is used.
| If <port> is not specified and <host> is not yet subscribed, the message's source-port is used.
| If <prefix> is specified on subscription, <prefix> is prepended to the OSC-address of all messages
| sent to the subscribed host.
| If <prefix> is specified on unsubscription, the subscribed host is only unsubscribed if the host,
| port and prefix all match the subscription.
| If <prefix> is not specified on unsubscription, the subscribed host is unsubscribed if the host and port
| match the subscription.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from OSCServer
|
| print_tracebacks = False
|
| socket_timeout = 1
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.UDPServer
|
| close_request(self, request)
|
| get_request(self)
|
| server_activate(self)
|
| shutdown_request(self, request)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.UDPServer
|
| allow_reuse_address = False
|
| max_packet_size = 8192
|
| socket_type = 2
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.TCPServer
|
| fileno(self)
| Return socket file number.
|
| Interface required by select().
|
| server_bind(self)
| Called by constructor to bind the socket.
|
| May be overridden.
|
| server_close(self)
| Called to clean-up the server.
|
| May be overridden.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.TCPServer
|
| address_family = 2
|
| request_queue_size = 5
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.BaseServer
|
| finish_request(self, request, client_address)
| Finish one request by instantiating RequestHandlerClass.
|
| handle_request(self)
| Handle one request, possibly blocking.
|
| Respects self.timeout.
|
| shutdown(self)
| Stops the serve_forever loop.
|
| Blocks until the loop has finished. This must be called while
| serve_forever() is running in another thread, or it will
| deadlock.
|
| verify_request(self, request, client_address)
| Verify the request. May be overridden.
|
| Return True if we should proceed with this request.
class NoCallbackError(OSCServerError)
| This error is raised (by an OSCServer) when an OSCMessage with an 'unmatched' address-pattern
| is received, and no 'default' handler is registered.
|
| Method resolution order
| NoCallbackError
| OSCServerError
| OSCError
| exceptions.Exception
| exceptions.BaseException
| __builtin__.object
| ----------------------------------------------------------------------
class NotSubscribedError(OSCClientError)
| This error is raised (by an OSCMultiClient) when an attempt is made to unsubscribe a host
| that isn't subscribed.
|
| Method resolution order
| NotSubscribedError
| OSCClientError
| OSCError
| exceptions.Exception
| exceptions.BaseException
| __builtin__.object
class OSCBundle(OSCMessage)
| Builds a 'bundle' of OSC messages.
|
| OSCBundle objects are container objects for building OSC-bundles of OSC-messages.
| An OSC-bundle is a special kind of OSC-message which contains a list of OSC-messages
| (And yes, OSC-bundles may contain other OSC-bundles...)
|
| OSCBundle objects behave much the same as OSCMessage objects, with these exceptions
| - if an item or items to be appended or inserted are not OSCMessage objects,
| OSCMessage objectss are created to encapsulate the item(s)
| - an OSC-bundle does not have an address of its own, only the contained OSC-messages do.
| The OSCBundle's 'address' is inherited by any OSCMessage the OSCBundle object creates.
| - OSC-bundles have a timetag to tell the receiver when the bundle should be processed.
| The default timetag value (0) means 'immediately'
|
| Method resolution order
| OSCBundle
| OSCMessage
| __builtin__.object
|
| Methods defined here
|
| append(self, argument, typehint=None)
| Appends data to the bundle, creating an OSCMessage to encapsulate
| the provided argument unless this is already an OSCMessage.
| Any newly created OSCMessage inherits the OSCBundle's address at the time of creation.
| If 'argument' is an iterable, its elements will be encapsuated by a single OSCMessage.
| Finally, 'argument' can be (or contain) a dict, which will be 'converted' to an OSCMessage;
| - if 'addr' appears in the dict, its value overrides the OSCBundle's address
| - if 'args' appears in the dict, its value(s) become the OSCMessage's arguments
|
| copy(self)
| Returns a deep copy of this OSCBundle
|
| getBinary(self)
| Returns the binary representation of the message
|
| getTimeTagStr(self)
| Return the TimeTag as a human-readable string
|
| setTimeTag(self, time)
| Set or change the OSCBundle's TimeTag
| In 'Python Time', that's floating seconds since the Epoch
|
| values(self)
| Returns a list of the OSCMessages appended so far
|
| ----------------------------------------------------------------------
| Methods inherited from OSCMessage
|
| clear(self, address='')
| Clear (or set a new) OSC-address and clear any arguments appended so far
|
| clearData(self)
| Clear any arguments appended so far
|
| count(self, val)
| Returns the number of times the given value occurs in the OSCMessage's arguments
|
| extend(self, values)
| Append the contents of 'values' to this OSCMessage.
| 'values' can be another OSCMessage, or a list/tuple of ints/floats/strings
|
| index(self, val)
| Returns the index of the first occurence of the given value in the OSCMessage's arguments.
| Raises ValueError if val isn't found
|
| insert(self, i, val, typehint=None)
| Insert given value (with optional typehint) into the OSCMessage
| at the given index.
|
| items(self)
| Returns a list of (typetag, value) tuples for
| the arguments appended so far
|
| iteritems(self)
| Returns an iterator of the OSCMessage's arguments as
| (typetag, value) tuples
|
| itertags(self)
| Returns an iterator of the OSCMessage's arguments' typetags
|
| itervalues(self)
| Returns an iterator of the OSCMessage's arguments
|
| pop(self, i)
| Delete the indicated argument from the OSCMessage, and return it.
|
| popitem(self, i)
| Delete the indicated argument from the OSCMessage, and return it
| as a (typetag, value) tuple.
|
| remove(self, val)
| Removes the first argument with the given value from the OSCMessage.
| Raises ValueError if val isn't found.
|
| reverse(self)
| Reverses the arguments of the OSCMessage (in place)
|
| setAddress(self, address)
| Set or change the OSC-address
|
| setItem(self, i, val, typehint=None)
| Set indicated argument to a new value (with typehint)
|
| tags(self)
| Returns a list of typetags of the appended arguments
|
| ----------------------------------------------------------------------
class OSCClient(__builtin__.object)
| Simple OSC Client. Handles the sending of OSC-Packets (OSCMessage or OSCBundle) via a UDP-socket
|
| Methods defined here
|
| address(self)
| Returns a (host,port) tuple of the remote server this client is
| connected to or None if not connected to any server.
|
| close(self)
| Disconnect & close the Client's socket
|
| connect(self, address)
| Bind to a specific OSC server
| the 'address' argument is a (host, port) tuple
| - host hostname of the remote OSC server,
| - port UDP-port the remote OSC server listens to.
|
| send(self, msg, timeout=None)
| Send the given OSCMessage.
| The Client must be already connected.
| - msg OSCMessage (or OSCBundle) to be sent
| - timeout A timeout value for attempting to send. If timeout == None,
| this call blocks until socket is available for writing.
| Raises OSCClientError when timing out while waiting for the socket,
| or when the Client isn't connected to a remote server.
|
| sendto(self, msg, address, timeout=None)
| Send the given OSCMessage to the specified address.
| - msg OSCMessage (or OSCBundle) to be sent
| - address (host, port) tuple specifing remote server to send the message to
| - timeout A timeout value for attempting to send. If timeout == None,
| this call blocks until socket is available for writing.
| Raises OSCClientError when timing out while waiting for the socket.
|
| setServer(self, server)
| Associate this Client with given server.
| The Client will send from the Server's socket.
| The Server will use this Client instance to send replies.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here
|
| sndbuf_size = 32768
class OSCClientError(OSCError)
| Class for all OSCClient errors
|
| Method resolution order
| OSCClientError
| OSCError
| exceptions.Exception
| exceptions.BaseException
| __builtin__.object
| ----------------------------------------------------------------------
| Methods inherited from exceptions.BaseException
class OSCError(exceptions.Exception)
| Base Class for all OSC-related errors
|
| Method resolution order
| OSCError
| exceptions.Exception
| exceptions.BaseException
class OSCMessage(__builtin__.object)
| Builds typetagged OSC messages.
|
| OSCMessage objects are container objects for building OSC-messages.
| On the 'front' end, they behave much like list-objects, and on the 'back' end
| they generate a binary representation of the message, which can be sent over a network socket.
| OSC-messages consist of an 'address'-string (not to be confused with a (host, port) IP-address!),
| followed by a string of 'typetags' associated with the message's arguments (ie. 'payload'),
| and finally the arguments themselves, encoded in an OSC-specific way.
|
| On the Python end, OSCMessage are lists of arguments, prepended by the message's address.
| The message contents can be manipulated much like a list
| >>> msg = OSCMessage("/my/osc/address")
| >>> msg.append('something')
| >>> msg.insert(0, 'something else')
| >>> msg[1] = 'entirely'
| >>> msg.extend([1,2,3.])
| >>> msg += [4, 5, 6.]
| >>> del msg[36]
| >>> msg.pop(-2)
| 5
| >>> print msg
| /my/osc/address ['something else', 'entirely', 1, 6.0]
|
| OSCMessages can be concatenated with the + operator. In this case, the resulting OSCMessage
| inherits its address from the left-hand operand. The right-hand operand's address is ignored.
| To construct an 'OSC-bundle' from multiple OSCMessage, see OSCBundle!
|
| Additional methods exist for retreiving typetags or manipulating items as (typetag, value) tuples.
|
| append(self, argument, typehint=None)
| Appends data to the message, updating the typetags based on
| the argument's type. If the argument is a blob (counted
| string) pass in 'b' as typehint.
| 'argument' may also be a list or tuple, in which case its elements
| will get appended one-by-one, all using the provided typehint
|
| clear(self, address='')
| Clear (or set a new) OSC-address and clear any arguments appended so far
|
| clearData(self)
| Clear any arguments appended so far
|
| copy(self)
| Returns a deep copy of this OSCMessage
|
| count(self, val)
| Returns the number of times the given value occurs in the OSCMessage's arguments
|
| extend(self, values)
| Append the contents of 'values' to this OSCMessage.
| 'values' can be another OSCMessage, or a list/tuple of ints/floats/strings
|
| getBinary(self)
| Returns the binary representation of the message
|
| index(self, val)
| Returns the index of the first occurence of the given value in the OSCMessage's arguments.
| Raises ValueError if val isn't found
|
| insert(self, i, val, typehint=None)
| Insert given value (with optional typehint) into the OSCMessage
| at the given index.
|
| items(self)
| Returns a list of (typetag, value) tuples for
| the arguments appended so far
|
| iteritems(self)
| Returns an iterator of the OSCMessage's arguments as
| (typetag, value) tuples
|
| itertags(self)
| Returns an iterator of the OSCMessage's arguments' typetags
|
| itervalues(self)
| Returns an iterator of the OSCMessage's arguments
|
| pop(self, i)
| Delete the indicated argument from the OSCMessage, and return it.
|
| popitem(self, i)
| Delete the indicated argument from the OSCMessage, and return it
| as a (typetag, value) tuple.
|
| remove(self, val)
| Removes the first argument with the given value from the OSCMessage.
| Raises ValueError if val isn't found.
|
| reverse(self)
| Reverses the arguments of the OSCMessage (in place)
|
| setAddress(self, address)
| Set or change the OSC-address
|
| setItem(self, i, val, typehint=None)
| Set indicated argument to a new value (with typehint)
|
| tags(self)
| Returns a list of typetags of the appended arguments
|
| values(self)
| Returns a list of the arguments appended so far
|
| ----------------------------------------------------------------------
class OSCMultiClient(OSCClient)
| 'Multiple-Unicast' OSC Client. Handles the sending of OSC-Packets (OSCMessage or OSCBundle) via a UDP-socket
| This client keeps a dict of 'OSCTargets'. and sends each OSCMessage to each OSCTarget
| The OSCTargets are simply (host, port) tuples, and may be associated with an OSC-address prefix.
| the OSCTarget's prefix gets prepended to each OSCMessage sent to that target.
|
| Method resolution order
| OSCMultiClient
| OSCClient
| __builtin__.object
|
| Methods defined here
|
| clearOSCTargets(self)
| Erases all OSCTargets from the Client's dict
|
| connect(self, address)
| The OSCMultiClient isn't allowed to connect to any specific
| address.
|
| delOSCTarget(self, address, prefix=None)
| Delete the specified OSCTarget from the Client's dict.
| the 'address' argument can be a ((host, port) tuple), or a hostname.
| If the 'prefix' argument is given, the Target is only deleted if the address and prefix match.
|
| getOSCTarget(self, address)
| Returns the OSCTarget matching the given address as a ((host, port), [prefix, filters]) tuple.
| 'address' can be a (host, port) tuple, or a 'host' (string), in which case the first matching OSCTarget is returned
| Returns (None, ['',{}]) if address not found.
|
| getOSCTargetStr(self, address)
| Returns the OSCTarget matching the given address as a ('osc//<host><port>[<prefix>]', ['<filter-string>', ...])' tuple.
| 'address' can be a (host, port) tuple, or a 'host' (string), in which case the first matching OSCTarget is returned
| Returns (None, []) if address not found.
|
| getOSCTargetStrings(self)
| Returns a list of all OSCTargets as ('osc//<host><port>[<prefix>]', ['<filter-string>', ...])' tuples.
|
| getOSCTargets(self)
| Returns the dict of OSCTargets {addr[prefix, filters], ...}
|
| hasOSCTarget(self, address, prefix=None)
| Return True if the given OSCTarget exists in the Client's dict.
| the 'address' argument can be a ((host, port) tuple), or a hostname.
| If the 'prefix' argument is given, the return-value is only True if the address and prefix match.
|
| send(self, msg, timeout=None)
| Send the given OSCMessage to all subscribed OSCTargets
| - msg OSCMessage (or OSCBundle) to be sent
| - timeout A timeout value for attempting to send. If timeout == None,
| this call blocks until socket is available for writing.
| Raises OSCClientError when timing out while waiting for the socket.
|
| sendto(self, msg, address, timeout=None)
| Send the given OSCMessage.
| The specified address is ignored. Instead this method calls send() to
| send the message to all subscribed clients.
| - msg OSCMessage (or OSCBundle) to be sent
| - address (host, port) tuple specifing remote server to send the message to
| - timeout A timeout value for attempting to send. If timeout == None,
| this call blocks until socket is available for writing.
| Raises OSCClientError when timing out while waiting for the socket.
|
| setOSCTarget(self, address, prefix=None, filters=None)
| Add (i.e. subscribe) a new OSCTarget, or change the prefix for an existing OSCTarget.
| the 'address' argument can be a ((host, port) tuple) The target server address & UDP-port
| or a 'host' (string) The host will be looked-up
| - prefix (string) The OSC-address prefix prepended to the address of each OSCMessage
| sent to this OSCTarget (optional)
|
| setOSCTargetFromStr(self, url)
| Adds or modifies a subscribed OSCTarget from the given string, which should be in the
| '<host><port>[/<prefix>] [+/<filter>]|[-/<filter>] ...' format.
|
| updateOSCTargets(self, dict)
| Update the Client's OSCTargets dict with the contents of 'dict'
| The given dict's items MUST be of the form
| { (host, port)[prefix, filters], ... }
|
| ----------------------------------------------------------------------
| Methods inherited from OSCClient
|
| address(self)
| Returns a (host,port) tuple of the remote server this client is
| connected to or None if not connected to any server.
|
| close(self)
| Disconnect & close the Client's socket
|
| setServer(self, server)
| Associate this Client with given server.
| The Client will send from the Server's socket.
| The Server will use this Client instance to send replies.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from OSCClient
|
| sndbuf_size = 32768
class OSCRequestHandler(SocketServer.DatagramRequestHandler)
| RequestHandler class for the OSCServer
|
| Method resolution order
| OSCRequestHandler
| SocketServer.DatagramRequestHandler
| SocketServer.BaseRequestHandler
|
| Methods defined here
|
| dispatchMessage(self, pattern, tags, data)
| Attmept to match the given OSC-address pattern, which may contain '*',
| against all callbacks registered with the OSCServer.
| Calls the matching callback and returns whatever it returns.
| If no match is found, and a 'default' callback is registered, it calls that one,
| or raises NoCallbackError if a 'default' callback is not registered.
|
| - pattern (string) The OSC-address of the receied message
| - tags (string) The OSC-typetags of the receied message's arguments, without ','
| - data (list) The message arguments
|
| finish(self)
| Finish handling OSCMessage.
| Send any reply returned by the callback(s) back to the originating client
| as an OSCMessage or OSCBundle
|
| handle(self)
| Handle incoming OSCMessage
|
| setup(self)
| Prepare RequestHandler.
| Unpacks request as (packet, source socket address)
| Creates an empty list for replies.
class OSCServer(SocketServer.UDPServer)
| A Synchronous OSCServer
| Serves one request at-a-time, until the OSCServer is closed.
| The OSC address-pattern is matched against a set of OSC-adresses
| that have been registered to the server with a callback-function.
| If the adress-pattern of the message machtes the registered address of a callback,
| that function is called.
|
| Method resolution order
| OSCServer
| SocketServer.UDPServer
| SocketServer.TCPServer
| SocketServer.BaseServer
|
| addDefaultHandlers(self, prefix='', info_prefix='/info', error_prefix='/error')
| Register a default set of OSC-address handlers with this Server
| - 'default' -> noCallback_handler
| the given prefix is prepended to all other callbacks registered by this method
| - '<prefix><info_prefix' -> serverInfo_handler
| - '<prefix><error_prefix> -> msgPrinter_handler
| - '<prefix>/print' -> msgPrinter_handler
| and, if the used Client supports it;
| - '<prefix>/subscribe' -> subscription_handler
| - '<prefix>/unsubscribe' -> subscription_handler
|
| Note the given 'error_prefix' argument is also set as default 'error_prefix' for error-messages
| *sent from* this server. This is ok, because error-messages generally do not elicit a reply from the receiver.
|
| To do this with the serverInfo-prefixes would be a bad idea, because if a request received on '/info' (for example)
| would send replies to '/info', this could potentially cause a never-ending loop of messages!
| Do *not* set the 'info_prefix' here (for incoming serverinfo requests) to the same value as given to
| the setSrvInfoPrefix() method (for *replies* to incoming serverinfo requests).
| For example, use '/info' for incoming requests, and '/inforeply' or '/serverinfo' or even just '/print' as the
| info-reply prefix.
|
| addMsgHandler(self, address, callback)
| Register a handler for an OSC-address
| - 'address' is the OSC address-string.
| the address-string should start with '/' and may not contain '*'
| - 'callback' is the function called for incoming OSCMessages that match 'address'.
| The callback-function will be called with the same arguments as the 'msgPrinter_handler' below
|
| address(self)
| Returns a (host,port) tuple of the local address this server is bound to,
| or None if not bound to any address.
|
| close(self)
| Stops serving requests, closes server (socket), closes used client
|
| delMsgHandler(self, address)
| Remove the registered handler for the given OSC-address
|
| getOSCAddressSpace(self)
| Returns a list containing all OSC-addresses registerd with this Server.
|
| handle_error(self, request, client_address)
| Handle an exception in the Server's callbacks gracefully.
| Writes the error to sys.stderr and, if the error_prefix (see setSrvErrorPrefix()) is set,
| sends the error-message as reply to the client
|
| msgPrinter_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler prints the received message.
| Returns None
|
| noCallback_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler prints a "No callback registered to handle ..." message.
| Returns None
|
| printErr(self, txt)
| Writes 'OSCServer txt' to sys.stderr
|
| reportErr(self, txt, client_address)
| Writes 'OSCServer txt' to sys.stderr
| If self.error_prefix is defined, sends 'txt' as an OSC error-message to the client(s)
| (see printErr() and sendOSCerror())
|
| sendOSCerror(self, txt, client_address)
| Sends 'txt', encapsulated in an OSCMessage to the default 'error_prefix' OSC-addres.
| Message is sent to the given client_address, with the default 'return_port' overriding
| the client_address' port, if defined.
|
| sendOSCinfo(self, txt, client_address)
| Sends 'txt', encapsulated in an OSCMessage to the default 'info_prefix' OSC-addres.
| Message is sent to the given client_address, with the default 'return_port' overriding
| the client_address' port, if defined.
|
| serve_forever(self)
| Handle one request at a time until server is closed.
|
| serverInfo_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler returns a reply to the client, which can contain various bits of information
| about this server, depending on the first argument of the received OSC-message
| - 'help' | 'info' Reply contains server type & version info, plus a list of
| available 'commands' understood by this handler
| - 'list' | 'ls' Reply is a bundle of 'address <string>' messages, listing the server's
| OSC address-space.
| - 'clients' | 'targets' Reply is a bundle of 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| messages, listing the local Client-instance's subscribed remote clients.
|
| setClient(self, client)
| Associate this Server with a new local Client instance, closing the Client this Server is currently using.
|
| setReturnPort(self, port)
| Set the destination UDP-port for replies returning from this server to the remote client
|
| setSrvErrorPrefix(self, pattern='')
| Set the OSC-address (pattern) this server will use to report errors occuring during
| received message handling to the remote client.
|
| If pattern is empty (default), server-errors are not reported back to the client.
|
| setSrvInfoPrefix(self, pattern)
| Set the first part of OSC-address (pattern) this server will use to reply to server-info requests.
|
| subscription_handler(self, addr, tags, data, client_address)
| Handle 'subscribe' / 'unsubscribe' requests from remote hosts,
| if the local Client supports this (i.e. OSCMultiClient).
|
| Supported commands
| - 'help' | 'info' Reply contains server type & version info, plus a list of
| available 'commands' understood by this handler
| - 'list' | 'ls' Reply is a bundle of 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| messages, listing the local Client-instance's subscribed remote clients.
| - '[subscribe | listen | sendto | target] <url> [<filter> ...] Subscribe remote client/server at <url>,
| and/or set message-filters for messages being sent to the subscribed host, with the optional <filter>
| arguments. Filters are given as OSC-addresses (or '*') prefixed by a '+' (send matching messages) or
| a '-' (don't send matching messages). The wildcard '*', '+*' or '+/*' means 'send all' / 'filter none',
| and '-*' or '-/*' means 'send none' / 'filter all' (which is not the same as unsubscribing!)
| Reply is an OSCMessage with the (new) subscription; 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| - '[unsubscribe | silence | nosend | deltarget] <url> Unsubscribe remote client/server at <url>
| If the given <url> isn't subscribed, a NotSubscribedError-message is printed (and possibly sent)
|
| The <url> given to the subscribe/unsubscribe handler should be of the form
| '[osc//][<host>][<port>][<prefix>]', where any or all components can be omitted.
|
| If <host> is not specified, the IP-address of the message's source is used.
| If <port> is not specified, the <host> is first looked up in the list of subscribed hosts, and if found,
| the associated port is used.
| If <port> is not specified and <host> is not yet subscribed, the message's source-port is used.
| If <prefix> is specified on subscription, <prefix> is prepended to the OSC-address of all messages
| sent to the subscribed host.
| If <prefix> is specified on unsubscription, the subscribed host is only unsubscribed if the host,
| port and prefix all match the subscription.
| If <prefix> is not specified on unsubscription, the subscribed host is unsubscribed if the host and port
| match the subscription.
|
| ----------------------------------------------------------------------
| Data and other attributes defined here
|
| RequestHandlerClass = <class OSC.OSCRequestHandler>
|
| print_tracebacks = False
|
| socket_timeout = 1
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.UDPServer
|
| close_request(self, request)
|
| get_request(self)
|
| server_activate(self)
|
| shutdown_request(self, request)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.UDPServer
|
| allow_reuse_address = False
|
| max_packet_size = 8192
|
| socket_type = 2
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.TCPServer
|
| fileno(self)
| Return socket file number.
|
| Interface required by select().
|
| server_bind(self)
| Called by constructor to bind the socket.
|
| May be overridden.
|
| server_close(self)
| Called to clean-up the server.
|
| May be overridden.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.TCPServer
|
| address_family = 2
|
| request_queue_size = 5
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.BaseServer
|
| finish_request(self, request, client_address)
| Finish one request by instantiating RequestHandlerClass.
|
| handle_request(self)
| Handle one request, possibly blocking.
|
| Respects self.timeout.
|
| handle_timeout(self)
| Called if no new request arrives within self.timeout.
|
| Overridden by ForkingMixIn.
|
| process_request(self, request, client_address)
| Call finish_request.
|
| Overridden by ForkingMixIn and ThreadingMixIn.
|
| shutdown(self)
| Stops the serve_forever loop.
|
| Blocks until the loop has finished. This must be called while
| serve_forever() is running in another thread, or it will
| deadlock.
|
| verify_request(self, request, client_address)
| Verify the request. May be overridden.
|
| Return True if we should proceed with this request.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.BaseServer
|
| timeout = None
class OSCServerError(OSCError)
| Class for all OSCServer errors
|
| Method resolution order
| OSCServerError
| OSCError
| exceptions.Exception
| exceptions.BaseException
| __builtin__.object
|
class ThreadingOSCRequestHandler(OSCRequestHandler)
| Multi-threaded OSCRequestHandler;
| Starts a new RequestHandler thread for each unbundled OSCMessage
|
| Method resolution order
| ThreadingOSCRequestHandler
| OSCRequestHandler
| SocketServer.DatagramRequestHandler
| SocketServer.BaseRequestHandler
|
| Methods inherited from OSCRequestHandler
|
| dispatchMessage(self, pattern, tags, data)
| Attmept to match the given OSC-address pattern, which may contain '*',
| against all callbacks registered with the OSCServer.
| Calls the matching callback and returns whatever it returns.
| If no match is found, and a 'default' callback is registered, it calls that one,
| or raises NoCallbackError if a 'default' callback is not registered.
|
| - pattern (string) The OSC-address of the receied message
| - tags (string) The OSC-typetags of the receied message's arguments, without ','
| - data (list) The message arguments
|
| finish(self)
| Finish handling OSCMessage.
| Send any reply returned by the callback(s) back to the originating client
| as an OSCMessage or OSCBundle
|
| handle(self)
| Handle incoming OSCMessage
|
| setup(self)
| Prepare RequestHandler.
| Unpacks request as (packet, source socket address)
| Creates an empty list for replies.
class ThreadingOSCServer(SocketServer.ThreadingMixIn, OSCServer)
| An Asynchronous OSCServer.
| This server starts a new thread to handle each incoming request.
|
| Method resolution order
| ThreadingOSCServer
| SocketServer.ThreadingMixIn
| OSCServer
| SocketServer.UDPServer
| SocketServer.TCPServer
| SocketServer.BaseServer
|
| Data and other attributes defined here
|
| RequestHandlerClass = <class OSC.ThreadingOSCRequestHandler>
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.ThreadingMixIn
|
| process_request(self, request, client_address)
| Start a new thread to process the request.
|
| process_request_thread(self, request, client_address)
| Same as in BaseServer but as a thread.
|
| In addition, exception handling is done here.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.ThreadingMixIn
|
| daemon_threads = False
|
| ----------------------------------------------------------------------
| Methods inherited from OSCServer
| addDefaultHandlers(self, prefix='', info_prefix='/info', error_prefix='/error')
| Register a default set of OSC-address handlers with this Server
| - 'default' -> noCallback_handler
| the given prefix is prepended to all other callbacks registered by this method
| - '<prefix><info_prefix' -> serverInfo_handler
| - '<prefix><error_prefix> -> msgPrinter_handler
| - '<prefix>/print' -> msgPrinter_handler
| and, if the used Client supports it;
| - '<prefix>/subscribe' -> subscription_handler
| - '<prefix>/unsubscribe' -> subscription_handler
|
| Note the given 'error_prefix' argument is also set as default 'error_prefix' for error-messages
| *sent from* this server. This is ok, because error-messages generally do not elicit a reply from the receiver.
|
| To do this with the serverInfo-prefixes would be a bad idea, because if a request received on '/info' (for example)
| would send replies to '/info', this could potentially cause a never-ending loop of messages!
| Do *not* set the 'info_prefix' here (for incoming serverinfo requests) to the same value as given to
| the setSrvInfoPrefix() method (for *replies* to incoming serverinfo requests).
| For example, use '/info' for incoming requests, and '/inforeply' or '/serverinfo' or even just '/print' as the
| info-reply prefix.
|
| addMsgHandler(self, address, callback)
| Register a handler for an OSC-address
| - 'address' is the OSC address-string.
| the address-string should start with '/' and may not contain '*'
| - 'callback' is the function called for incoming OSCMessages that match 'address'.
| The callback-function will be called with the same arguments as the 'msgPrinter_handler' below
|
| address(self)
| Returns a (host,port) tuple of the local address this server is bound to,
| or None if not bound to any address.
|
| close(self)
| Stops serving requests, closes server (socket), closes used client
|
| delMsgHandler(self, address)
| Remove the registered handler for the given OSC-address
|
| getOSCAddressSpace(self)
| Returns a list containing all OSC-addresses registerd with this Server.
|
| handle_error(self, request, client_address)
| Handle an exception in the Server's callbacks gracefully.
| Writes the error to sys.stderr and, if the error_prefix (see setSrvErrorPrefix()) is set,
| sends the error-message as reply to the client
|
| msgPrinter_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler prints the received message.
| Returns None
|
| noCallback_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler prints a "No callback registered to handle ..." message.
| Returns None
|
| printErr(self, txt)
| Writes 'OSCServer txt' to sys.stderr
|
| reportErr(self, txt, client_address)
| Writes 'OSCServer txt' to sys.stderr
| If self.error_prefix is defined, sends 'txt' as an OSC error-message to the client(s)
| (see printErr() and sendOSCerror())
|
| sendOSCerror(self, txt, client_address)
| Sends 'txt', encapsulated in an OSCMessage to the default 'error_prefix' OSC-addres.
| Message is sent to the given client_address, with the default 'return_port' overriding
| the client_address' port, if defined.
|
| sendOSCinfo(self, txt, client_address)
| Sends 'txt', encapsulated in an OSCMessage to the default 'info_prefix' OSC-addres.
| Message is sent to the given client_address, with the default 'return_port' overriding
| the client_address' port, if defined.
|
| serve_forever(self)
| Handle one request at a time until server is closed.
|
| serverInfo_handler(self, addr, tags, data, client_address)
| Example handler for OSCMessages.
| All registerd handlers must accept these three arguments
| - addr (string) The OSC-address pattern of the received Message
| (the 'addr' string has already been matched against the handler's registerd OSC-address,
| but may contain '*'s & such)
| - tags (string) The OSC-typetags of the received message's arguments. (without the preceding comma)
| - data (list) The OSCMessage's arguments
| Note that len(tags) == len(data)
| - client_address ((host, port) tuple) the host & port this message originated from.
|
| a Message-handler function may return None, but it could also return an OSCMessage (or OSCBundle),
| which then gets sent back to the client.
|
| This handler returns a reply to the client, which can contain various bits of information
| about this server, depending on the first argument of the received OSC-message
| - 'help' | 'info' Reply contains server type & version info, plus a list of
| available 'commands' understood by this handler
| - 'list' | 'ls' Reply is a bundle of 'address <string>' messages, listing the server's
| OSC address-space.
| - 'clients' | 'targets' Reply is a bundle of 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| messages, listing the local Client-instance's subscribed remote clients.
|
| setClient(self, client)
| Associate this Server with a new local Client instance, closing the Client this Server is currently using.
|
| setReturnPort(self, port)
| Set the destination UDP-port for replies returning from this server to the remote client
|
| setSrvErrorPrefix(self, pattern='')
| Set the OSC-address (pattern) this server will use to report errors occuring during
| received message handling to the remote client.
|
| If pattern is empty (default), server-errors are not reported back to the client.
|
| setSrvInfoPrefix(self, pattern)
| Set the first part of OSC-address (pattern) this server will use to reply to server-info requests.
|
| subscription_handler(self, addr, tags, data, client_address)
| Handle 'subscribe' / 'unsubscribe' requests from remote hosts,
| if the local Client supports this (i.e. OSCMultiClient).
|
| Supported commands
| - 'help' | 'info' Reply contains server type & version info, plus a list of
| available 'commands' understood by this handler
| - 'list' | 'ls' Reply is a bundle of 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| messages, listing the local Client-instance's subscribed remote clients.
| - '[subscribe | listen | sendto | target] <url> [<filter> ...] Subscribe remote client/server at <url>,
| and/or set message-filters for messages being sent to the subscribed host, with the optional <filter>
| arguments. Filters are given as OSC-addresses (or '*') prefixed by a '+' (send matching messages) or
| a '-' (don't send matching messages). The wildcard '*', '+*' or '+/*' means 'send all' / 'filter none',
| and '-*' or '-/*' means 'send none' / 'filter all' (which is not the same as unsubscribing!)
| Reply is an OSCMessage with the (new) subscription; 'target osc//<host><port>[<prefix>] [<filter>] [...]'
| - '[unsubscribe | silence | nosend | deltarget] <url> Unsubscribe remote client/server at <url>
| If the given <url> isn't subscribed, a NotSubscribedError-message is printed (and possibly sent)
|
| The <url> given to the subscribe/unsubscribe handler should be of the form
| '[osc//][<host>][<port>][<prefix>]', where any or all components can be omitted.
|
| If <host> is not specified, the IP-address of the message's source is used.
| If <port> is not specified, the <host> is first looked up in the list of subscribed hosts, and if found,
| the associated port is used.
| If <port> is not specified and <host> is not yet subscribed, the message's source-port is used.
| If <prefix> is specified on subscription, <prefix> is prepended to the OSC-address of all messages
| sent to the subscribed host.
| If <prefix> is specified on unsubscription, the subscribed host is only unsubscribed if the host,
| port and prefix all match the subscription.
| If <prefix> is not specified on unsubscription, the subscribed host is unsubscribed if the host and port
| match the subscription.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from OSCServer
|
| print_tracebacks = False
|
| socket_timeout = 1
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.UDPServer
|
| close_request(self, request)
|
| get_request(self)
|
| server_activate(self)
|
| shutdown_request(self, request)
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.UDPServer
|
| allow_reuse_address = False
|
| max_packet_size = 8192
|
| socket_type = 2
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.TCPServer
|
| fileno(self)
| Return socket file number.
|
| Interface required by select().
|
| server_bind(self)
| Called by constructor to bind the socket.
|
| May be overridden.
|
| server_close(self)
| Called to clean-up the server.
|
| May be overridden.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.TCPServer
|
| address_family = 2
|
| request_queue_size = 5
|
| ----------------------------------------------------------------------
| Methods inherited from SocketServer.BaseServer
|
| finish_request(self, request, client_address)
| Finish one request by instantiating RequestHandlerClass.
|
| handle_request(self)
| Handle one request, possibly blocking.
|
| Respects self.timeout.
|
| handle_timeout(self)
| Called if no new request arrives within self.timeout.
|
| Overridden by ForkingMixIn.
|
| shutdown(self)
| Stops the serve_forever loop.
|
| Blocks until the loop has finished. This must be called while
| serve_forever() is running in another thread, or it will
| deadlock.
|
| verify_request(self, request, client_address)
| Verify the request. May be overridden.
|
| Return True if we should proceed with this request.
|
| ----------------------------------------------------------------------
| Data and other attributes inherited from SocketServer.BaseServer
|
| timeout = None
FUNCTIONS
OSCArgument(next, typehint=None)
Convert some Python types to their
OSC binary representations, returning a
(typetag, data) tuple.
OSCBlob(next)
Convert a string into an OSC Blob.
An OSC-Blob is a binary encoded block of data, prepended by a 'size' (int32).
The size is always a mutiple of 4 bytes.
The blob ends with 0 to 3 zero-bytes ('^@')
OSCString(next)
Convert a string into a zero-padded OSC String.
The length of the resulting string is always a multiple of 4 bytes.
The string ends with 1 to 4 zero-bytes ('^@')
OSCTimeTag(time)
Convert a time in floating seconds to its
OSC binary representation
decodeOSC(data)
Converts a binary OSC message to a Python list.
getFilterStr(filters)
Return the given 'filters' dict as a list of
An OSC-Blob is a binary encoded block of data, prepended by a 'size' (int32).
The size is always a mutiple of 4 bytes.
The blob ends with 0 to 3 zero-bytes ('^@')
OSCString(next)
Convert a string into a zero-padded OSC String.
The length of the resulting string is always a multiple of 4 bytes.
The string ends with 1 to 4 zero-bytes ('^@')
OSCTimeTag(time)
Convert a time in floating seconds to its
OSC binary representation
decodeOSC(data)
Converts a binary OSC message to a Python list.
getFilterStr(filters)
Return the given 'filters' dict as a list of
'+<addr>' | '-<addr>' filter-strings
getRegEx(pattern)
Compiles and returns a 'regular expression' object for the given address-pattern.
getUrlStr(*args)
Convert provided arguments to a string in 'hostport/prefix' format
Args can be
- (host, port)
- (host, port), prefix
- host, port
- host, port, prefix
hexDump(bytes)
Useful utility; prints the string in hexadecimal.
parseFilterStr(args)
Convert Message-Filter settings in '+<addr> -<addr> ...' format to a dict of the form
{ '<addr>'True, '<addr>'False, ... }
Returns a list ['<prefix>', filters]
parseUrlStr(url)
Convert provided string in 'hostport/prefix' format to it's components
Returns ((host, port), prefix)
DATA
FloatTypes = [<type 'float'>, <type 'numpy.float32'>, <type 'numpy.flo...
IntTypes = [<type 'int'>, <type 'numpy.int8'>, <type 'numpy.uint8'>, <...
OSCtrans = '\x00\x01\x02\x03\x04\x05\x06\x07\x08\t\n\x0b\x0c\r\x0e\x0f...
version = ('0.3', '5b', '5294')
