ptcall.h

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

// of these objects and their state changes. Events that are reported by
// PtCallListener objects that pertain to PtConnections and
// PtTerminalConnections are instances of (or descendants of) the
// PtConnectionEvent class and the PtTerminalConnectionEvent class,
// respectively.
// <p>
// An event is delivered to the application whenever the state of the PtCall
// changes. The events corresponding to PtCall state changes are
// CALL_ACTIVE and CALL_INVALID.
//
// <H4>When Call Event Transmission Ends</H4>
// Applications receive events on a listener until the listener is removed
// or until the PtCall object is no longer observable. In these instances,
// each listener receives a CALL_EVENT_TRANSMISSION_ENDED event as its final
// event.
//
// <H4>Event Granularity</H4>
// An application may control the granularity of the events that are reported.
// Registering for the highest level (PtCallListener) will direct the
// implementation to send only PtCall-related events (including meta events).
// Registering as a listener at a lower level (PtConnectionListener or
// PtTerminalConnectionListener) directs the implementation to provide
// successively more detailed events.
//
// <H4>Registering Call Listeners via Address and Terminal</H4>
// Applications may also receive events about a call by adding a listener via
// the PtAddress or PtTerminal objects; this is done with the
// PtAddress.addCallListener()
// and PtTerminal.addCallListener() (and related) methods. These methods
// provide the ability for an application to receive call-related events when
// a PtCall contains a particular PtAddress or PtTerminal. In particular,
// methods exist to add a PtCallListener, PtConnectionListener and
// PtTerminalConnectionListener via PtAddress and PtTerminal.
// See the specifications for the PtAddress and PtTerminal classes for more
// details.

class PtCall
{
/* //////////////////////////// PUBLIC //////////////////////////////////// */
public:

   enum CallState
   {
      IDLE,
      ACTIVE,
      INVALID
   };

/* ============================ CREATORS ================================== */
        PtCall();
     //:Default constructor

        PtCall(TaoClientTask *pClient, const char* callId);

        PtCall(const char* callId);

        PtCall(const PtCall& rPtCall);
     //:Copy constructor (not implemented for this class)

      virtual
   ~PtCall();
     //:Destructor

/* ============================ MANIPULATORS ============================== */

   PtCall& operator=(const PtCall& rhs);
     //:Assignment operator (not implemented for this class)

