oscP5
Class OscP5

java.lang.Object
  oscP5.OscP5

All Implemented Interfaces:

TcpPacketListener, UdpPacketListener

public class OscP5
extends Object
implements UdpPacketListener, TcpPacketListener

TODO add better error message handling for oscEvents, see this post http://forum.processing.org/topic/oscp5-major-problems-with-error-handling# 25080000000811163

Field Summary

static int	MULTICAST a static variable used when creating an oscP5 instance with a sepcified network protocol.
static boolean	OFF
static boolean	ON
static int	TCP a static variable used when creating an oscP5 instance with a sepcified network protocol.
static int	UDP a static variable used when creating an oscP5 instance with a sepcified network protocol.
static String	VERSION

Constructor Summary

OscP5(Object theParent, int theReceiveAtPort)

OscP5(Object theParent, int theReceiveAtPort, int theMode)

OscP5(Object theParent, OscProperties theProperties)

OscP5(Object theParent, String theAddress, int thePort)
Deprecated.

OscP5(Object theParent, String theAddress, int thePort, int theMode)

OscP5(Object theParent, String theHost, int theSendToPort, int theReceiveAtPort, String theMethodName)
Deprecated.

Method Summary

void	addListener(OscEventListener theListener)
void	connect(NetAddress theNetAddress, String theName, String[] theArguments)
void	disconnect(NetAddress theHost)
void	disconnectFromTEMP() Deprecated.
void	dispose()
static void	flush(byte[] theBytes, NetAddress theNetAddress)
static void	flush(byte[] theBytes, String theAddress, int thePort) Deprecated.
static void	flush(OscMessage theOscMessage, NetAddress theNetAddress) a static method to send an OscMessage straight out of the box without having to instantiate oscP5.
static void	flush(OscMessage theOscMessage, String theAddress, int thePort) Deprecated.
static void	flush(OscPacket theOscPacket, NetAddress theNetAddress)
static void	flush(String theAddrPattern, Object[] theArguments, NetAddress theNetAddress)
String	ip()
boolean	isBroadcast()
Vector<OscEventListener>	listeners()
NetInfo	netInfo() netinfo() returns an instance of a NetInfo Object from which you can get LAN and WAN information.
OscBundle	newBundle() Deprecated.
OscMessage	newMsg(String theAddrPattern) Deprecated.
void	plug(Object theObject, String theMethodName, String theAddrPattern)
void	plug(Object theObject, String theMethodName, String theAddrPattern, String theTypeTag) osc messages can be automatically forwarded to a specific method of an object.
void	process(DatagramPacket thePacket, int thePort) incoming osc messages from an udp socket are parsed, processed and forwarded to the parent.
void	process(TcpPacket thePacket, int thePort)
OscProperties	properties() returns the current properties of oscP5.
void	remove(AbstractTcpClient theTcpClient)
void	removeListener(OscEventListener theListener)
void	send(OscPacket thePacket)
void	send(OscPacket thePacket, NetAddress theNetAddress) you can send osc packets in many different ways.
void	send(OscPacket thePacket, NetAddressList theNetAddressList)
void	send(OscPacket thePacket, String theIpAddress, int thePort) Deprecated.
void	send(OscPacket thePacket, TcpClient theClient) send to tcp client
void	send(String theAddrPattern, Object[] theArguments)
void	send(String theAddrPattern, Object[] theArguments, NetAddress theNetAddress)
void	send(String theAddrPattern, Object[] theArguments, NetAddressList theNetAddressList)
void	send(String theAddrPattern, Object[] theArguments, String theAddress, int thePort)
void	send(String theAddrPattern, Object[] theArguments, TcpClient theClient)
static void	setLogStatus(int theValue)
static void	setLogStatus(int theIndex, int theValue) oscP5 has a logging mechanism which prints out processes, warnings and errors into the console window.
void	setTimeToLive(int theTTL) set timeToLive of a multicast packet.
void	status(int theIndex)
void	stop() stop oscP5 and close open Sockets.
TcpClient	tcpClient() return the instance of the running TCP client if in TCP mode.
TcpServer	tcpServer() return the instance of the running TCP server if in TCP mode.
String	version() get the current version of oscP5.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ON

