ptcall.h

基于sipfoundy 公司开发的sipx协议API

//
// Copyright (C) 2004, 2005 Pingtel Corp.
// 
//
// $$
////////////////////////////////////////////////////////////////////////
//////

#ifndef _PtCall_h_
#define _PtCall_h_

// SYSTEM INCLUDES
// APPLICATION INCLUDES
#include <ptapi/PtDefs.h>
#include "os/OsBSem.h"
#include "os/OsProtectEventMgr.h"
#include "cp/CpCallManager.h"

// DEFINES
// MACROS
// EXTERNAL FUNCTIONS
// EXTERNAL VARIABLES
// CONSTANTS
// STRUCTS
// TYPEDEFS
// FORWARD DECLARATIONS
class PtAddress;
class PtCallListener;
class PtConnection;
class PtProvider;
class PtSessionDesc;
class PtTerminal;
class PtTerminalConnection;
class TaoClientTask;
class TaoServerTask;
class TaoReference;
class TaoObjectMap;

//:A PtCall object models a telephone call.
// A call can have zero or more connections. A two-party call has two
// connections, and a conference call has three or more connections.
// Each connection models the relationship between a call and an address,
// where an address identifies a particular party or set of parties on a
// call.
//
// <H3>Creating PtCall Objects</H3>
// Applications create instances of a PtCall object with the
// PtProvider.createCall() method, which returns a pointer to a PtCall
// object that has zero PtConnections and is in the PtCall::IDLE state.
// The PtCall maintains a reference to its provider for the life of that
// PtCall object. The PtProvider associated with a PtCall is obtained
// via the PtCall.getProvider() method.
//
// <H3>Call States</H3>
// A PtCall has a state that is obtained via the PtCall.getState() method.
// This state describes the current progress of a telephone call, where it is
// in its life cycle, and how many connections exist on the call. The PtCall
// state may be one of three values: PtCall::IDLE, PtCall::ACTIVE, or
// PtCall::INVALID. A description of each state follows.<br>
// <br>
// <dl>
// <dt><b>PtCall::IDLE</b></dt>
// <dd>This is the initial state for all calls. In this state, the call has
// zero connections; that is, PtCall.getConnections() must return an empty
// array.</dd>
// <br>
// <dt><b>PtCall::ACTIVE</b></dt>
// <dd>A call with some current ongoing activity is in this state. Calls with
// one or more associated connections must be in this state. If a call is
// in this state, the PtCall.getConnections() method must return an array
// containing at least one item.</dd>
// <br>
// <dt><b>PtCall::INVALID</b></dt>
// <dd>This is the final state for all calls. PtCall objects that lose all of
// their PtConnection objects (via a transition of the PtConnection object
// into the PtConnection::DISCONNECTED state) move into this state. Calls in
// this state have zero connections and these PtCall objects may not be used
// for any future action. In this state, the PtCall.getConnections() method
// must return an empty array. </dd>
// </dl>
// <H3>Calls and Connections</H3>
// A PtCall maintains a list of the PtConnections on that call. Applications
// obtain an array of PtConnection pointers associated with the call via the
// PtCall.getConnections() method. A PtCall retains a reference to a
// PtConnection only if it is not in the PtConnection::DISCONNECTED state.
// Therefore, if a PtCall has a reference to a PtConnection, then that
// PtConnection must not be in the PtConnection::DISCONNECTED state. When a
// connection moves into the PtConnection::DISCONNECTED state (e.g., when a
// party hangs up), the PtCall loses its reference to that PtConnection, which
// is then no longer reported via the PtCall.getConnections() method.
//
// <H3>Call Information methods</H3>
// The PtCall class provides methods that return the calling address, calling
// terminal, called address, and last redirected address information.  These
// methods only make sense for a two-party call.<br> <br>
// <ul>
// <li>The <b>calling address</b>, as returned by the PtCall.getCallingAddress()
// method, is the PtAddress that originally placed the PtCall. </li><br>
// <br>
// <li>The <b>calling terminal</b>, as returned by the PtCall.getCallingTerminal()
// method, is the PtTerminal which originally placed the PtCall. </li><br>
// <br>
// <li>The <b>called address</b>, as returned by the PtCall.getCalledAddress()
// method, is the PtAddress to which the PtCall was originally placed. </li><br>
// <br>
// <li>The <b>last redirected address</b>, as returned by the
// PtCall.getLastRedirectedAddress() method, is the PtAddress to which this
// PtCall was placed before the current destination address. For example, if
// a PtCall was forwarded from one PtAddress to another, then the first
// PtAddress is the last redirected PtAddress for this call.</li></ul>
// <p>
// Each of these methods returns NULL if their values are unknown at the
// present time. During the lifetime of a PtCall, an implementation may
// learn this additional information and, as a result, return different values
// for some or all of these methods.
//
// <H3>Conferencing Telephone Calls</H3>
// The conferencing feature supported by this interface permits two telephone
// calls to be "merged". That is, two PtCalls are merged into a single
// PtCall with the union of all of the participants of the two PtCalls being
// placed on the single PtCall.
// <p>
// Applications invoke the PtCall.conference() method to perform the
// conferencing feature. This method is given the "second" PtCall as an
// argument. All participants are moved from the second PtCall to the PtCall
// on which the method is invoked.  The second PtCall moves into the
// PtCall::INVALID state as a result.
// <p>
// In order for the conferencing feature to happen, there must be a common
// participant in both PtCalls, as represented by a single PtTerminal and
// two PtTerminalConnections, one on each of the two PtCalls. These two
// PtTerminalConnections are known as the conference controllers. In the
// real world, one of the two telephone calls must be on hold with respect
// to the controlling PtTerminal, and hence, the PtTerminalConnection on
// the second PtCall must be in the PtTerminalConnection::HELD state. The
// two conference controlling PtTerminalConnections are merged into one as
// a result of this method.
// <p>
// Applications may control which PtTerminalConnection acts as the
// conference controller via the PtCall.setConferenceController() method.
// The PtCall.getConferenceController() method returns the current
// conference controller, or NULL if there is none. If no conference
// controller is set, the implementation chooses a suitable
// PtTerminalConnection when the conferencing feature is invoked.
//
// <H3>Transferring Telephone Calls</H3>
// The transfer feature supported by this interface permits one PtCall to
// be "moved" to another PtCall. That is, all of the participants from
// one PtCall are moved to another PtCall, except for the transferring
// participant which drops off from both PtCalls.
// <p>
// Applications invoke the PtCall.transfer() method to perform the transfer
// feature. There are two overloaded versions of this method: <br>
// <ul>
// <li>The first
// method takes a second PtCall as an argument. This method acts similarly
// to PtCall.conference(), except the two PtTerminalConnections on each
// PtCall with a common PtTerminal are removed from both PtCalls. </li>
// <br>
// <li>The second
// version takes a telephone address URL as an argument. This method
// removes the transfer controller participant while placing the telephone
// call to the designated address. This version of the transfer
// feature is often known as a single-step transfer. </li>
// </ul>
// <p>
// In order for the transfer feature to happen, there must be a participant
// which acts as the transfer controller. The transfer controller is a
// PtTerminalConnection around which the transfer is performed. In the first
// version of the PtCall.transfer() method, the transfer controller must be
// present on each of the two PtCalls and share a common PtTerminal. In the
// second version, the transfer controller only applies to the PtCall object
// on which the method is invoked (since there is no second PtCall involved).
// In both cases, the transfer controller participant is no longer part of
// any PtCall once the transfer feature is complete.
// <p>
// Applications may control which PtTerminalConnection acts as the transfer
// controller via the PtCall.setTransferController() method. The
// PtCall.getTransferController() method returns the current transfer
// controller, or NULL if there is none. If no transfer controller is set,
// the implementation chooses a suitable PtTerminalConnection when the
// conferencing feature is invoked.
//
// <H3>Consultation Calls</H3>
// Consultation calls are special types of telephony calls created (often
// temporarily) for a specific purpose. Consultation calls can be created if
// a user wants to "consult" with another party briefly while currently on
// a PtCall, or for the purpose of conferencing or transferring
// with a PtCall. Consequently, consultation calls are always associated
// with another existing PtCall.
// <p>
// Applications invoke the PtCall.consult() method to perform the
// consultation feature. The instance on which the method is invoked is
// always the "idle" PtCall on which the consultation takes place.
// This method takes a
// PtTerminalConnection and a string telephone address URL as arguments.
// This consultation telephone call is associated with the PtCall of the
// PtTerminalConnection argument. This method places a telephone call from
// the same originating endpoint specified by the PtTerminalConnection
// argument to the designated telephone address.
// <h3>
// Additional Methods</h3>
// The PtCall.addParty() method adds a single party to a PtCall given some
// telephone address URL. The PtCall.drop() method then disconnects all parties
// from the PtCall, and moves it into the PtCall::INVALID state.
//
// <H3>Listeners and Events</H3>
// All events pertaining to a PtCall object are reported via
// PtCallListener objects. Applications instantiate an object that is
// derived from the PtCallListener class and use the PtCall.addCallListener()
// method to begin the delivery of events.
// <p>
// PtConnection-related and PtTerminalConnection-related events are also
// reported via the PtCallListener objects. These events include the creation