javax.telephony.media.connection
Interface MediaConnection

All Superinterfaces:

MediaConnectionConstants

public interface MediaConnection

extends MediaConnectionConstants

The MediaService API for inter-Group connections.

Note: this is an optional interface. A platform-specific MediaService (not necessarily BasicMediaService) implements MediaConnection and Connectable. Use (ms instanceof MediaConnection) to verify that a MediaService object supports this interface.

Note: the target object must also implement Connectable. Eventually, things other than a MediaService could be Connectable. For example, a Conference object, or a reference to a external MediaService. Maybe even a JTAPI Call!

Note: multi-party conference service can be modeled by a MediaService that is configured to contain a Conference Resource. To bridge() or join() to such a MediaService constitutes "joining the conference". The Conference Resource may also have an API for floor control, volume control, etc.

Since:

JTAPI-1.4

Inner Class Summary

static interface

MediaConnection.Token Each Token represents a connection between the the MediaGroups of two bound MediaService objects.

Fields inherited from interface javax.telephony.media.connection.MediaConnectionConstants

ev_Bridge, ev_Connect, ev_Disconnect, ev_Join, ev_Loopback, ev_SetDataFlow, v_AllConnections, v_AllSecondary, v_Both, v_Bridge, v_Join, v_Listen, v_Loopback, v_None, v_Primary, v_PrimaryToPrimary, v_PrimaryToSecondary, v_SecondaryToSecondary, v_Talk

Method Summary

MediaConnection.Token	bridge(Connectable otherConnectable, Symbol maxDataFlow, Symbol initialDataFlow) Create a v_Bridge connection from this to the other Connectable.
MediaConnection.Token	connect(Symbol connType, Connectable otherConnectable, Symbol maxDataFlow, Symbol initialDataFlow) Create a connection from this to the other Connectable.
void	disconnect(MediaConnection.Token connection) Disconnect the given connection.
void	disconnect(Symbol connection) Disconnect the given connection.
MediaConnection.Token	join(Connectable otherConnectable, Symbol maxDataFlow, Symbol initialDataFlow) Create a v_Primary connection from this to the other Connectable.
MediaConnection.Token	loopback(Connectable otherConnectable, Symbol maxDataFlow, Symbol initialDataFlow) Create a v_Loopback connection from this to the other Connectable.
void	setDataFlow(MediaConnection.Token connection, Symbol dataFlow) Change the data flow direction of a connection.
void	setDataFlow(Symbol connection, Symbol dataFlow) Change the data flow direction of a connection.

Method Detail

connect

public MediaConnection.Token connect(Symbol connType,
                                     Connectable otherConnectable,
                                     Symbol maxDataFlow,
                                     Symbol initialDataFlow)
                              throws MediaConnectionException

Create a connection from this to the other Connectable. The type of connection is determined by the first argument.

Parameters:

connType - one of v_Bridge, v_Join, v_Loopback.

otherConnectable - a Connectable or null to unattach.

maxDataFlow - a Symbol indicating flow directions to be reserved.

initialDataFlow - a Symbol indicating the initial data flow

Returns:

a MediaConnectionEvent

Throws:

MediaConnectionException - if requested operation fails.

bridge

public MediaConnection.Token bridge(Connectable otherConnectable,
                                    Symbol maxDataFlow,
                                    Symbol initialDataFlow)
                             throws MediaConnectionException

Create a v_Bridge connection from this to the other Connectable.

Parameters:

otherConnectable - a Connectable or null to unattach.

maxDataFlow - a Symbol indicating flow directions to be reserved.

initialDataFlow - a Symbol indicating the initial data flow

Returns:

a MediaConnectionEvent

Throws:

MediaConnectionException - if requested operation fails.

join

public MediaConnection.Token join(Connectable otherConnectable,
                                  Symbol maxDataFlow,
                                  Symbol initialDataFlow)
                           throws MediaConnectionException

Create a v_Primary connection from this to the other Connectable. The other Connectable gets a v_Secondary connection.

Parameters:

otherConnectable - a Connectable that accepts a secondary connection.

maxDataFlow - a Symbol indicating flow directions to be reserved.

initialDataFlow - a Symbol indicating the initial data flow

Returns:

a MediaConnectionEvent.

Throws:

MediaConnectionException -

loopback

public MediaConnection.Token loopback(Connectable otherConnectable,
                                      Symbol maxDataFlow,
                                      Symbol initialDataFlow)
                               throws MediaConnectionException

Create a v_Loopback connection from this to the other Connectable.

Parameters:

otherConnectable - a Connectable or null to unattach.

maxDataFlow - a Symbol indicating flow directions to be reserved.

initialDataFlow - a Symbol indicating the initial data flow

Returns:

a MediaConnectionEvent

Throws:

MediaConnectionException - if requested operation fails.

disconnect

public void disconnect(MediaConnection.Token connection)
                throws MediaConnectionException

Disconnect the given connection. The other end receives ev_disconnect.

Parameters:

connection - a Token identifying the connection to be disconnected.

Throws:

MediaConnectionException - if requested operation fails.

disconnect

public void disconnect(Symbol connection)
                throws MediaConnectionException

Disconnect the given connection. The other end receives ev_disconnect.

Parameters:

connection - a Symbol identifying the connection(s) to be disconnected. One of: v_PrimaryConnection, v_AllSecondary, v_AllConnections

Throws:

MediaConnectionException - if requested operation fails.

setDataFlow

public void setDataFlow(MediaConnection.Token connection,
                        Symbol dataFlow)
                 throws MediaConnectionException

Change the data flow direction of a connection. The dataFlow can be set to one of: v_Both, v_Talk, v_Listen, v_None. The new dataFlow must not exceed the maxDataFlow established when this connection was created.

Note: v_Talk and v_Listen are with respect to the Connectable on which this method is invoked.

Parameters:

connection - a Token identifying the connection to be changed.

dataFlow - a Symbol to indicate the new direction(s) of flow.

Throws:

MediaConnectionException - if requested operation fails.

setDataFlow

public void setDataFlow(Symbol connection,
                        Symbol dataFlow)
                 throws MediaConnectionException

Change the data flow direction of a connection. The dataFlow can be set to one of: v_Both, v_Talk, v_Listen, v_None. The new dataFlow must not exceed the maxDataFlow established when this connection was created.

Note: v_Talk and v_Listen are with respect to the Connectable on which this method is invoked.

Parameters:

connection - a Symbol identifying the connection(s) to be changed. One of: v_PrimaryConnection, v_AllSecondary, v_AllConnections

dataFlow - a Symbol to indicate the new direction(s) of flow.

Throws:

MediaConnectionException - if requested operation fails.