public static final boolean ON

See Also:

Constant Field Values

OFF

public static final boolean OFF

See Also:

Constant Field Values

UDP

public static final int UDP

a static variable used when creating an oscP5 instance with a sepcified network protocol.

See Also:

Constant Field Values

MULTICAST

public static final int MULTICAST

a static variable used when creating an oscP5 instance with a sepcified network protocol.

See Also:

Constant Field Values

TCP

public static final int TCP

a static variable used when creating an oscP5 instance with a sepcified network protocol.

See Also:

Constant Field Values

VERSION

public static final String VERSION

See Also:

Constant Field Values

Constructor Detail

OscP5

public OscP5(Object theParent,
             OscProperties theProperties)

Parameters:

theParent - Object

theProperties - OscProperties

OscP5

public OscP5(Object theParent,
             String theAddress,
             int thePort,
             int theMode)

Parameters:

theParent - Object

theAddress - String

thePort - int

theMode - int

OscP5

public OscP5(Object theParent,
             int theReceiveAtPort,
             int theMode)

OscP5

public OscP5(Object theParent,
             int theReceiveAtPort)

Parameters:

theParent - Object

theReceiveAtPort - int

OscP5

public OscP5(Object theParent,
             String theHost,
             int theSendToPort,
             int theReceiveAtPort,
             String theMethodName)

Deprecated.

old version of constructor. still in here for backwards compatibility.

OscP5

public OscP5(Object theParent,
             String theAddress,
             int thePort)

Deprecated.

Parameters:

theParent - Object

theAddress - String

thePort - int

Method Detail

version

public String version()

get the current version of oscP5.

Returns:

String

dispose

public void dispose()

addListener

public void addListener(OscEventListener theListener)

removeListener

public void removeListener(OscEventListener theListener)

listeners

public Vector<OscEventListener> listeners()

plug

public void plug(Object theObject,
                 String theMethodName,
                 String theAddrPattern,
                 String theTypeTag)

osc messages can be automatically forwarded to a specific method of an object. the plug method can be used to by-pass parsing raw osc messages - this job is done for you with the plug mechanism. you can also use the following array-types int[], float[], String[]. (but only as on single parameter e.g. somemethod(int[] theArray) {} ).

Parameters:

theObject - Object, can be any Object

theMethodName - String, the method name an osc message should be forwarded to

theAddrPattern - String, the address pattern of the osc message

theTypeTag - String

+Example

/**
 * oscP5plug by andreas schlegel
 * example shows how to use the plug service with oscP5.
 * the concept of the plug service is, that you can
 * register methods in your sketch to which incoming 
 * osc messages will be forwareded automatically without 
 * having to parse them in the oscEvent method.
 * that a look at the example below to get an understanding
 * of how plug works.
 * oscP5 website at http://www.sojamo.de/oscP5
 */

import oscP5.*;
import netP5.*;

OscP5 oscP5;
NetAddress myRemoteLocation;

void setup() {
  size(400,400);
  frameRate(25);
  /* start oscP5, listening for incoming messages at port 12000 */
  oscP5 = new OscP5(this,12000);
  
  /* myRemoteLocation is a NetAddress. a NetAddress takes 2 parameters,
   * an ip address and a port number. myRemoteLocation is used as parameter in
   * oscP5.send() when sending osc packets to another computer, device, 
   * application. usage see below. for testing purposes the listening port
   * and the port of the remote location address are the same, hence you will
   * send messages back to this sketch.
   */
  myRemoteLocation = new NetAddress("127.0.0.1",12000);
  
  /* osc plug service
   * osc messages with a specific address pattern can be automatically
   * forwarded to a specific method of an object. in this example 
   * a message with address pattern /test will be forwarded to a method
   * test(). below the method test takes 2 arguments - 2 ints. therefore each
   * message with address pattern /test and typetag ii will be forwarded to
   * the method test(int theA, int theB)
   */
  oscP5.plug(this,"test","/test");
}


