Module org.praxislive.internal.osc
Package org.praxislive.internal.osc

Class OSCTransmitter

  • All Implemented Interfaces:
    OSCChannel
    public abstract class OSCTransmitter
extends Object
implements OSCChannel
    A class that sends OSC packets (messages or bundles) to a target OSC server. Each instance takes a network channel, either explictly specified by a DatagramChannel (for UDP) or SocketChannel (for TCP), or internally opened when a protocol type is specified.

    Messages are send by invoking one of the send methods. For an example, please refer to the OSCReceiver document.

    Note that as of v0.3, you will most likely want to use preferably one of OSCClient or OSCServer over OSCTransmitter. Also note that as of v0.3, OSCTransmitter is abstract, which renders direct instantiation impossible. To update old code, occurences of new OSCTransmitter() must be replaced by one of the OSCTransmitter.newUsing methods!

    Version:
    0.33, 05-Mar-09
    Author:
    Hanns Holger Rutz
    See Also:
    OSCClient, OSCServer, OSCReceiver

    • Field Detail

      • sync

        protected final Object sync

      • allocBuf

        protected boolean allocBuf

      • dumpMode

        protected int dumpMode

      • revivable

        protected final boolean revivable

    • Method Detail

      • newUsing

        public static OSCTransmitter newUsing​(String protocol)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol. It picks an arbitrary free port and uses the local machine's IP. To determine the resulting port, you can use getLocalAddress afterwards.
        Parameters:
        protocol - the protocol to use, currently either UDP or TCP
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used
        See Also:
        OSCChannel.UDP, OSCChannel.TCP, getLocalAddress()

      • newUsing

        public static OSCTransmitter newUsing​(OSCPacketCodec c,
                                      String protocol)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol. It picks an arbitrary free port and uses the local machine's IP. To determine the resulting port, you can use getLocalAddress afterwards.
        Parameters:
        c - the codec to use
        protocol - the protocol to use, currently either UDP or TCP
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used
        Since:
        NetUtil 0.33
        See Also:
        OSCChannel.UDP, OSCChannel.TCP, getLocalAddress()

      • newUsing

        public static OSCTransmitter newUsing​(String protocol,
                                      int port)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and port. It uses the local machine's IP. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!
        Parameters:
        protocol - the protocol to use, currently either UDP or TCP
        port - the port number for the OSC socket, or 0 to use an arbitrary free port
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used

      • newUsing

        public static OSCTransmitter newUsing​(OSCPacketCodec c,
                                      String protocol,
                                      int port)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and port. It uses the local machine's IP. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!
        Parameters:
        c - the codec to use
        protocol - the protocol to use, currently either UDP or TCP
        port - the port number for the OSC socket, or 0 to use an arbitrary free port
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used
        Since:
        NetUtil 0.33

      • newUsing

        public static OSCTransmitter newUsing​(String protocol,
                                      int port,
                                      boolean loopBack)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and port. It uses the local machine's IP or the "loopback" address. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!
        Parameters:
        protocol - the protocol to use, currently either UDP or TCP
        port - the port number for the OSC socket, or 0 to use an arbitrary free port
        loopBack - if true, the "loopback" address ("127.0.0.1") is used which limits communication to the local machine. If false, the special IP "0.0.0.0" is used which means any local host is picked
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used

      • newUsing

        public static OSCTransmitter newUsing​(OSCPacketCodec c,
                                      String protocol,
                                      int port,
                                      boolean loopBack)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and port. It uses the local machine's IP or the "loopback" address. Note that the port specifies the local socket, not the remote (or target) port. This can be set using the setTarget method!
        Parameters:
        c - the codec to use
        protocol - the protocol to use, currently either UDP or TCP
        port - the port number for the OSC socket, or 0 to use an arbitrary free port
        loopBack - if true, the "loopback" address ("127.0.0.1") is used which limits communication to the local machine. If false, the special IP "0.0.0.0" is used which means any local host is picked
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used
        Since:
        NetUtil 0.33

      • newUsing

        public static OSCTransmitter newUsing​(String protocol,
                                      InetSocketAddress localAddress)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using default codec and a specific transport protocol and local socket address. Note that localAddress specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!
        Parameters:
        protocol - the protocol to use, currently either UDP or TCP
        localAddress - a valid address to use for the OSC socket. If the port is 0, an arbitrary free port is picked when the transmitter is connected. (you can find out the actual port in this case by calling getLocalAddress() after the transmitter was connected).
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used

      • newUsing

        public static OSCTransmitter newUsing​(OSCPacketCodec c,
                                      String protocol,
                                      InetSocketAddress localAddress)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using a specific codec and transport protocol and local socket address. Note that localAddress specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!
        Parameters:
        c - the codec to use
        protocol - the protocol to use, currently either UDP or TCP
        localAddress - a valid address to use for the OSC socket. If the port is 0, an arbitrary free port is picked when the transmitter is connected. (you can find out the actual port in this case by calling getLocalAddress() after the transmitter was connected).
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while creating the socket
        IllegalArgumentException - if an illegal protocol is used
        Since:
        NetUtil 0.33

      • newUsing

        public static OSCTransmitter newUsing​(DatagramChannel dch)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using default codec and UDP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using dch.socket().bind( SocketAddress )). Note that dch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!
        Parameters:
        dch - the DatagramChannel to use as UDP socket.
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while configuring the socket

      • newUsing

        public static OSCTransmitter newUsing​(OSCPacketCodec c,
                                      DatagramChannel dch)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using a specific codec and UDP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using dch.socket().bind( SocketAddress )). Note that dch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!
        Parameters:
        c - the codec to use
        dch - the DatagramChannel to use as UDP socket.
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while configuring the socket
        Since:
        NetUtil 0.33

      • newUsing

        public static OSCTransmitter newUsing​(SocketChannel sch)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using default codec and TCP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using sch.socket().bind( SocketAddress )). Furthermore, the channel must be connected (using connect()) before being able to transmit messages. Note that sch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!
        Parameters:
        sch - the SocketChannel to use as TCP socket.
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while configuring the socket

      • newUsing

        public static OSCTransmitter newUsing​(OSCPacketCodec c,
                                      SocketChannel sch)
                               throws IOException
        Creates a new instance of an OSCTransmitter, using a specific codec and TCP transport on a given channel. The caller should ensure that the provided channel's socket was bound to a valid address (using sch.socket().bind( SocketAddress )). Furthermore, the channel must be connected (using connect()) before being able to transmit messages. Note that sch specifies the local socket, not the remote (or target) socket. This can be set using the setTarget method!
        Parameters:
        c - the codec to use
        sch - the SocketChannel to use as TCP socket.
        Returns:
        the newly created transmitter
        Throws:
        IOException - if a networking error occurs while configuring the socket
        Since:
        NetUtil 0.33

      • getLocalAddress

        public abstract InetSocketAddress getLocalAddress()
                                           throws IOException
        Queries the transmitter's local socket address. You can determine the host and port from the returned address by calling getHostName() (or for the IP getAddress().getHostAddress()) and getPort(). This port number may be 0 if the transmitter was called with an unspecified port and has not yet been connected. In this case, to determine the port actually used, call this method after the transmitter has been connected.
        Specified by:
        getLocalAddress in interface OSCChannel
        Returns:
        the address of the transmitter's local socket.
        Throws:
        IOException - if the local host could not be resolved
        See Also:
        InetSocketAddress.getHostName(), InetSocketAddress.getAddress(), InetSocketAddress.getPort()

      • setTarget

        public void setTarget​(SocketAddress target)
        Specifies the transmitter's target address, that is the address of the remote side to talk to. You should call this method only once and you must call it before starting to send messages using the shortcut call send( OSCPacket ).
        Parameters:
        target - the address of the remote target socket. Usually you construct an appropriate InetSocketAddress
        See Also:
        InetSocketAddress

      • setCodec

        public void setCodec​(OSCPacketCodec c)
        Description copied from interface: OSCChannel
        Specifies which codec is used in packet coding and decoding.
        Specified by:
        setCodec in interface OSCChannel
        Parameters:
        c - the codec to use

      • connect

        public abstract void connect()
                      throws IOException
        Establishes connection for transports requiring connectivity (e.g. TCP). For transports that do not require connectivity (e.g. UDP), this ensures the communication channel is created and bound.

        When a UDP transmitter is created without an explicit DatagramChannel – say by calling OSCTransmitter.newUsing( "udp" ), you are required to call connect() so that an actual DatagramChannel is created and bound. For a UDP transmitter which was created with an explicit DatagramChannel, this method does noting, so it is always safe to call connect(). However, for TCP transmitters, this may throw an IOException if the transmitter was already connected, therefore be sure to check isConnected() before.

        Throws:
        IOException - if a networking error occurs. Possible reasons: - the underlying network channel had been closed by the server. - the transport is TCP and the server is not available. - the transport is TCP and an OSCReceiver sharing the same socket was stopped before (unable to revive).
        See Also:
        isConnected()

      • isConnected

        public abstract boolean isConnected()
        Queries the connection state of the transmitter.
        Returns:
        true if the transmitter is connected, false otherwise. For transports that do not use connectivity (e.g. UDP) this returns false, if the underlying DatagramChannel has not yet been created.
        See Also:
        connect()

      • send

        public final void send​(OSCPacket p,
                       SocketAddress target)
                throws IOException
        Sends an OSC packet (bundle or message) to the given network address, using the current codec.
        Parameters:
        p - the packet to send
        target - the target address to send the packet to
        Throws:
        IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs

      • send

        public abstract void send​(OSCPacketCodec c,
                          OSCPacket p,
                          SocketAddress target)
                   throws IOException
        Sends an OSC packet (bundle or message) to the given network address, using a particular codec.
        Parameters:
        c - the codec to use
        p - the packet to send
        target - the target address to send the packet to
        Throws:
        IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs
        Since:
        NetUtil 0.33

      • send

        public final void send​(OSCPacket p)
                throws IOException
        Sends an OSC packet (bundle or message) to the default network address, using the current codec. The default address is the one specified using the setTarget method. Therefore this will throw a NullPointerException if no default address was specified.
        Parameters:
        p - the packet to send
        Throws:
        IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs
        NullPointerException - if no default address was specified
        See Also:
        setTarget( SocketAddress )

      • send

        public abstract void send​(OSCPacketCodec c,
                          OSCPacket p)
                   throws IOException
        Sends an OSC packet (bundle or message) to the default network address, using a particular codec. The default address is the one specified using the setTarget method. Therefore this will throw a NullPointerException if no default address was specified.
        Parameters:
        c - the codec to use
        p - the packet to send
        Throws:
        IOException - if a write error, OSC encoding error, buffer overflow error or network error occurs
        NullPointerException - if no default address was specified
        Since:
        NetUtil 0.33
        See Also:
        setTarget( SocketAddress )

      • setBufferSize

        public void setBufferSize​(int size)
        Description copied from interface: OSCChannel
        Adjusts the buffer size for OSC messages. This is the maximum size an OSC packet (bundle or message) can grow to.
        Specified by:
        setBufferSize in interface OSCChannel
        Parameters:
        size - the new size in bytes.
        See Also:
        OSCChannel.getBufferSize()

      • getBufferSize

        public int getBufferSize()
        Description copied from interface: OSCChannel
        Queries the buffer size used for coding or decoding OSC messages. This is the maximum size an OSC packet (bundle or message) can grow to.
        Specified by:
        getBufferSize in interface OSCChannel
        Returns:
        the buffer size in bytes.
        See Also:
        OSCChannel.setBufferSize( int )

      • dumpOSC

        public void dumpOSC​(int mode,
                    PrintStream stream)
        Description copied from interface: OSCChannel
        Changes the way processed OSC messages are printed to the standard err console. By default messages are not printed.
        Specified by:
        dumpOSC in interface OSCChannel
        Parameters:
        mode - one of kDumpOff (don't dump, default), kDumpText (dump human readable string), kDumpHex (hexdump), or kDumpBoth (both text and hex)
        stream - the stream to print on, or null which is shorthand for System.err
        See Also:
        OSCChannel.kDumpOff, OSCChannel.kDumpText, OSCChannel.kDumpHex, OSCChannel.kDumpBoth

      • dispose

        public void dispose()
        Description copied from interface: OSCChannel
        Disposes the resources associated with the OSC communicator. The object should not be used any more after calling this method.
        Specified by:
        dispose in interface OSCChannel

      • checkBuffer

        protected void checkBuffer()