de.sciss.net
Class OSCPacket

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

Direct Known Subclasses:

OSCBundle, OSCMessage

public abstract class OSCPacket
extends Object

OSCPacket is the superclass of OSC messages and bundles. It provides methods that apply to both of these OSC packet types, like calculating the packet's size encoding the packet from a given byte buffer or decoding a received message from a given buffer.

Version:

0.33, 25-Feb-08

Author:

Hanns Holger Rutz

Constructor Summary

protected

OSCPacket() Constructs a new OSCPacket.

Method Summary

static OSCPacket	decode(ByteBuffer b) Creates a new packet decoded from the ByteBuffer, using the default codec.
void	encode(ByteBuffer b) Encodes the contents of this packet into the provided ByteBuffer, beginning at the buffer's current position, using the default codec.
void	encode(OSCPacketCodec c, ByteBuffer b) Encodes the contents of this packet into the provided ByteBuffer, beginning at the buffer's current position, using a given codec.
int	getSize() Calculates and returns the packet's size in bytes, using the default codec.
int	getSize(OSCPacketCodec c) Calculates and returns the packet's size in bytes, using a given codec.
static void	printHexOn(PrintStream stream, ByteBuffer b) Prints a hexdump version of a packet to a given stream.
static void	printTextOn(PrintStream stream, OSCPacket p) Prints a text version of a packet to a given stream.

Methods inherited from class java.lang.Object

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

Constructor Detail

OSCPacket

protected OSCPacket()

Constructs a new OSCPacket. Refer to the subclasses for the particular way they instantiate the class

Method Detail

getSize

public final int getSize()
                  throws IOException

Calculates and returns the packet's size in bytes, using the default codec.

Returns:

the size of the packet in bytes, including the initial osc command and aligned to 4-byte boundary. this is the amount of bytes written by the encode method.

Throws:

IOException - if an error occurs during the calculation

See Also:

getSize( OSCPacketCodec )

getSize

public final int getSize(OSCPacketCodec c)
                  throws IOException

Calculates and returns the packet's size in bytes, using a given codec.

Parameters:

c - the codec that is shall used for encoding the packet

Returns:

the size of the packet in bytes, including the initial osc command and aligned to 4-byte boundary. this is the amount of bytes written by the encode method.

Throws:

IOException - if an error occurs during the calculation

See Also:

OSCPacketCodec.getSize( OSCPacket )

encode

public final void encode(ByteBuffer b)
                  throws IOException

Encodes the contents of this packet into the provided ByteBuffer, beginning at the buffer's current position, using the default codec. To write the encoded packet, you will typically call flip() on the buffer, then write() on the channel.

Parameters:

b - ByteBuffer pointing right at the beginning of the osc packet. buffer position will be right after the end of the packet when the method returns.

Throws:

IOException - in case some of the writing procedures failed.

See Also:

encode( OSCPacketCodec, ByteBuffer )

encode

public final void encode(OSCPacketCodec c,
                         ByteBuffer b)
                  throws IOException

Encodes the contents of this packet into the provided ByteBuffer, beginning at the buffer's current position, using a given codec. To write the encoded packet, you will typically call flip() on the buffer, then write() on the channel.

Parameters:

b - ByteBuffer pointing right at the beginning of the osc packet. buffer position will be right after the end of the packet when the method returns.

c - the codec that is shall used for encoding the packet

Throws:

IOException - in case some of the writing procedures failed.

See Also:

OSCPacketCodec.encode( OSCPacket, ByteBuffer )

decode

public static OSCPacket decode(ByteBuffer b)
                        throws IOException

Creates a new packet decoded from the ByteBuffer, using the default codec. This method simply calls the equivalent method in OSCPacketCodec.

Parameters:

b - ByteBuffer pointing right at the beginning of the packet. the buffer's limited should be set appropriately to allow the complete packet to be read. when the method returns, the buffer's position is right after the end of the packet.

Returns:

new decoded OSC packet

Throws:

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

IllegalArgumentException - occurs in some cases of buffer underflow

See Also:

OSCPacketCodec.decode( ByteBuffer )

printTextOn

public static void printTextOn(PrintStream stream,
                               OSCPacket p)

Prints a text version of a packet to a given stream. The format is similar to scsynth using dump mode 1. Bundles will be printed with each message on a separate line and increasing indent.

Parameters:

stream - the print stream to use, for example System.out

p - the packet to print (either a message or bundle)

printHexOn

public static void printHexOn(PrintStream stream,
                              ByteBuffer b)

Prints a hexdump version of a packet to a given stream. The format is similar to scsynth using dump mode 2. Unlike printTextOn this takes a raw received or encoded byte buffer and not a decoded instance of OSCPacket.

Parameters:

stream - the print stream to use, for example System.out

b - the byte buffer containing the packet. read position should be at the very beginning of the packet, limit should be at the end of the packet. this method alters the buffer position in a manner that a successive flip() will restore the original position and limit.

See Also:

Buffer.limit(), Buffer.position()