public void test(int theA, int theB) {
  println("### plug event method. received a message /test.");
  println(" 2 ints received: "+theA+", "+theB);  
}


void draw() {
  background(0);
}


void mousePressed() {
  /* createan osc message with address pattern /test */
  OscMessage myMessage = new OscMessage("/test");
  
  myMessage.add(123); /* add an int to the osc message */
  myMessage.add(456); /* add a second int to the osc message */

  /* send the message */
  oscP5.send(myMessage, myRemoteLocation); 
}


/* incoming osc message are forwarded to the oscEvent method. */
void oscEvent(OscMessage theOscMessage) {
  /* with theOscMessage.isPlugged() you check if the osc message has already been
   * forwarded to a plugged method. if theOscMessage.isPlugged()==true, it has already 
   * been forwared to another method in your sketch. theOscMessage.isPlugged() can 
   * be used for double posting but is not required.
  */  
  if(theOscMessage.isPlugged()==false) {
  /* print the address pattern and the typetag of the received OscMessage */
  println("### received an osc message.");
  println("### addrpattern\t"+theOscMessage.addrPattern());
  println("### typetag\t"+theOscMessage.typetag());
  }
}

plug

public void plug(Object theObject,
                 String theMethodName,
                 String theAddrPattern)

Parameters:

theObject - Object, can be any Object

theMethodName - String, the method name an osc message should be forwarded to

theAddrPattern - String, the address pattern of the osc message

+Example

/**
 * oscP5plug by andreas schlegel
 * example shows how to use the plug service with oscP5.
 * the concept of the plug service is, that you can
 * register methods in your sketch to which incoming 
 * osc messages will be forwareded automatically without 
 * having to parse them in the oscEvent method.
 * that a look at the example below to get an understanding
 * of how plug works.
 * oscP5 website at http://www.sojamo.de/oscP5
 */

import oscP5.*;
import netP5.*;

OscP5 oscP5;
NetAddress myRemoteLocation;

void setup() {
  size(400,400);
  frameRate(25);
  /* start oscP5, listening for incoming messages at port 12000 */
  oscP5 = new OscP5(this,12000);
  
  /* myRemoteLocation is a NetAddress. a NetAddress takes 2 parameters,
   * an ip address and a port number. myRemoteLocation is used as parameter in
   * oscP5.send() when sending osc packets to another computer, device, 
   * application. usage see below. for testing purposes the listening port
   * and the port of the remote location address are the same, hence you will
   * send messages back to this sketch.
   */
  myRemoteLocation = new NetAddress("127.0.0.1",12000);
  
  /* osc plug service
   * osc messages with a specific address pattern can be automatically
   * forwarded to a specific method of an object. in this example 
   * a message with address pattern /test will be forwarded to a method
   * test(). below the method test takes 2 arguments - 2 ints. therefore each
   * message with address pattern /test and typetag ii will be forwarded to
   * the method test(int theA, int theB)
   */
  oscP5.plug(this,"test","/test");
}


public void test(int theA, int theB) {
  println("### plug event method. received a message /test.");
  println(" 2 ints received: "+theA+", "+theB);  
}


void draw() {
  background(0);
}


void mousePressed() {
  /* createan osc message with address pattern /test */
  OscMessage myMessage = new OscMessage("/test");
  
  myMessage.add(123); /* add an int to the osc message */
  myMessage.add(456); /* add a second int to the osc message */

  /* send the message */
  oscP5.send(myMessage, myRemoteLocation); 
}


/* incoming osc message are forwarded to the oscEvent method. */
void oscEvent(OscMessage theOscMessage) {
  /* with theOscMessage.isPlugged() you check if the osc message has already been
   * forwarded to a plugged method. if theOscMessage.isPlugged()==true, it has already 
   * been forwared to another method in your sketch. theOscMessage.isPlugged() can 
   * be used for double posting but is not required.
  */  
  if(theOscMessage.isPlugged()==false) {
  /* print the address pattern and the typetag of the received OscMessage */
  println("### received an osc message.");
  println("### addrpattern\t"+theOscMessage.addrPattern());
  println("### typetag\t"+theOscMessage.typetag());
  }
}

