Class: TTelephoneLineHandle

Declaration: TelephonyClasses.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

The standard hardware-independent surrogate for a telephone line, it permits the Application Frameworks to identify and access telephony services from a specific telephone network connection specified by means of construction arguments. It also provides member functions for determining the hook status of the line, initiating and terminating telephone call connections, and creating control objects that provide access to advanced telephone features such as hold, transfer, conference, and forward.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

It is intended that the behavior of this class be extended by adding TTelephoneLineFeature and TTelephoneLineFeatureControl derived classes rather than by deriving TTelephoneLineHandle.

Concurrency:

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

Resource Use:

Depending on whether or not other handles exist for the line in question, construction of this class might cause a new TTelephoneLine derived class to be constructed by the handset 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. TTelephoneLineHandle also retains pointers to any call handles or feature controls that it has created. Attempting to access one of these objects after the demise of its parent line handle results in an exception being thrown.

Member Function: TTelephoneLineHandle::TTelephoneLineHandle

TTelephoneLineHandle (const TTelephoneLineConfigurationData & lineConfiguration)
TTelephoneLineHandle (const TTelephoneLineHandle &)
TTelephoneLineHandle ()

Interface Category:

API.

Purpose:

Creates a TTelephoneLineHandle using the specified configuration information.
Copy constructor.
Default constructor.

Calling Context:

Call directly at construction.
Call directly to copy an object.
Call directly for streaming and assignment only.

Parameters:

const TTelephoneLineConfigurationData & lineConfiguration -Specifies phone number(s) and active features.
const TTelephoneLineHandle & -The TTelephoneLineHandle to be copied.
Takes no 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 TTelephoneLine derived class to be constructed by the telephone server.

Member Function: TTelephoneLineHandle::~TTelephoneLineHandle

virtual ~ TTelephoneLineHandle ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no 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 TTelephoneLine derived class. TTelephoneLineHandle also retains pointers to any call handles or feature controls which it has created. Attempting to access one of these objects after the demise of its parent line handle results in an exception being thrown.

Member Function: TTelephoneLineHandle::operator=

