Class: TTelephoneHandsetHandle

Declaration: TelephonyClasses.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

The standard hardware-independent surrogate for the physical telephone terminal equipment (that is, the desktop unit connected to the wall jack rather than the telephone line itself). It provides a mechanism for monitoring the handset's hook status and will eventually 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.

Deriving Classes:

This class can be derived to accommodate handsets with additional capabilities, such as buttons and displays.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Resource Use:

Depending on whether other handles exist for the line in question, construction of this class might cause a new TTelephoneLine derived class to be constructed by the telephone server. Destruction of this class might cause the server to delete the corresponding TTelephoneLine derived class. 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: TTelephoneHandsetHandle::TTelephoneHandsetHandle

  1. TTelephoneHandsetHandle (const TTelephoneHandsetConfigurationData &)
  2. TTelephoneHandsetHandle (const TTelephoneHandsetHandle &)
  3. TTelephoneHandsetHandle ()

Interface Category:

API.

Purpose:

  1. Creates a TTelephoneHandsetHandle using the specified configuration information.
  2. Copy constructor.
  3. Default constructor.

Calling Context:

  1. Call directly at construction.
  2. Call directly to copy an object.
  3. Call directly for streaming and assignment.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

Construction of this class might cause a new TTelephoneHandset derived class to be constructed by the handset server.

Member Function: TTelephoneHandsetHandle::~TTelephoneHandsetHandle

virtual ~ TTelephoneHandsetHandle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

Destruction of this class might cause the server to delete the corresponding TTelephoneHandset derived class.

Member Function: TTelephoneHandsetHandle::operator=

TTelephoneHandsetHandle & operator =(const TTelephoneHandsetHandle &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call directly when an object is assigned to another compatible object.

Parameters:

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

Calling this function might cause the server to delete and/or create a new TTelephoneHandsetHandle derived class.

Member Function: TTelephoneHandsetHandle::IsOnHook

virtual bool IsOnHook () const

Interface Category:

API.

Purpose:

Determines whether the handset is on hook.

Calling Context:

Call directly to determine the current hook status.

Parameters:

Return Value:

Returns true if the handset is on hook.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

None.

Member Function: TTelephoneHandsetHandle::IsConnected

virtual bool IsConnected () const

Interface Category:

API.

Purpose:

Determines whether the handset is connected to a telephone line.

Calling Context:

Call directly to determine the current connection status.

Parameters:

Return Value:

Returns true if the handset is connected to a line.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

None.

Member Function: TTelephoneHandsetHandle::ConnectToTelephoneLine

virtual void ConnectToTelephoneLine (const TTelephoneLineHandle &)

Interface Category:

API.

Purpose:

Connects the handset to a telephone line. Taking the handset off hook or putting it on hook affects the hook status of the associated line.

Calling Context:

Call directly when the handset is to be associated with a specific telephone line.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

None.

Member Function: TTelephoneHandsetHandle::DisconnectFromTelephoneLine

virtual void DisconnectFromTelephoneLine ()

Interface Category:

API.

Purpose:

Disconnects the handset from a telephone line. Taking the handset off hook or putting it on hook no longer affects the hook status of the dissociated line.

Calling Context:

Call directly when the handset is to be dissociated from a specific line.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

None.

Member Function: TTelephoneHandsetHandle::CreateLineConfigurationData

virtual TTelephoneLineConfigurationData * CreateLineConfigurationData () const

Interface Category:

API.

Purpose:

Creates a configuration data object for the currently connected telephone line.

Calling Context:

Call directly to determine what line is currently connected.

Parameters:

Return Value:

Returns a pointer to a new telephone line configuration object identifying the connected line.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

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

Member Function: TTelephoneHandsetHandle::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:

Call directly to determine what telephone lines are available for connection to this handset.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

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

Member Function: TTelephoneHandsetHandle::CreateHookInterest

virtual TInterest * CreateHookInterest () const

Interface Category:

API.

Purpose:

Creates a new hook status interest object.

Calling Context:

Call directly. By adding or adopting the interest created by this function into a notification connection, the client can register to receive notification every time the handset's hook status changes.

Parameters:

Return Value:

Returns a TInterest pointer referencing a TTelephoneInterest derived class.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

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

Member Function: TTelephoneHandsetHandle::CreateRingInterest

virtual TInterest * CreateRingInterest () const

Interface Category:

API.

Purpose:

Creates a new ring status interest object.

Calling Context:

Call directly. By adding or adopting the interest created by this function into a notification connection, the client can register to receive notification of any incoming calls on the connected line. Parameters:

Return Value:

Returns a TInterest pointer referencing a TTelephoneInterest derived class.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

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

Member Function: TTelephoneHandsetHandle::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called by the Collection classes to generate a hash value.

Parameters:

Return Value:

The numeric value of the hash.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe. Not intended to be shared across address spaces.

Other Considerations:

None.

Member Function: TTelephoneHandsetHandle::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call directly to stream in data.

Parameters:

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. Not intended to be shared across address spaces.

Other Considerations:

Calling this function might cause the server to delete and/or create a new TTelephoneHandset derived class.

Member Function: TTelephoneHandsetHandle::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call directly to stream out data.

Parameters:

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. Not intended to be shared across address spaces.

Other Considerations:

None.
Click the icon to mail questions or corrections about this material to Taligent personnel.
Copyright©1995 Taligent,Inc. All rights reserved.