ptaddress.h

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

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

#ifndef _PtAddress_h_
#define _PtAddress_h_

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

// DEFINES
// MACROS
// EXTERNAL FUNCTIONS
// EXTERNAL VARIABLES
// CONSTANTS
// STRUCTS
// TYPEDEFS
// FORWARD DECLARATIONS
class PtAddressForwarding;
class PtAddressListener;
class PtCallListener;
class PtConnection;
class PtProvider;
class PtTerminal;
class TaoObjectMap;
class TaoReference;
class PtAddress;
class PtCall;
class PtProviderListener;
class TaoClientTask;
class TaoServerTask;

//:A PtAddress object represents what we commonly think of as a phone number.
// However, for calls to IP telephony endpoints, the "telephone number" is
// a URL or IP address identifying the endpoint.
// <p>
// Address objects may be classified into two categories: local and remote.
// <br>
// <ul>
// <li><b>Local address objects</b> are those addresses that are part of the
// provider's local domain. All of the provider's currently known local
// addresses are reported via the PtProvider.getAddresses() method. </li>
// <p>
// <li><B>Remote address objects</B> are those outside of the provider's domain
// that the provider learns about during its lifetime through various happenings
// (for example, an incoming call from a currently unknown address). Remote
// addresses are not reported via the PtProvider.getAddresses() method. </li>
// </ul><p>
// Note that applications may not create PtAddress objects. The PtProvider
// begins with knowledge of certain PtAddress objects within its local domain.
// This list is quasi-static, changing only as logical endpoints are added
// and removed in the phone system.
//
// <H3>Address and Terminal Objects</H3>
// PtAddress and PtTerminal objects exist in a many-to-many relationship. A
// PtAddress object may have zero or more PtTerminals associated with it.
// Each PtTerminal associated with a PtAddress must reflect its association
// with the PtAddress. The PtTerminals associated with a PtAddress are given
// by the PtAddress.getTerminals() method.
// <p>
// An association between a PtAddress and a PtTerminal indicates that the
// terminal is addressable via that address. In many instances, a telephone
// set (represented by a PtTerminal object) has only one telephone number
// (represented by a PtAddress object) associated with it. In more complex
// configurations, telephone sets may have several telephone numbers
// associated with them. Likewise, a telephone number may appear on more
// than one telephone set.
//
// <H3>Address and Call Objects</H3>
// PtAddress objects represent the logical endpoints of a telephone call. A
// logical view of a telephone call views the call as originating from one
// PtAddress endpoint and terminating at another PtAddress endpoint.
// <p>
// PtAddress objects are related to PtCall objects via the PtConnection
// object. The PtConnection object has a state that describes the current
// relationship between the call and the address. Each PtAddress object may
// be part of more than one telephone call, and in each case, is represented
// by a separate PtConnection object. The PtAddress.getConnections() method
// returns all PtConnection objects currently associated with the call.
// <p>
// An address is associated with a call until the connection moves into the
// PtConnection::DISCONNECTED state. At that time, the connection is no longer
// reported by the PtAddress.getConnections() method. Therefore, the
// PtAddress.getConnections() method will never report a connection in the
// PtConnection::DISCONNECTED state.
//
// <H3>Address Listeners and Events</H3>
// All changes in a PtAddress object are reported via PtAddressListener
// objects. Applications instantiate an object which is derived from the
// PtAddressListener class and use the PtAddress.addAddressListener() method
// to begin the delivery of events. All address-related events reported via
// a PtAddressListener are instances of either the PtAddressEvent class
// or its descendants.  Applications receive events on a listener until the
// listener is removed via the PtAddress.removeAddressListener() method, or
// until the PtAddress is no longer observable. In these instances, each
// AddressListener receives an ADDRESS_EVENT_TRANSMISSION_ENDED event as its
// final event.
//
// <H3>Call Listeners</H3>
// At times, applications may want to monitor a particular address for all
// calls that come to that address. For example, a customer service agent
// application may only be interested in telephone calls that are associated
// with a particular agent address. To achieve this sort of address-based call
// monitoring, applications may add PtCallListeners to a PtAddress via the
// PtAddress.addCallListener() method.
// <p>
// When a PtCallListener is added to a PtAddress, this listener instance is
// immediately added to all calls at this address, and is added to all calls
// which come to this address in the future. These listeners remain on the
// telephone call as long as the address is associated with the telephone
// call.
//
// <H3>Address Forwarding</H3>
// This class supports methods which permit applications to modify and query
// the forwarding characteristics of a PtAddress. The forwarding
// characteristics determine how incoming telephone calls to this PtAddress
// should be handled, if any special handling is desired.
// <p>
// Each PtAddress may have zero or more forwarding instructions. Each
// instruction describes how the switching domain should handle incoming
// telephone calls to a PtAddress 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 PtAddressForwarding class.
// <p>
// Applications assign a list of forwarding instructions via the
// PtAddress.setForwarding() method. To obtain the current,
// effective forwarding instructions, applications invoke the
// PtAddress.getForwarding() method. To cancel all forwarding
// instructions, applications use the PtAddress.cancelForwarding()
// method.
//
// <H3>Do-not-disturb and Message-waiting</H3>
// The <i>do-not-disturb</i> 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 <b>not</b> alert this PtAddress to incoming telephone calls. Applications
// use the PtAddress.setDoNotDisturb() method to activate and deactivate this
// feature, and the PtAddress.getDoNotDisturb() method to return the current
// state of this attribute.
// <p>
// Note that the PtTerminal interface also has a <i>do-not-disturb</i>
// attribute. This gives the ability to control the <i>do-not-disturb</i>
// property at either the PtAddress level (for example, a phone number) or
// at the PtTerminal level (for example, an individual phone.)
// <p>
// The <i>message-waiting</i> attribute indicates whether there are messages
// waiting for a human user of the address. These messages may be maintained
// either by an application or by some telephony platform. Applications
// inform the phone set of the message waiting status, and typically
// the phone set displays a visible indicator (such as an LED) to users.
// Applications use the PtAddress.setMessageWaiting() method to activate and
// deactivate this feature, and the PtAddress.getMessageWaiting() method to
// return the current state of this attribute.
//
// <H3>Offered Timeout</H3>
// The offered timeout attribute for a PtAddress indicates how long the
// connection for an incoming call will stay in the PtConnection::OFFERED
// state before it transitions to the PtConnection::ALERTING state.  By
// default, the offered timeout for a PtAddress is 0.  This means that as
// soon as the connection for the incoming call is offered on a PtAddress,
// the PtTerminals for that address will begin alerting (by ringing, for
// example).
// <p>
// To implement services such as call screening or find-me-follow-me,
// applications must be allowed to explicitly accept, reject or
// redirect connections that are offered to a PtAddress.  Setting the
// offered timeout for a PtAddress to a positive number causes the
// PtConnection to stay in the PtConnection::OFFERED state until the
// PtCall is either explicitly accepted, rejected, or redirected, or until the
// offered timeout expires, whichever comes first.  If the offered timeout
// expires before the call is explicitly accepted, rejected, or
// redirected, the PtConnection transitions to the PtConnection::ALERTING
// state.
// <p>
// The timer-based transition of the PtConnection from
// PtConnection::OFFERED to PtConnection::ALERTING may be disabled by
// setting the offered timeout for the PtAddress to -1.

