jtapipeer.java

Java Telephony API .java程序

/*
 * Copyright (c) 1996 Sun Microsystems, Inc. All Rights Reserved.
 *
 * Permission to use, copy, modify, and distribute this software
 * and its documentation for NON-COMMERCIAL purposes and without
 * fee is hereby granted provided that this copyright notice
 * appears in all copies. Please refer to the file "copyright.html"
 * for further important copyright and licensing information.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF
 * THE SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
 * TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
 * PARTICULAR PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR
 * ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR
 * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES.
 */

package java.telephony;

/**
 * The JtapiPeer interface represents a vendor's particular implementation
 * of the Java Telephony API. Each vendor which provides an implementation of
 * JTAPI must implement this interface.
 * <p>
 * Applications use the <EM>getProvider()</EM> method on this interface
 * to obtain new Provider objects. Each implementation may support one or
 * more different "services" (e.g. for different types of underlying network
 * substrate). A list of available services can be obtained via the
 * <EM>getServices()</EM> method.
 * <p>
 * Applications may also supply optional arguments to the Provider. These
 * arguments are appended to the string argument passed to the
 * <EM>getProvider()</EM> method. The string argument has the following
 * format:
 * <p>
 * &lt service name &gt ; arg1 = val1; arg2 = val2; ...
 * <p>
 * Where &lt service name &gt is not optional, and each optional argument pair
 * which follows is separated by a semi-colon. The keys for these arguments
 * is implementation specific, except for two standard-defined keys:
 * <OL>
 * <LI>login: provides the login user name to the Provider.
 * <LI>passwd: provides a password to the Provider.
 * </OL>
 */

public interface JtapiPeer {

  /**
   * Returns the name of this JtapiPeer object instance. This name is the same
   * name used as an argument to <EM>JtapiPeerFactory.getJtapiPeer()</EM>
   * method.
   * <p>
   * @return The name of this JtapiPeer object instance.
   */
  public String getName()
    throws PlatformException;


  /**
   * Returns the services that this implementation supports.
   * <p>
   * @return The services that this implementation supports.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public String[] getServices()
    throws PlatformException;


  /**
   * Returns an instance of a Provider object given a string argument which
   * contains the desired service name. Optional arguments may also be
   * provided in this string, with the following format:
   * <p>
   * &lt service name &gt ; arg1 = val1; arg2 = val2; ...
   * <p>
   * Where &lt service name &gt is not optional, and each optional argument pair
   * which follows is separated by a semi-colon. The keys for these arguments
   * is implementation specific, except for two standard-defined keys:
   * <OL>
   * <LI>login: provides the login user name to the Provider.
   * <LI>passwd: provides a password to the Provider.
   * </OL>
   * <p>
   * If the argument is null, this method returns some default Provider as
   * determined by the object which implements this interface.
   * <p>
   * The Provider returned is in the Provider.OUT_OF_SERVICE state, leading
   * to the following post-conditions:
   * <OL>
   * <LI>getProvider().getState() == Provider.OUT_OF_SERVICE.
   * </OL>
   * @param providerString The name of the desired service plus an optional
   * arguments.
   * @return An instance of the Provider object.
   * @exception PlatformException A platform-specific exception occurred.
   */
  public Provider getProvider(String providerString)
    throws PlatformException;
}