provider.java

Java Telephony API .java程序

   * <p>
   * @return An array of Terminals known by this provider.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Terminal[] getTerminals()
    throws PlatformException;


  /**
   * Returns an instance of the Terminal class which corresponds to the
   * given name. Each Terminal has a unique name associated with it, which
   * is assigned to it by the JTAPI implementation.  If
   * no Terminal is available for the given name within the Provider's
   * domain, this method throws the InvalidArgumentException. This Terminal
   * must be in the array generated by <EM>Provider.getTerminals().</EM>
   * <p>
   * The pre-condition predicates for this method is:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>this.getTerminal(name) is an element of this.getTerminals()
   * </OL>
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>this.getTerminal(name) is an element of this.getTerminals()
   * </OL>
   * <p>
   * @param name The name of desired Terminal object.
   * @return The Terminal object associated with the given name.
   * @exception InvalidArgumentException The name provided does not correspond
   * to a name of any Terminal known to the Provider or within the Provider's
   * domain.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Terminal getTerminal(String name)
    throws InvalidArgumentException, PlatformException;


  /**
   * Instructs the Provider to shut itself down and perform all neccessary
   * cleanup. Applications invoke this method when they no longer intend to
   * use the Provider, most often right before they exit. This
   * method is intended to allow the Provider to perform any neccessary
   * cleanup which would not be taken care of when the Java objects are
   * garbage collected. This method causes the Provider to move into the
   * Provider.SHUTDOWN state, in which it will stay indefinitely.
   * <p>
   * The pre-conditions for this method are:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * </OL>
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>this.getState() == Provider.SHUTDOWN
   * </OL>
   * <p>
   * @exception InvalidStateException This Provider object is not in the
   * Provider.IN_SERVICE state.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public void shutdown()
    throws InvalidStateException, PlatformException;


  /**
   * Creates and returns a new instance of the Call object. This new call
   * object is in the Call.IDLE state and has no connections. An exception is
   * generated if a new call cannot be created.
   * <p>
   * The pre-condition predicates for this method are:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * </OL>
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>this.getState() == Provider.IN_SERVICE
   * <LI>Let Call call = this.createCall();
   * <LI>call.getState() == Call.IDLE.
   * <LI>call.getConnections() == null
   * <LI>call is an element of this.getCalls()
   * </OL>
   * <p>
   * @return The new Call object.
   * @exception ResourceUnavailableException An internal resource neccessary
   * to create a new Call object is unavailable.
   * @exception InvalidStateException The Provider is not in the
   * Provider.IN_SERVICE state.
   * @exception PrivilegeViolationException The application does not have
   * the proper authority to create a new telephone call object.
   * @exception MethodNotSupportedException The implementation does not support
   * creating new Call objects.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Call createCall()
    throws ResourceUnavailableException, InvalidStateException,
      PrivilegeViolationException, MethodNotSupportedException,
      PlatformException;

  
  /**
   * Adds an observer to the Provider. The ProviderObserver reports all
   * Provider-related state changes as events. The Provider bject will report
   * events to this ProviderObserver object for the lifetime
   * of the Provider object or until the observer is removed with the
   * <EM>Provider.removeObserver()</EM> method.
   * <p>
   * This method is valid anytime and has no pre-conditions. Application must
   * have the ability to add observers to Providers so they can monitor
   * the changes in state in the Provider.
   * <p>
   * If an application attempts to add an instance of an observer already
   * present on this Provider, then repeated attempts to add the instance
   * of the observer will silently fail, i.e. multiple instances of an
   * observer are not added and no exception will be thrown.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is an element of this.getObservers()
   * </OL>
   * <p>
   * @param observer The observer being added.
   * @exception ResourceUnavailableException The resource limit for the
   * numbers of observers has been exceeded.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void addObserver(ProviderObserver observer)
    throws ResourceUnavailableException, PlatformException;


  /**
   * Returns a list of all ProviderObservers associated with this call object.
   * If no observers exist on this Provider, then this method returns null.
   * <p>
   * There are no preconditions for this method. The application must be
   * able to get the list of observers even when the Provider is not in
   * the IN_SERVICE state.
   * <p>
   * The post-conditions for this method are:
   * <OL>
   * <LI>Let ProviderObserver[] obs = this.getObservers()
   * <LI>obs == null or obs.length >= 1
   * </OL>
   * <p>
   * @return An array of ProviderObserver objects associated with this
   * Provider.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public ProviderObserver[] getObservers()
    throws PlatformException;


  /**
   * Removes the given observer from the Provider. If successful, the observer
   * will no longer receive events generated by this call object.
   * <p>
   * There are no pre-conditions for this method. Application should be able
   * to remove observers even if the Provider is not in the IN_SERVICE state.
   * <p>
   * Also, if an observer is not part of the Provider, then this method
   * fails silently, i.e. no observer is removed an no exception is thrown.
   * <p>
   * The post-condition predicates for this method are:
   * <OL>
   * <LI>observer is not an element of this.getObservers()
   * </OL>
   * <p>
   * @param observer The observer which is being removed.
   * @exception PlatformException A platform-specific exception occurred.
   */ 
  public void removeObserver(ProviderObserver observer)
    throws InvalidArgumentException;


  /**
   * Returns the ProviderCapabilities object with respect to a Terminal.
   * If null is passed as a Terminal parameter, the general/provider-wide 
   * Provider capabilities
   * are returned.
   * <p>
   * @exception InvalidArgumentException invalid argument exception occurred
   * @exception PlatformException A platform-specific exception occurred.
   */
  public ProviderCapabilities getProviderCapabilities(Terminal term)
    throws InvalidArgumentException, PlatformException;


  /**
   * Gets the CallCapabilities object with respect to a Terminal.
   * If null is passed as a Terminal parameter, the general/provider-wide 
   * Call capabilities
   * are returned.
   * <p>
   * @param terminal the terminal whose call capabilities are being queried
   * @exception InvalidArgumentException invalid argument exception occurred
   * @exception PlatformException A platform-specific exception occurred.
   */
  public CallCapabilities getCallCapabilities(Terminal terminal,Address address)
    throws InvalidArgumentException, PlatformException;


  /**
   * Gets the ConnectionCapabilities object with respect to a Terminal.
   * If null is passed as a Terminal parameter, the general/provider-wide 
   * Connection capabilities
   * are returned.
   * <p>
   * @param terminal the terminal whose connection capabilities are being 
   * queried
   * @exception InvalidArgumentException invalid argument exception occurred
   * @exception PlatformException A platform-specific exception occurred.
   */
  public ConnectionCapabilities getConnectionCapabilities(Terminal terminal,Address address)
    throws InvalidArgumentException, PlatformException;


  /**
   * Gets the AddressCapabilities object with respect to a Terminal.
   * If null is passed as a Terminal parameter, the general/provider-wide 
   * Address capabilities
   * are returned.
   * <p>
   * @param terminal the terminal whose address capabilities are being 
   * queried
   * @exception InvalidArgumentException invalid argument exception occurred
   * @exception PlatformException A platform-specific exception occurred.
   */
  public AddressCapabilities getAddressCapabilities(Terminal terminal)
    throws InvalidArgumentException, PlatformException;


  /**
   * Gets the TerminalConnectionCapabilities of a Terminal.
   * If null is passed as a Terminal parameter, the general/provider-wide 
   * TerminalConnection capabilities
   * are returned.
   * <p>
   * @param terminal the terminal whose terminal connection capabilities 
   * are being queried
   * @exception InvalidArgumentException invalid argument exception occurred
   * @exception PlatformException A platform-specific exception occurred.
   */
  public TerminalConnectionCapabilities getTerminalConnectionCapabilities(Terminal terminal)
    throws InvalidArgumentException, PlatformException;


  /**
   * Gets the TerminalCapabilities object with respect to a Terminal.
   * If null is passed as a Terminal parameter, the general/provider-wide 
   * Terminal capabilities
   * are returned.
   * <p>
   * @param terminal the terminal whose capabilities are being queried
   * @exception InvalidArgumentException invalid argument exception occurred
   * @exception PlatformException A platform-specific exception occurred.
   */
  public TerminalCapabilities getTerminalCapabilities(Terminal terminal)
    throws InvalidArgumentException, PlatformException;
}