process

public void process(DatagramPacket thePacket,
                    int thePort)

incoming osc messages from an udp socket are parsed, processed and forwarded to the parent.

Specified by:

process in interface UdpPacketListener

Parameters:

thePacket - DatagramPacket

thePort - int

process

public void process(TcpPacket thePacket,
                    int thePort)

Specified by:

process in interface TcpPacketListener

See Also:

TcpPacketListener.process(netP5.TcpPacket, int)

remove

public void remove(AbstractTcpClient theTcpClient)

Specified by:

remove in interface TcpPacketListener

Parameters:

theTcpClient - AbstractTcpClient

status

public void status(int theIndex)

Specified by:

status in interface TcpPacketListener

Parameters:

theIndex - int

properties

public OscProperties properties()

returns the current properties of oscP5.

Returns:

OscProperties

isBroadcast

public boolean isBroadcast()

Returns:

boolean

ip

public String ip()

Returns:

String

setLogStatus

public static void setLogStatus(int theIndex,
                                int theValue)

oscP5 has a logging mechanism which prints out processes, warnings and errors into the console window. e.g. turn off the error log with setLogStatus(Logger.ERROR, Logger.OFF);

Parameters:

theIndex - int

theValue - int

setLogStatus

public static void setLogStatus(int theValue)

Parameters:

theValue -

setTimeToLive

public void setTimeToLive(int theTTL)

set timeToLive of a multicast packet.

Parameters:

theTTL - int

disconnect

public void disconnect(NetAddress theHost)

Parameters:

theHost - NetAddress

connect

public void connect(NetAddress theNetAddress,
                    String theName,
                    String[] theArguments)

Parameters:

theNetAddress - NetAddress

theName - String

theArguments - String[]

netInfo

public NetInfo netInfo()

netinfo() returns an instance of a NetInfo Object from which you can get LAN and WAN information.

Returns:

NetInfo

tcpServer

public TcpServer tcpServer()

return the instance of the running TCP server if in TCP mode.

Returns:

TcpServer

tcpClient

public TcpClient tcpClient()

return the instance of the running TCP client if in TCP mode.

Returns:

TcpClient

send

public void send(OscPacket thePacket,
                 NetAddress theNetAddress)

you can send osc packets in many different ways. see below and use the send method that fits your needs.

Parameters:

thePacket - OscPacket

theNetAddress - NetAddress

send

public void send(OscPacket thePacket)

Parameters:

thePacket - OscPacket

+Example

/**
 * oscP5sendreceive by andreas schlegel
 * example shows how to send and receive osc messages.
 * oscP5 website at http://www.sojamo.de/oscP5
 */
 
import oscP5.*;
import netP5.*;
  
OscP5 oscP5;
NetAddress myRemoteLocation;

void setup() {
  size(400,400);
  frameRate(25);
  /* start oscP5, listening for incoming messages at port 12000 */
  oscP5 = new OscP5(this,12000);
  
  /* myRemoteLocation is a NetAddress. a NetAddress takes 2 parameters,
   * an ip address and a port number. myRemoteLocation is used as parameter in
   * oscP5.send() when sending osc packets to another computer, device, 
   * application. usage see below. for testing purposes the listening port
   * and the port of the remote location address are the same, hence you will
   * send messages back to this sketch.
   */
  myRemoteLocation = new NetAddress("127.0.0.1",12000);
}


void draw() {
  background(0);  
}

void mousePressed() {
  /* in the following different ways of creating osc messages are shown by example */
  OscMessage myMessage = new OscMessage("/test");
  
  myMessage.add(123); /* add an int to the osc message */

  /* send the message */
  oscP5.send(myMessage, myRemoteLocation); 
}


/* incoming osc message are forwarded to the oscEvent method. */
void oscEvent(OscMessage theOscMessage) {
  /* print the address pattern and the typetag of the received OscMessage */
  print("### received an osc message.");
  print(" addrpattern: "+theOscMessage.addrPattern());
  println(" typetag: "+theOscMessage.typetag());
}

