de.sciss.net
Class OSCMessage

java.lang.Object
  de.sciss.net.OSCPacket
      de.sciss.net.OSCMessage

public class OSCMessage
extends OSCPacket

Class for decoding OSC messages from received datagrams or encoding OSC message for sending to a target socket. See opensoundcontrol.org/spec-1_0 for the specification of the message format.

Here is an example:

      DatagramChannel dch = null;

      final ByteBuffer buf        = ByteBuffer.allocateDirect( 1024 );
      final SocketAddress addr    = new InetSocketAddress( "localhost", 57110 );
      final Random rnd            = new Random( System.currentTimeMillis() );

      try {
          dch = DatagramChannel.open();
          dch.configureBlocking( true );
          new OSCMessage( "/s_new", new Object[] { "default",
                          new Integer( 1001 ), new Integer( 1 ), new Integer( 0 ),
                          "out", new Integer( 0 ), "freq", new Float( 0 ), "amp", new Float( 0.1f )}
          ).encode( buf );
          buf.flip();
          dch.send( buf, addr );
          
          for( int i = 0; i < 11; i++ ) {
              buf.clear();
              // no schoenheitsprize
              new OSCMessage( "/n_set", new Object[] { new Integer( 1001 ),
                  "freq", new Float( 333 * Math.pow( 2, rnd.nextInt( 12 ) / 12.0f ))}
              ).encode( buf );
              buf.flip();
              dch.send( buf, addr );
              Thread.currentThread().sleep( 300 );
          }
          buf.clear();
          new OSCMessage( "/n_free", new Object[] { new Integer( 1001 )}).encode( buf );
          buf.flip();
          dch.send( buf, addr );
      }
      catch( InterruptedException e1 ) {}
      catch( IOException e2 ) {
          System.err.println( e2.getLocalizedMessage() );
      }
      finally {
          if( dch != null ) {
              try {
                  dch.close();
              }
              catch( IOException e4 ) {};
          }
      }
        

Note that this example uses the old way of sending messages. A easier way is to create an OSCTransmitter which handles the byte buffer for you. See the OSCReceiver doc for an example using a dedicated transmitter.

Version:

0.33, 28-Apr-07

Author:

Hanns Holger Rutz

See Also:

OSCReceiver

Field Summary

static Object[]

NO_ARGS Shorthand to pass to the constructor if you want to create an OSC message which doesn't contain any arguments.

Constructor Summary

OSCMessage(String name)
Creates a generic OSC message with no arguments.

OSCMessage(String name, Object[] args)
Creates a generic OSC message from Primitive arguments.

Method Summary

static OSCMessage	decodeMessage(String command, ByteBuffer b) Creates a new message with arguments decoded from the ByteBuffer, using the default codec.
Object	getArg(int index) Returns the argument at the given index.
int	getArgCount() Returns the number of arguments of the message.
String	getName() Returns the OSC command of this message

Methods inherited from class de.sciss.net.OSCPacket

decode, encode, encode, getSize, getSize, printHexOn, printTextOn

Methods inherited from class java.lang.Object

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

Field Detail

NO_ARGS

public static final Object[] NO_ARGS

Shorthand to pass to the constructor if you want to create an OSC message which doesn't contain any arguments. Note: alternatively you can use the constructor new OSCMessage( String ).

See Also:

OSCMessage( String )

Constructor Detail

OSCMessage

public OSCMessage(String name)

Creates a generic OSC message with no arguments.

Parameters:

name - the OSC command, like "/s_new"

OSCMessage

public OSCMessage(String name,
                  Object[] args)

Creates a generic OSC message from Primitive arguments.

Parameters:

name - the OSC command, like "/s_new"

args - array of arguments which are simply assembled. Supported types are Integer, Long, Float, Double, String, furthermore byte[] and OSCPacket (both of which are written as a blob). Note that in a future version of NetUtil, special codecs will allow customization of the way classes are encoded.

Method Detail

getName

public String getName()

Returns the OSC command of this message

Returns:

the message's command, e.g. "/synced" etc.

getArgCount

public int getArgCount()

Returns the number of arguments of the message.

Returns:

the number of typed arguments in the message. e.g. for [ "/n_go", 1001, 0, -1, -1, 0 ] it returns 5.

getArg

public Object getArg(int index)

Returns the argument at the given index. See decodeMessage() for information about the used java classes. The most fail-safe way to handle numeric arguments is to assume Number instead of a particular number subclass. To read a primitive int, the recommended code is ((Number) msg.getArg( index )).intValue(), which will work with any of Integer, Long, Float, Double.

Parameters:

index - index of the argument, beginning at zero, must be less than getArgCount()

Returns:

the primitive type (Integer, Float, String etc.) argument at the given index. e.g. for [ "/n_go", 1001, 0, -1, -1, 0 ], requesting index 0 would return new Integer( 1001 ).

See Also:

getArgCount(), decodeMessage( String, ByteBuffer ), Number.intValue()

decodeMessage

public static OSCMessage decodeMessage(String command,
                                       ByteBuffer b)
                                throws IOException

Creates a new message with arguments decoded from the ByteBuffer, using the default codec. Usually you call decode from the OSCPacket superclass or directly from the OSCPacketCodec.

Parameters:

b - ByteBuffer pointing right at the beginning of the type declaration section of the OSC message, i.e. the name was skipped before.

Returns:

new OSC message representing the received message described by the ByteBuffer.

Throws:

IOException - in case some of the reading or decoding procedures failed.

IllegalArgumentException - occurs in some cases of buffer underflow

See Also:

OSCPacketCodec.decodeMessage( String, ByteBuffer )