SCLOrkWire | SuperCollider 3.13.0 Help

Description

Attempts to combine the reliability of TCP, specifically full-duplex two-way communication, automatic retransmission of dropped packets, and in-order packet arrival, with the lower-latency benefits of UDP. A SCLOrkWire wraps arbitrary OSC messages in its own protocol, allows for sending of those messages using sendMsg similar to a NetAddr, and also provides a means to respond to incoming OSC messages using the onMessageReceived function callback.

Class Methods

.new

Makes a new SCLOrkWire using the provided arguments.

Arguments:

receivePort	The port on this computer that the SCLOrkWire should listen on. NOTE: SCLOrkWires are designed to uniquely own a specific port. While other OSC messages can be received on that port multiple SCLOrkWires listening on the same port may create problems if the remote machines have the same id.
id	A unique identifier that will be supplied to the remote machine, that the remote machine will use in all subsequent communications to this client.
timeout	The amount of time, in seconds, that the SCLOrkWire should wait before attempting retransmission of any data.
maxRetries	The number of times that the wire should try retransmitting data before giving up with a failure state.
bufferSize	The size of internal buffers for sending and receiving. The buffers are primarily used for re-ordering of packets that arrive out-of-order, so the size of the buffer conceptually represents the maximum number of packets that the system can tolerate receiving out-of-order before receving retransmission of the in-order data.
netAddrFactory	Useful for testing, allows the user to provide a function that when called with hostname, port arguments will return a NetAddr or similar mocked object. For production code leave at default value.

Returns:

A shiny new SCLOrkWire.

.bind

Will start listening to knock requests on the provided port, calling onKnock function with every new wire made.

Arguments:

port	The port to listen to. Will not re-open or re-assign ports for which bind has already been called.
wireIssueId	A function that will be evaulated to issue unique identifiers to the wire clients. This value will become the id in the created wires.
wireOnConnected	A function that bind provides to the constructed SCLOrkWire objects as their onConnected function.
wireOnMessageReceived	A function that bind provides to the constructed SCLOrkWire objects as their onMessageReceived function.
onKnock	A function that the SCLOrkWire will call on the initiation of each client connection. The function is called with a sole argument which is the newly created wire object.
netAddrFactory	Used for testing, will provide this netAddrFactory function to the SCLOrkWire objects created by bind. Production code should leave at default.

.unbind

Removes any binding function listening at port. Note than any existing SCLOrkWire connections are unaffected by this operation.

Arguments:

port	The port number to stop listening on.

Instance Methods

.disconnect

Initiate the process to normally terminate the connection, resulting in an eventual connection state change to \disconnected or \failureTimeout.

.selfId

Accessor for the unique identifier number provided by the remote connection.

.id

Accessor for the unique identifier provided by the client code on this side at construction time.

.connectionState

Returns the current connection state of the SCLOrkWire, a label enum. The following values are in use:

label value	discussion
\neverConnected	The initial state of a SCLOrkWire, before any connection attempted or requested.
\knocking	The wire is communicating with the remote to get a port assigned, valid next states are either \connectionRequested or \failureTimeout.
\failureTimeout	Some communication the server has timed out and exceeded maximum retries. This is a terminal state of the wire.
\disconnected	Normal disconnection procedure has completed. This is a terminal state of the wire.
\connected	The wire is connected. Valid next states are \disconnected, \disconnectRequested, or \failureTimeout.
\connectionRequested	The wire is responding to an incoming connection request. Valid next states are \connected or \failureTimeout.
\connectionAccepted	The wire is attempting to initiate a connection to the remote host. Valid next states are \connected or \failureTimeout.
\disconnectRequested	The wire is attempting to disconnect from the remote host. Valid next states are \disconnected or \failureTimeout.

.onMessageReceived

The function this SCLOrkWire will call on receipt of a message from the remote host. The function is called with arguments wire, messageArray, where wire is the wire receiving the message, and messageArray is the OSC message that was sent, provided in a manner identical to that of OSCFunc message argument.

.sendMsg

Send the provided arguments as an OSC message to the remote host. Arguments are provided in a manner identical to that of NetAddr: sendMsg.

Arguments:

... args

The message to send.

.free

If connected, disconnect the wire, then delete the object and unbind all listening for messages.

.knock

Attempt to contact hostname at hostPort requesting that they assign a port and initiate a connection with us at our receivePort provided at constrution time.

Arguments:

hostname	The name or ip address of the remote host to contact.
knockPort	The port that the remote host has bound with bind.

.isIdle

Will be true if the wire is \connected or \disconnected and is not currently sending data or has buffered out-of-order received data. Useful for testing.

.onConnected

A function called when there's a change in connectionState. The function is called with arguments wire, state, where wire is the wire reporting the state change and state is any of the enum values detailed in the connectionState table.

.connect

Initiate a connection to the remote host.

Arguments:

hostname	The name or ip address of the remote host to connect to.
requestPort	The port on the remote host to initiate connection with.

Examples

// ==== Client-Server Networking

// Server sets up a knock port at 8000, and will populate
// connectedWires with all connected wires as they come in.
// Server will respond with '/pong' to each '/ping' message.
(
var idSerial = 1;
var connectedWires = Array.new;
SCLOrkWire.bind(
    port: 8000,
    wireIssueId: {
        var id = idSerial;
        idSerial = idSerial + 1;
        id;
    },
    wireOnConnected: { | wire, state |
        "wire id: %, new state: %".format(wire.id, state).postln;
    },
    wireOnMessageRecieved: { | wire, message |
        var wire = connectedWires.at(id);
        "wire id: % received message %".format(
            wire.id, message).postln;
        if (message[0] == '/ping', {
            wire.sendMsg('/pong');
        });
    },
    onKnock: { | wire |
        connectedWires = connectedWires.add(wire);
    }
);
)

// Client connects to server via knocking.
(
var wire = SCLOrkWire.new;
wire.onMessageReceived = { | id, message |
    if (message[0] == '/pong', {
        "got pong".postln;
    });
};
// Send message on connection complete.
wire.onConnected = { | id, state |
    if (state == \connected, {
        wire.sendMsg('/ping');
    });
};
wire.knock("sclork-s01.local", 8000);
)

helpfile source: HelpSource/Classes/SCLOrkWire.schelp
link::SCLOrkTools/Classes/SCLOrkWire::

SCLOrkWireExtension

Description

Class Methods

.new

Arguments:

Returns:

.bind

Arguments:

.unbind

Arguments:

Instance Methods

.disconnect

.selfId

.id

.connectionState

.onMessageReceived

.sendMsg

Arguments:

.free

.knock

Arguments:

.isIdle

.onConnected

.connect

Arguments:

Examples

SCLOrkWire
Extension