   virtual PtStatus addCallListener(PtCallListener& rCallListener);
     //:Adds a listener to this call.
     //!param: (in) rCallListener - The listener to add to this call
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_EXISTS - <i>rCallListener</i> is already registered
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus addParty(const char* newPartyURL,
                     PtSessionDesc* pSessionDesc,
                     PtConnection& rConnection);
     //:Adds an additional party to an existing call.
     // This is sometimes called a "single-step conference" because a party
     // is conferenced directly into the call. The telephone address
     // provided as the <i>newPartyURL</i> argument must be valid.
     //!param: (in) newPartyURL - Address of the party to add to this call
     //!param: (in) pSessionDesc - Pointer to the requested attributes for the new connection or NULL to use defaults
     //!param: (out) rpConnection - Set to point to the PtConnection associated with the new party
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_PARTY - Invalid <i>newPartyURL</i>
     //!retcode: PT_INVALID_STATE - The call is either not ACTIVE or has fewer than two ESTABLISHED PtConnections
     //!retcode: PT_RESOURCE_UNAVAILABLE - Insufficient resources
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus conference(PtCall& rOtherCall);
     //:Merges two PtCalls together, resulting in the union of the
     //:participants of both PtCalls being placed on a single PtCall.
     // If successful, all of the participants from <i>rOtherCall</i> will
     // be moved to the PtCall on which this method is invoked.
     //!param: (in) rOtherCall - The PtCall object whose participants will be moved to this PtCall
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_ARGUMENT - The <i>rOtherCall</i> object is not valid for the conference
     //!retcode: PT_INVALID_STATE - The call is either not ACTIVE or the conference controllers are not in the proper state
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus connect(PtTerminal& rTerminal, PtAddress& rAddress,
                    const char* destinationURL, PtSessionDesc* pSessionDesc);
     //:Places a telephone call from an originating endpoint to a destination
     //:address URL.
     // The <i>pSessionDesc</i> argument points to an object containing the
     // attributes requested for the connection.
     //!param: (in) rTerminal - The originating terminal
     //!param: (in) rAddress - The originating address
     //!param: (in) destinationURL - The intended destination for the call
     //!param: (in) pSessionDesc - Pointer to the requested attributes for the new connection or NULL to use defaults
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_ARGUMENT - Bad <i>rTerminal</i>, <i>rAddress</i> or <i>rSessionDesc</i> argument
     //!retcode: PT_INVALID_PARTY - Invalid <i>destinationURL</i>
     //!retcode: PT_RESOURCE_UNAVAILABLE - Insufficient resources
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus consult(PtTerminalConnection& rTerminalConnection,
                    const char* destinationURL,
                    PtSessionDesc* pSessionDesc,
                    PtConnection& rSrcConnection,
                    PtConnection& rDstConnection);
     //:Creates a new call between the PtTerminal associated with
     //:<i>rTerminalConnection</i> and the destination indicated by
     //:<i>destinationURL</i>.
     //!param: (in) rTerminalConnection - The terminal connection used to obtain the originating terminal
     //!param: (in) destinationURL - The intended destination for the new call
     //!param: (in) pSessionDesc - Pointer to the requested attributes for the new connection or NULL to use defaults
     //!param: (out) rpSrcConnection - Set to point to the PtConnection for the origination of the call
     //!param: (out) rpDstConnection - Set to point to the PtConnection for the termination of the call
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_PARTY - Invalid <i>destinationURL</i>
     //!retcode: PT_INVALID_STATE - The call associated with <i>rTerminalConnection</i> is not ACTIVE
     //!retcode: PT_RESOURCE_UNAVAILABLE - Insufficient resources
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus drop(void);
     //:Drops the entire call.
     // This method is equivalent to using the PtConnection.disconnect()
     // method on each PtConnection which is part of the PtCall. Typically,
     // each PtConnection on the PtCall will move into the
     // PtConnection::DISCONNECTED state, each PtTerminalConnection will
     // move into the PtTerminalConnection::DROPPED state, and the PtCall
     // will move into the PtCall::INVALID state.
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus removeCallListener(PtCallListener& rCallListener);
     //:Removes the indicated listener from this call.
     //!param: (in) rCallListener - The listener to remove from this call
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_NOT_FOUND - <i>rCallListener</i> not registered
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus setConferenceController(PtTerminalConnection* pController);
     //:Sets the PtTerminalConnection that acts as the conference controller
     //:for this call.
     // The conference controller represents the participant in the call
     // around which a conference takes place.
     //!param: pController - The terminal connection to use as a conference controller for this call
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_ARGUMENT - The indicated terminal connection is not part of this call
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus setTransferController(PtTerminalConnection* pController);
     //:Sets the PtTerminalConnection that acts as the transfer controller
     //:for this call.
     // The transfer controller represents the participant in the call
     // around which a transfer takes place.
     //!param: pController - The terminal connection to use as a transfer controller for this call
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_ARGUMENT - The indicated terminal connection is not part of this call
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus transfer(PtCall& rOtherCall);
     //:Moves all participants from one PtCall to another, with the
     //:exception of a selected common participant.
     //!param: (in) rOtherCall - The PtCall object whose participants will be moved to this PtCall
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_ARGUMENT - The <i>rOtherCall</i> object is not valid for the transfer
     //!retcode: PT_INVALID_STATE - The call is either not ACTIVE or the conference controllers are not in the proper state
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus transfer(const char* destinationURL,
                     PtSessionDesc* pSessionDesc,
                     PtConnection& rNewConnection,
                                         int transferType = CpCallManager::CP_BLIND_TRANSFER);
     //:Transfers all participants currently on this PtCall, with the
     //:exception of the transfer controller participant, to the address
     //:indicated by the destination URL.
     //!param: (in) destinationURL - The intended destination for the new call
     //!param: (in) pSessionDesc - Pointer to the requested attributes for the new call or NULL to use defaults
     //!param: (out) rNewConnection - Set to point to the PtConnection that the participants have been moved to
     //!param: (in) transferType - CP_BLIND_TRANSFER or CP_SINGLE_CALL_TRANSFER
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_INVALID_PARTY - Invalid <i>destinationURL</i>
     //!retcode: PT_RESOURCE_UNAVAILABLE - Insufficient resources
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available


   virtual PtStatus hold(UtlBoolean bBridgeParticipants = TRUE) ;
     //:Places the call on hold and optionally allows call participants to
     //:continue speaking among other participants (bridged) or participants
     //:are requested to not transmit date (far end hold).
     //
     //!param (in): bBridgeParticipants - Controls whether participants are
     //             placed on local hold or far end hold.  If TRUE, local
     //             hold is selected and participants are bridged and able
     //             to communicate with each other.  If FALSE, all parties
     //             are muted and not sent audio data.
     //
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_BUSY - Unable to communicate with call processing