send

public void send(OscPacket thePacket,
                 NetAddressList theNetAddressList)

Parameters:

thePacket - OscPacket

theNetAddressList - NetAddressList

send

public void send(String theAddrPattern,
                 Object[] theArguments)

Parameters:

theAddrPattern - String

theArguments - Object[]

send

public void send(String theAddrPattern,
                 Object[] theArguments,
                 NetAddressList theNetAddressList)

Parameters:

theAddrPattern - String

theArguments - Object[]

theNetAddressList - NetAddressList

send

public void send(String theAddrPattern,
                 Object[] theArguments,
                 NetAddress theNetAddress)

Parameters:

theAddrPattern - String

theArguments - Object[]

theNetAddress - NetAddress

send

public void send(String theAddrPattern,
                 Object[] theArguments,
                 String theAddress,
                 int thePort)

Parameters:

theAddrPattern - String

theArguments - Object[]

theNetAddress - NetAddress

send

public void send(OscPacket thePacket,
                 TcpClient theClient)

send to tcp client

Parameters:

thePacket - OscPacket

theClient - TcpClient

send

public void send(String theAddrPattern,
                 Object[] theArguments,
                 TcpClient theClient)

Parameters:

theAddrPattern - String

theArguments - Object[]

theClient - TcpClient

send

public void send(OscPacket thePacket,
                 String theIpAddress,
                 int thePort)

Deprecated.

the send method offers a lot of possibilities. have a look at the send documentation.

Parameters:

thePacket - OscPacket

theIpAddress - String

thePort - int

stop

public void stop()

stop oscP5 and close open Sockets.

flush

public static void flush(OscMessage theOscMessage,
                         NetAddress theNetAddress)

a static method to send an OscMessage straight out of the box without having to instantiate oscP5.

Parameters:

theOscMessage - OscMessage

theNetAddress - NetAddress

+Example

 /**
 * oscP5flush by andreas schlegel
 * example shows how to send osc messages without having to instantiate an oscP5 object.
 * this can be useful if you are not listening for incoming messages and you
 * want to avoid to have the additional oscP5 thread running listening for incoming 
 * message (which you wont need if you are only sending messages).
 * oscP5 website at http://www.sojamo.de/oscP5
 */
 
import oscP5.*;
import netP5.*;


NetAddress myRemoteLocation;
void setup() {
  size(400,400);
  frameRate(25);
  /* set up a remote location */
  myRemoteLocation = new NetAddress("127.0.0.1",12000);
}


void draw() {
  background(0);
}


void mousePressed() {
  /* create a new OscMessage with an address pattern, in this case /test. */
  OscMessage myOscMessage = new OscMessage("/test");
  
  /* add a value (an integer) to the OscMessage */
  myOscMessage.add(100);
  
  /* send the OscMessage to the remote location. 
   */
  OscP5.flush(myOscMessage,myRemoteLocation);
}

flush

public static void flush(OscPacket theOscPacket,
                         NetAddress theNetAddress)

flush

public static void flush(String theAddrPattern,
                         Object[] theArguments,
                         NetAddress theNetAddress)

flush

public static void flush(byte[] theBytes,
                         NetAddress theNetAddress)

flush

public static void flush(byte[] theBytes,
                         String theAddress,
                         int thePort)

Deprecated.

Parameters:

theBytes - byte[]

theAddress - String

thePort - int

flush

public static void flush(OscMessage theOscMessage,
                         String theAddress,
                         int thePort)

Deprecated.

Parameters:

theOscMessage - OscMessage

theAddress - String

thePort - int

newMsg

public OscMessage newMsg(String theAddrPattern)

Deprecated.

Parameters:

theAddrPattern - String

Returns:

OscMessage

newBundle

public OscBundle newBundle()

Deprecated.

Parameters:

theAddrPattern - String

Returns:

OscMessage

disconnectFromTEMP

public void disconnectFromTEMP()

Deprecated.

used by the monome library by jklabs