Class: TTelephoneHandset

Declaration: TelephoneHandset.h

Taxonomy Categories:

Member Functions:

~TTelephoneHandset
SetConfigurationData
CreateConfigurationData
Unreachable
Hash
operator<<=
operator>>=
GetNotifier
TTelephoneHandset
operator=
ReceiveUpdate
SetHookStatus
FindLine
UpdateHookStatus
UpdateConnectionStatus
CreateLineConfigurationData
CreateConnectibleLineConfigurations
ConnectToTelephoneLine
DisconnectFromTelephoneLine
CreateHookNotification
CreateRingNotification

Interface Category:

API.

Inherits From:

MRemoteDispatcher, MDelegatingNotifier, MReferenceCounted

Inherited By:

None.

Purpose:

An abstract base class that provides a software model for the physical telephone terminal equipment (that is, the desktop unit connected to the wall jack rather than the telephone line itself). Associated with each phone line is: (1) a hook state (on-hook or off-hook), (2) a set of telephone line configuration objects identifying the line(s) to which it is physically possible to connect the handset. TTelephoneHandset defines a standard interface for managing connections with these telephone lines. Derived classes must override the pure virtual functions ConnectToTelephoneLine and DisconnectFromTelephoneLine with implementations appropriate to the available hardware. Rather than instantiating TTelephoneHandset derived classes directly, Application Frameworks clients request handset services via an intermediate handle object, TTelephoneHandsetHandle. Eventually, TTelephoneHandset will permit handsets with the proper interface to be used as microphones and speakers by the Audio Framework.

Instantiation:

Allocate on the heap or the stack. Normally allocated on heap by the handset server.

Deriving Classes:

Derived classes of this abstract class override its pure virtual member functions in order to communicate with a specific telephone handset. Deriving classes may also override ReceiveUpdate to do special processing of telephony events.

Concurrency:

Multithread safe.

Resource Use:

Once configured and installed, handsets are created and deleted automatically by the handset server. The server retains pointers to all handsets in use. The current implementation of this class also makes use of the remote caller/dispatcher mechanism as well as the Notification Framework and consumes the resources associated with these services.

Member Function: TTelephoneHandset::~TTelephoneHandset

virtual ~ TTelephoneHandset ()

Interface Category:

API.

Purpose:

Destructor. Releases the resources associated with TTelephoneHandset.

Calling Context:

Called to destroy an object. Should only be called after creating a handset for configuration. It is called automatically by the handset server when a handset is no longer needed.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::SetConfigurationData

virtual void SetConfigurationData (const TTelephoneHandsetConfigurationData &)

Interface Category:

API.

Purpose:

Specifies new configuration information for a previously configured handset.

Calling Context:

Call directly when the handset needs to be reconfigured.

Parameters:

const TTelephoneLineConfigurationData & -Specifies the lines available for connection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::CreateConfigurationData

virtual TTelephoneHandsetConfigurationData * CreateConfigurationData () const

Interface Category:

API.

Purpose:

Permits the handset to be queried regarding its current configuration.

Calling Context:

Call directly when the handset configuration needs to be extracted or verified.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a new configuration data object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The caller must assume responsibility for the storage referenced by the pointer returned.

Member Function: TTelephoneHandset::Unreachable

virtual void Unreachable ()

Interface Category:

API.

Purpose:

Overrides inherited MReferenceCounted function.

Calling Context:

Used by framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Used by collection classes.

Parameters:

Takes no parameters.

Return Value:

The numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Only for internal use by Server. Developers should treat as protected.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if the versions don't match.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call directly to store handset configuration.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::GetNotifier

virtual MNotifier * GetNotifier () const

Interface Category:

API.

Purpose:

Overrides inherited MDelegatingNotifier function.

Calling Context:

Used by Notification Framework.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to the delegated notifier.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The telephone handset retains responsibility for the storage referenced by the pointer returned.

Member Function: TTelephoneHandset::TTelephoneHandset

TTelephoneHandset (const TTelephoneHandsetConfigurationData &)
TTelephoneHandset (const TTelephoneHandset &)
TTelephoneHandset ()

Interface Category:

API.

Purpose:

Creates a TTelephoneHandset using the specified configuration information.
Copy constructor.
Default constructor. Used to resurrect a configured TTelephoneHandset from disk.

Calling Context:

Called via derived class constructors during installation to specify connectible line(s).
Used by Telephony Framework. Called by derived class copy constructors.
Used by Telephony Framework. Called by derived class constructors.

Parameters:

const TTelephoneHandsetConfigurationData & -Specifies connectible line(s).
const TTelephoneHandset & -The TTelephoneHandset to be copied.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::operator=