TTelephoneLineHandle & operator =(const TTelephoneLineHandle &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

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

Other Considerations:

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

Member Function: TTelephoneLineHandle::GetLocalEndpoint

void GetLocalEndpoint (TCollectionOf<TText> & phoneEndpoint) const

Interface Category:

API.

Purpose:

Creates a set of TText derived classes to specify the directory number(s) associated with the line.

Calling Context:

Call directly to extract the phone endpoint.

Parameters:

TCollectionOf<TText> & phoneEndpoint -The collection that is to receive the directory number(s). (Note: This interface will eventually use a phone endpoint class to be provided by the Modem framework.)

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

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

Other Considerations:

TTelephoneLineHandle retains the storage responsibility for the TText derived classes contained in the collection parameter.

Member Function: TTelephoneLineHandle::IsOnHook

virtual bool IsOnHook () const

Interface Category:

API.

Purpose:

Determines whether a line is on hook.

Calling Context:

Call directly to determine the current hook status.

Parameters:

Takes no parameters.

Return Value:

Returns true if the line 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: TTelephoneLineHandle::CreateAndPlaceCall

virtual TTelephoneCallHandle * CreateAndPlaceCall (const TText & phoneNumber)

Interface Category:

API.

Purpose:

Places an outbound call and creates a call handle representing the new connection.

Calling Context:

Call directly to place a new call.

Parameters:

const TText & phoneNumber -The phone number to be dialed.

Return Value:

Returns a pointer to a new call handle representing the call and its current status.

Exceptions:

Throws no exceptions, passes all exceptions through. Placing the call might not result in a completed connection. Check the status of the resulting call handle to determine the state of the connection.

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: TTelephoneLineHandle::CreateAndAnswerCall

virtual TTelephoneCallHandle * CreateAndAnswerCall ()

Interface Category:

API.

Purpose:

Answers an incoming call and creates a call handle representing the new connection.

Calling Context:

Call directly to answer an incoming call.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a new call handle representing the call and its current status.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

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

Other Considerations:

None.

Member Function: TTelephoneLineHandle::CreateFeatureControl

virtual TTelephoneLineFeatureControl * CreateFeatureControl (const TTypeDescription & featureType)

Interface Category:

API.

Purpose:

Creates a control object for an advanced telephone feature.

Calling Context:

Call directly to access an advanced telephony feature.

Parameters:

const TTypeDescription & featureType -Specifies the type of feature for which a control is required.

Return Value:

Returns a pointer to a TTelephoneLineFeatureControl derived class that matches the specified telephone line feature.

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: TTelephoneLineHandle::CreateCallList

virtual void CreateCallList (TCollectionOf<TTelephoneCallHandle> & currentCalls)

Interface Category:

API.

Purpose:

Creates a collection of call handles for any existing connections.

Calling Context:

Call directly to monitor the status of ongoing connections.

Parameters:

TCollectionOf<TTelephoneCallHandle> & currentCalls -The collection to which the call handles are to be added.

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 responsibility for the storage referenced by the pointers added to the collection parameter.

Member Function: TTelephoneLineHandle::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 line's hook status changes.

Parameters:

Takes no 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: TTelephoneLineHandle::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 line.

Parameters:

Takes no 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: TTelephoneLineHandle::CreateCallInterest

virtual TInterest * CreateCallInterest (const TTelephoneCallHandle &) const

Interface Category:

API.

Purpose:

Creates a new call 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 specified call's status changes.

Parameters:

const TTelephoneCallHandle & -Identifies the call to be monitored.

Return Value:

Returns a TInterest pointer referencing a TTelephoneCallInterest 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: TTelephoneLineHandle::CreateFeatureInterest

virtual TInterest * CreateFeatureInterest (const TTelephoneLineFeatureControl &) const

Interface Category:

API.

Purpose:

Creates a new feature interest object.

Calling Context:

Parameters:

const TTelephoneLineFeatureControl & -Identifies the feature to be monitored.

Return Value:

Returns a TInterest pointer referencing a TTelephoneFeatureInterest 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: TTelephoneLineHandle::TakeOffHook

virtual void TakeOffHook ()

Interface Category:

API.

Purpose:

Takes the line off hook.

Calling Context:

This low-level function can be called directly by clients to get more fine-grained control over the telephone line.

Parameters:

Takes no 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: TTelephoneLineHandle::PutOnHook

virtual void PutOnHook ()

Interface Category:

API.

Purpose:

Puts the line on hook.

Calling Context:

This low-level function can be called directly by clients to get more fine-grained control over the telephone line.

Parameters:

Takes no 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: TTelephoneLineHandle::DialNumber

virtual void DialNumber (const TText & phoneNumber)

Interface Category:

API.

Purpose:

Dials out a fully specified phone number.

Calling Context:

This low-level function can be called directly by clients to get more fine-grained control over the telephone line.

Parameters:

const TText & phoneNumber -Specifies the number to dial.

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: TTelephoneLineHandle::SendDigits

virtual void SendDigits (const TText & phoneCharacters)

Interface Category:

API.

Purpose:

Sends out a raw digit string.

Calling Context:

This low-level function can be called directly by clients to access voice mail or interactive voice response services.

Parameters:

const TText & phoneCharacters -Specifies the digits to send.

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: TTelephoneLineHandle::CreatePreferredTypeList

virtual void CreatePreferredTypeList (TSequenceOf<TTypeDescription> &) const

Interface Category:

API.

Purpose:

Overrides the inherited type negotiation member function to create a list of type descriptions for the features currently configured on the line.

Calling Context:

Called by the telephone server to locate and register features configured on a given line instance.

Parameters:

TSequenceOf<TTypeDescription> & -A sequence allocated by the client to receive the list of feature type descriptions.

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 feature type descriptions contained in the sequence parameter.

Member Function: TTelephoneLineHandle::ChoosePreferredType

virtual TTypeDescription * ChoosePreferredType (const TSequenceOf<TTypeDescription> &) const

Interface Category:

API.

Purpose:

Overrides the inherited type negotiation member function to verify that a specific feature type is currently configured on the line.

Calling Context:

Called directly by the client application to locate a telephone line with an appropriate configuration.

Parameters:

const TSequenceOf<TTypeDescription> & -The client's list of preferred feature types. Typically contains a single feature unless multiple versions of a given feature are supported by the client application and by the line instance.

Return Value:

A pointer to the client's copy of the matching feature type description. Returns NIL if no match was found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

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

Other Considerations:

The client retains the storage responsibility for the type descriptions contained in the sequence parameter.

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

Takes no 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: TTelephoneLineHandle::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call directly to stream in data.

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

Other Considerations:

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

Member Function: TTelephoneLineHandle::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call directly to stream out data.

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. 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.