JSR-043: JTAPI-1.4

javax.telephony.callcontrol
Interface CallControlAddress

All Superinterfaces:
Address

public interface CallControlAddress
extends Address

Introduction

The CallControlAddress interface extends the core Address interface. It provides additional features on the Address. Applications may query an Address object using the instanceof operator to see whether it supports this interface.

Address Forwarding

This interface supports methods which permit applications to modify and query the forwarding characteristics of an Address. The forwarding characteristics determine how incoming telephone calls to this Address should be handled, if any special handling is desired. A switching domain will honor those instructions to the extent that other possibly higher priority instructions allow.

Each Address may have zero or more forwarding instructions. Each instruction describes how the switching domain should handle incoming telephone calls to an Address under different circumstances. Examples of forwarding instructions are "forward all calls to x9999" or "forward all calls to x7777 when no one answers." Each forwarding instruction is represented by an instance of the CallControlForwarding class. A switching domain will honor forwarding instructions to the extent that other (possibly higher priority) instructions allow.

Applications assign a list of forwarding instructions via the the CallControlAddress.setForwarding() method. To obtain the current, effective forwarding instructions, applications invoke the CallControlAddress.getForwarding() method. To cancel all forwarding instructions, applications use the CallControlAddress.cancelForwarding() method.

Do Not Disturb and Message Waiting

The CallControlAddress interface defines two additional attributes: do-not-disturb and message-waiting.

The do-not-disturb feature gives the means to notify the telephony platform that an Address does not want to receive incoming telephone calls. That is, if this feature is activated, the underlying telephony platform will not alert this Address to incoming telephone calls. Applications use the CallControlAddress.setDoNotDisturb() method to activate or deactivate this feature and the CallControlAddress.getDoNotDisturb() method to return the current state of this attribute.

Note that the CallControlTerminal interface also has a do-not-disturb attribute. This gives the ability to control the do not disturb property at either the Address level (e.g. a phone number) or at the Terminal level (e.g. an individual phone.)

The message-waiting attribute indicates whether there are messages waiting for a human user of the Address. These messages may either be maintained by an application or some telephony platform. Applications inform the telephony hardware of the message waiting status, and typically the hardware displays a visible indicator (e.g. an LED) to users. Applications use the CallControlAddress.setMessageWaiting() method to activate or deactivate this feature and the CallControlAddress.getMessageWaiting() method to return the current state of this attribute.

Observers and Events

All events pertaining to the CallControlAddress interface are reported via the AddressObserver.addressChangedEvent() method. The application observer object must also implement the CallControlCallObserver interface to express interest in the call control package events.

The following are the events associated with this interface:

CallCtlAddrDoNotDisturbEv Indicates the do-not-disturb feature of this Address has changed.
CallCtlAddrForwardEv Indicates the forwarding characteristics of this Address has changed.
CallCtlAddrMessageWaitingEv Indicates the message waiting characteristics of this Address has changed.

See Also:
CallControlTerminal, CallControlForwarding, CallControlAddressObserver, CallCtlAddrDoNotDisturbEv, CallCtlAddrForwardEv, CallCtlAddrMessageWaitingEv

Method Summary
 void cancelForwarding()
          Cancels all of the forwarding instructions on this Address.
 boolean getDoNotDisturb()
          Returns true if the do-not-disturb feature is activated, false otherwise.
 CallControlForwarding[] getForwarding()
          Returns an array of forwarding instructions currently effective for this Address.
 boolean getMessageWaiting()
          Returns true if the message waiting is activated, false otherwise.
 void setDoNotDisturb(boolean enable)
          Specifies whether the do-not-disturb feature should be activated or deactivated for this Address.
 void setForwarding(CallControlForwarding[] instructions)
          Sets the forwarding characteristics for this Address.
 void setMessageWaiting(boolean enable)
          Specifies whether the message-waiting indicator should be activated or deactivated for this Address.
 
Methods inherited from interface javax.telephony.Address
addAddressListener, addCallListener, addCallObserver, addObserver, getAddressCapabilities, getAddressListeners, getCallListeners, getCallObservers, getCapabilities, getConnections, getName, getObservers, getProvider, getTerminals, removeAddressListener, removeCallListener, removeCallObserver, removeObserver
 

Method Detail

setForwarding