TTelephoneHandset & operator =(const TTelephoneHandset &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called by derived classes when an object is assigned to another compatible object.

Parameters:

const TTelephoneLine & -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::ReceiveUpdate

virtual void ReceiveUpdate (const TNotification &)

Interface Category:

API.

Purpose:

Distributes notification of the hook status. Updates state information for the internal hook. Can be overridden by derived classes to do special processing of telephony events, in which case the inherited function should always be called from the overriding function.

Calling Context:

Used by Telephony Framework to propagate hook status events.

Parameters:

const TNotification & -Contains a TInterest derived class appropriate to the telephony event in question (TTelephoneInterest). Notifications should be allocated by means of one of the Create Notification calls provided by TTelephoneHandset.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Calls the Notify member function inherited from MDelegatingNotifier.

Member Function: TTelephoneHandset::SetHookStatus

virtual void SetHookStatus (const TToken & theStatus)

Interface Category:

API.

Purpose:

Modifies the telephone handset's current hook status.

Calling Context:

Called automatically by the base class in response to a hook status event.

Parameters:

const TToken & -Receives the current hook status. (Potential values are defined in the class TTelephoneStatusNotification.)

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::FindLine

virtual TTelephoneLine* FindLine (const TTelephoneLineConfigurationData & )

Interface Category:

API.

Purpose:

Locates a pointer to a connectible telephone line.

Calling Context:

Called by the handset to communicate with the telephone line to be connected.

Parameters:

const TTelephoneLineConfigurationData & -Specifies the telephone line to be located.

Return Value:

TTelephoneLine * -A pointer to the specified connectible line.

Exceptions:

Throws a TTelephonyException if the specified line cannot be found.

Concurrency:

Multithread safe.

Other Considerations:

The telephone handset retains responsibility for the storage referenced by pointer returned.

Member Function: TTelephoneHandset::UpdateHookStatus

virtual TToken UpdateHookStatus () const

Interface Category:

API.

Purpose:

Returns the current hook status of the handset instance.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request for a status update.

Parameters:

Takes no parameters.

Return Value:

Returns a TToken containing the current hook status value. (Potential values are defined in the class TTelephoneStatusNotification.)

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::UpdateConnectionStatus

virtual bool UpdateConnectionStatus () const

Interface Category:

API.

Purpose:

Returns the current connection status of the handset instance.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request for a status update.

Parameters:

Takes no parameters.

Return Value:

Returns true if handset is currently connected to a telephone line.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneHandset::CreateLineConfigurationData

virtual TTelephoneLineConfigurationData * CreateLineConfigurationData () const

Interface Category:

API.

Purpose:

Creates and returns a copy of the configuration data object for the currently connected line. Used be baseclass implementation.

Calling Context:

Called via the remote dispatcher to extract the configuration for the current line.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a new configuration data object.

Exceptions:

Throws TTelephonyException if no line is connected.

Concurrency:

Multithread safe.

Other Considerations:

The caller must assume responsibility for the storage referenced by the pointer returned.

Member Function: TTelephoneHandset::CreateConnectibleLineConfigurations

virtual void CreateConnectibleLineConfigurations (TCollectionOf<TTelephoneLineConfigurationData> & connectibleLineConfigurations) const

Interface Category:

API.

Purpose:

Creates a list of a configuration data objects for the telephone lines to which the handset can be connected.

Calling Context:

Called via the remote dispatcher mechanism to determine what telephone lines are available for connection to this handset.

Parameters:

TCollectionOf<TTelephoneLineConfigurationData> & connectibleLineConfigurations -The collection to which the configuration objects are to be added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The caller must assume storage responsibility for the configuration objects contained in the collection parameter.

Member Function: TTelephoneHandset::ConnectToTelephoneLine

virtual void ConnectToTelephoneLine (const TTelephoneLineConfigurationData&)

Interface Category:

API.

Purpose:

Connects the handset to a telephone line. All audio input/output is subsequently directed to the connected line rather than to the host computer's Audio Framework.

Calling Context:

Called via the remote dispatcher mechanism to associate the handset to a specific telephone line.

Parameters:

const TTelephoneLineConfigurationData & -Specifies the line to be connected.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Pure virtual member function.

Member Function: TTelephoneHandset::DisconnectFromTelephoneLine

virtual void DisconnectFromTelephoneLine ()

Interface Category:

API.

Purpose:

Disconnects the handset from a telephone line. All audio input/output is subsequently directed to the host computer's Audio Framework rather than to the telephone line.

Calling Context:

Called via the remote dispatcher mechanism to disassociate the handset from a specific telephone line.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Pure virtual member function.

Member Function: TTelephoneHandset::CreateHookNotification

virtual TNotification * CreateHookNotification (const TToken & hookState, TTelephoneStatusNotification :: ETelephoneStatusClassification classification =TTelephoneStatusNotification :: kSuccess) const

Interface Category:

API.

Purpose:

Allocates a notification object for a hook status event. The resulting pointer should be passed as a parameter to the ReceiveUpdate function in order to update the telephone handset's hook status and to distribute the event to interested notification connections.

Calling Context:

Called by derived classes in response to telephony hardware activity.

Parameters:

const TToken & hookState -The new hook status. (Potential values are defined in the class TTelephoneStatusNotification.)
TTelephoneStatusNotification :: ETelephoneStatusClassification classification =TTelephoneStatusNotification :: kSuccess -The notification classification. It defaults to Success.

Return Value:

Returns a TNotification pointer referencing a TTelephoneStatusNotification derived class.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The caller must assume responsibility for the storage referenced by the pointer returned.

Member Function: TTelephoneHandset::CreateRingNotification

virtual TNotification * CreateRingNotification (const TText & incomingPhoneNumber) const

Interface Category:

API.

Purpose:

Allocates a notification object for an incoming ring event. The resulting pointer should be passed as a parameter to the ReceiveUpdate function in order to distribute the event to interested notification connections.

Calling Context:

Called by derived classes in response to telephony hardware activity.

Parameters:

const TText & phoneNumber -The phone number of the calling party, if available.

Return Value:

Returns a TNotification pointer referencing a TTelephoneRingNotification derived class.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The caller must assume responsibility for the storage referenced by the pointer returned.

Click the icon to mail questions or corrections about this material to Taligent personnel.