class PtAddress
{
/* //////////////////////////// PUBLIC //////////////////////////////////// */
public:

/* ============================ CREATORS ================================== */

        PtAddress();
         //:Default constructor

        PtAddress(TaoClientTask *pClient, const char* name);

        PtAddress(PtProvider *pProvider, const char* address);

        PtAddress(const PtAddress& rPtAddress);
         //:Copy constructor (not implemented for this class)

        PtAddress(const char* address);

        virtual
        ~PtAddress();
     //:Destructor

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

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

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

   virtual PtStatus addCallListener(PtCallListener& rCallListener);
     //:Adds a listener to a PtCall object when this PtAddress object first
     //:becomes part of that PtCall.
     //!param: (in) rCallListener - The listener to add to calls associated with this address
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_EXISTS - <i>rCallListener</i> is already registered
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus cancelForwarding(void);
     //:Cancels all of the forwarding instructions on this address.
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available

   virtual PtStatus cancelForwarding(PtAddressForwarding forwards[], int size);
     //:Cancels forwarding instructions in forwards on this address.
     //!param: (in) forwards - the forwarding instructions to remove
     //!param: (in) size - the number of forwarding instructions to remove
     //!retcode: PT_SUCCESS - Success
     //!retcode: PT_PROVIDER_UNAVAILABLE - The provider is not available