public void setForwarding(CallControlForwarding[] instructions)
                   throws MethodNotSupportedException,
                          InvalidStateException,
                          InvalidArgumentException
Sets the forwarding characteristics for this Address. This forwarding command supplants all previous forwarding instructions if it succedes, otherwise the forwarding state at the time of the command remains unchanged. This method takes an array of CallControlForwarding objects. Each object describes a different forwarding. This method waits until all forwarding instructions have been set or until an error occurs and an exception is thrown.

Pre-conditions:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
Post-conditions:
  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. this.getForwarding() == instructions
  3. CallCtlAddrForwardEv is delivered for this Address
Parameters:
instructions - An array of Address forwarding instructions
Throws:
MethodNotSupportedException - This method is not supported by the given implementation.
InvalidStateException - The Provider is not "in service".
InvalidArgumentException - An invalid set of forwarding instructions were given as a parameter.
See Also:
CallCtlAddrForwardEv

getForwarding

public CallControlForwarding[] getForwarding()
                                      throws MethodNotSupportedException
Returns an array of forwarding instructions currently effective for this Address. If there are no effective forwarding instructions, this method returns null.

Returns:
An array of Address forwarding instructions, null if there are none.
Throws:
MethodNotSupportedException - This method is not supported by the given implementation.

cancelForwarding

public void cancelForwarding()
                      throws MethodNotSupportedException,
                             InvalidStateException
Cancels all of the forwarding instructions on this Address. When this method completes, the CallControlAddress.getForwarding() method will return null. This method waits until all forwarding instructions have been cancelled or until an error occurs and an exception is thrown.

Pre-conditions:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
Post-conditions:
  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. this.getForwarding == null
  3. CallCtlAddrForwardEv is delivered for this Address.
Throws:
MethodNotSupportedException - This method is not supported by the given implementation.
InvalidStateException - The Provider is not "in service".
See Also:
CallCtlAddrForwardEv

getDoNotDisturb

public boolean getDoNotDisturb()
                        throws MethodNotSupportedException
Returns true if the do-not-disturb feature is activated, false otherwise.

Returns:
True if do-not-disturb feature is activated, false if it is deactivated.
Throws:
MethodNotSupportedException - This method is not supported by the given implementation.

setDoNotDisturb

public void setDoNotDisturb(boolean enable)
                     throws MethodNotSupportedException,
                            InvalidStateException
Specifies whether the do-not-disturb feature should be activated or deactivated for this Address. This feature only affects whether or not calls will be accepted at this Address. Note that the do-not-disturb feature on all Terminals associated with this Address are independent of this Terminal's do-not-disturb setting. If 'enable' is true, do-not-disturb is activated if not already activated. If 'enable' is false, do-not-disturb is deactivated if not already deactivated.

Pre-conditions:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
Post-conditions:
  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. this.getDoNotDisturb() == enable
  3. CallCtlAddrDoNotDisturbEv is delivered for this Address
Parameters:
enable - True to activate do-not-disturb, false to deactivate.
Throws:
MethodNotSupportedException - This method is not supported by the given implementation.
InvalidStateException - The Provider is not "in service".
See Also:
CallCtlAddrDoNotDisturbEv

getMessageWaiting

public boolean getMessageWaiting()
                          throws MethodNotSupportedException
Returns true if the message waiting is activated, false otherwise.

Returns:
True if message-waiting is activated, false if it is deactivated.
Throws:
MethodNotSupportedException - This method is not supported by the given implementation.

setMessageWaiting

public void setMessageWaiting(boolean enable)
                       throws MethodNotSupportedException,
                              InvalidStateException
Specifies whether the message-waiting indicator should be activated or deactivated for this Address. If 'enable' is true, message-waiting is activated if not already activated. If 'enable' is false, message-waiting is deactivated if not already deactivated.

Pre-conditions:

  1. (this.getProvider()).getState() == Provider.IN_SERVICE
Post-conditions:
  1. (this.getProvider()).getState() == Provider.IN_SERVICE
  2. this.getMessageWaiting() == enable
  3. CallCtlAddrMessageWaitingEv is delivered for this Address
Parameters:
enable - True to activate message-waiting, false to deactivate.
Throws:
MethodNotSupportedException - This method is not supported by the given implementation.
InvalidStateException - The Provider is not "in service".
See Also:
CallCtlAddrMessageWaitingEv

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org