Class: TTelephoneLine

Declaration: TelephoneLine.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MRemoteDispatcher, MDelegatingNotifier, MReferenceCounted

Inherited By:

None.

Purpose:

Provides a software model of the physical connection between the computer and the telephone network. Associated with each phone line is: (1) a hook state (on-hook or off-hook), (2) a unique telephone endpoint containing one or more directory numbers, and (3) a set of available telephone line features (for example, hold, transfer, conference, and forward). TTelephoneLine defines a standard interface for communicating with the telephone network. Derived classes must provide concrete hardware-specific implementations of the pure virtual functions TakeOffHook, PutOnHook, DialNumber, and SendDigits. Rather than instantiating TTelephoneLine derived classes directly, Application Frameworks clients request telephony services via an intermediate handle object, TTelephoneLineHandle. Eventually, TTelephoneLine will permit telephony hardware with the proper interface to be used for audio input/output by the Audio Framework.

Instantiation:

Allocate on the heap or the stack. Normally allocated on heap by the Telephony Framework.

Deriving Classes:

Derived classes of this abstract class override its pure virtual member functions in order to communicate with the specific hardware interface to a specific telephone network. Deriving classes may also override ReceiveUpdate to do special processing of telephony events. The two convenience functions CreateAndPlaceCall and CreateAndAnswerCall could also require overrides if the default behavior they define is inappropriate for a given derived class implementation.

Concurrency:

Multithread safe.

Resource Use:

Once configured and installed, lines are created and deleted automatically by the Telephony Framework. The framework retains pointers to all lines in use. The current implementation of this cass 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: TTelephoneLine::~TTelephoneLine

virtual ~ TTelephoneLine ()

Interface Category:

API.

Purpose:

Destructor. Releases the resources associated with TTelephoneLine.

Calling Context:

Called to destroy an object. Called automatically by the Telephony Framework when a line 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: TTelephoneLine::SetConfigurationData

virtual void SetConfigurationData (const TTelephoneLineConfigurationData &)

Interface Category:

API.

Purpose:

Specifies new configuration information for a previously configured line.

Calling Context:

Call directly when the a line needs to be reconfigured.

Parameters:

const TTelephoneLineConfigurationData & -Specifies phone number(s) and active features.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneLine::CreateConfigurationData

virtual TTelephoneLineConfigurationData * CreateConfigurationData () const

Interface Category:

API.

Purpose:

Permits a line to be queried regarding its current configuration.

Calling Context:

Call directly when a line 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: TTelephoneLine::Unreachable

virtual void Unreachable ()

Interface Category:

API.

Purpose:

Overrides inherited MReferenceCounted function.

Calling Context:

Same as for base class.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneLine::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

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

Other Considerations:

None.

Member Function: TTelephoneLine::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Used be Telephony Framework.

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. Throws a TTelephonyException if any of the features configured for the stored telephone line cannot be configured on the target telephone line.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneLine::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call directly to store a configured line.

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: TTelephoneLine::GetNotifier

virtual MNotifier * GetNotifier () const

Interface Category:

API.

Purpose:

Overrides inherited MDelegatingNotifier function.

Calling Context:

Same as for base class.

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 line retains responsibility for the storage referenced by the pointer returned.

Member Function: TTelephoneLine::TTelephoneLine

TTelephoneLine (const TTelephoneLineConfigurationData &)
TTelephoneLine (const TTelephoneLine &)
TTelephoneLine ()

Interface Category:

API.

Purpose:

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

Calling Context:

Called by derived class constructors during installation to specify the phone number and the active features.
Called by derived class copy constructors.
Called by derived class constructors.

Parameters:

const TTelephoneLineConfigurationData & -Specifies the phone number(s) and the active features.
const TTelephoneLine & -The TTelephoneLine to be copied.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Derived classes that provide telephone line feature implementations must provide an override for TTelephoneLine (const TTelephoneLineConfigurationData &), which allocates instances of each feature to be supported and then calls ConfigureFeatures using a preferred type list obtained from the configuration data parameter.

Member Function: TTelephoneLine::operator=

TTelephoneLine & operator =(const TTelephoneLine &)

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: TTelephoneLine::AdoptFeature

virtual void AdoptFeature (TTelephoneLineFeature *)

Interface Category:

API.

Purpose:

Adds a telephone line feature implementation to a telephone line derived class.

Calling Context:

Call from derived class during configuration.

Parameters:

TTelephoneLineFeature * -The feature implementation to be added.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

The telephone line retains responsibility for the storage referenced by the parameter.

Member Function: TTelephoneLine::ConfigureFeatures

virtual void ConfigureFeatures (const TCollectionOf <TTypeDescription > & theFeatures)

Interface Category:

API.

Purpose:

Specifies the feature type(s) for which a line instance is actually configured. A predefined set of feature implementations is associated (via AdoptFeature) with each line implementation. Depending on the user's class of service, only a subset of these might be available for a specific line instance.

Calling Context:

Call from derived class during construction to specify which feature type(s) are actually available.

Parameters:

const TCollectionOf<TTypeDescription> & theChoices -A collection of type descriptions for the features to be selected for configuration.

Return Value:

None.

Exceptions:

Throws a TTelephony exception if one or more of the features to be configured are not supported by the line instance.

Concurrency:

Multithread safe.

Other Considerations:

The caller retains responsibility for the storage of type descriptions contained in the collection parameter.

Member Function: TTelephoneLine::ReceiveUpdate

virtual void ReceiveUpdate (const TNotification &)

Interface Category:

API.

Purpose:

Distributes notification of the hook status. Updates the state information for the internal hook, call, and feature representations. 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:

Called by a derived class to propagate the hook status, call Progress, and other telephony events.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Can allocate internal objects in order to maintain call state information. Calls the Notify member function inherited from MDelegatingNotifier.

Member Function: TTelephoneLine::SetHookStatus

virtual void SetHookStatus (const TToken &)

Interface Category:

API.

Purpose:

Modifies the telephone line's current hook status.

Calling Context:

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

Parameters:

const TToken & -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: TTelephoneLine::TakeOffHook

virtual void TakeOffHook ()

Interface Category:

API.

Purpose:

Must be overridden to do whatever is required by the specific telephone network interface to make the line go off hook.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request to take the line off hook.

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: TTelephoneLine::PutOnHook

virtual void PutOnHook ()

Interface Category:

API.

Purpose:

Must be overridden to do whatever is required by the specific telephone network interface to make the line go on hook.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request to put the line on hook.

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: TTelephoneLine::DialNumber

virtual void DialNumber (const TText & phoneNumber)

Interface Category:

API.

Purpose:

Must be overridden to do whatever is required by the specific telephone network interface to dial a number.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request to dial a number.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Pure virtual member function.

Member Function: TTelephoneLine::SendDigits

virtual void SendDigits (const TText & phoneCharacters)

Interface Category:

API.

Purpose:

Must be overridden to do whatever is required by the specific telephone network interface to send digits.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request to send digits.

Parameters:

const TText & phoneCharacters -The digits to be sent.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

Pure virtual member function.

Member Function: TTelephoneLine::CreateAndPlaceCall

virtual TTelephoneCallHandle * CreateAndPlaceCall (const TText & phoneNumber)

Interface Category:

API.

Purpose:

Uses lower-level functions to go off hook and place an outbound call. Uses call that is "Ready to Dial" if one exists. Otherwise, creates a new call. Calls TakeOffHook and DialNumber. Can be overridden to provide different behavior.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request to place a call.

Parameters:

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

Return Value:

Returns a pointer to a telephone call handle representing the new connection.

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

virtual TTelephoneCallHandle * CreateAndAnswerCall ()

Interface Category:

API.

Purpose:

Uses lower-level functions to go off hook and answer an incoming call. Calls TakeOffHook and looks for an active call. Can be overridden to provide different behavior.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request to answer a call.

Parameters:

Takes no parameters.

Return Value:

Returns a pointer to a telephone call handle representing the new connection.

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

virtual void CreateCallList (TCollectionOf<TTelephoneCallHandle> &) const

Interface Category:

API.

Purpose:

Creates a collection of call handles for any existing connections.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request for a list of calls.

Parameters:

TCollectionOf<TTelephoneCallHandle> & -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.

Other Considerations:

The caller must assume responsibility for the storage referenced by the pointers added to the collection parameter.

Member Function: TTelephoneLine::UpdateHookStatus

virtual TToken UpdateHookStatus () const

Interface Category:

API.

Purpose:

Returns the current hook status of the line 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: TTelephoneLine::UpdateCallStatus

virtual TToken UpdateCallStatus (const TTelephoneCallHandle &)

Interface Category:

API.

Purpose:

Returns the current status of the specified call handle.

Calling Context:

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

Parameters:

const TTelephoneCallHandle & -Designates the call for which a status update is required.

Return Value:

Returns a TToken containing the current call status value. Returns idle status if the specified handle does not correspond to an existing connection. (Potential values are defined in the class TTelephoneStatusNotification.)

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneLine::CreateFeatureControl

virtual TTelephoneLineFeatureControl * CreateFeatureControl (const TTypeDescription &) const

Interface Category:

API.

Purpose:

Provides access to a specific telephone line feature.

Calling Context:

Called via the remote dispatcher mechanism in response to the client's request for the control object associated with a specific telephone line feature.

Parameters:

const TTypeDescription & -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 TTelephonyException if the specified feature is not available.

Concurrency:

Multithread safe.

Other Considerations:

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

Member Function: TTelephoneLine::AddCallAndCreateHandle

virtual TTelephoneCallHandle * AddCallAndCreateHandle (const TText & remotePhoneNumber)

Interface Category:

API.

Purpose:

Adds a new connection and returns its corresponding call handle.

Calling Context:

Called by derived classes to manage ongoing connections.

Parameters:

const TText & remotePhoneNumber -The phone number at the remote end of the connection.

Return Value:

Returns a pointer to a telephone call handle representing the new connection.

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: TTelephoneLine::FindCallAndCreateHandle

virtual TTelephoneCallHandle * FindCallAndCreateHandle (const TToken & callState) const

Interface Category:

API.

Purpose:

Locates an existing connection and returns its corresponding call handle.

Calling Context:

Called by derived classes to manage ongoing connections.

Parameters:

const TToken & callState -Identifies the specified connection by specifying its current call status.

Return Value:

Returns a pointer to a telephone call handle representing the existing connection. Returns NIL if no connections exist for the specified call status.

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: TTelephoneLine::DeleteCall

virtual void DeleteCall (const TTelephoneCallHandle & callHandle)

Interface Category:

API.

Purpose:

DeleteCall -Eliminates an existing connection.

Calling Context:

Called by derived classes to manage ongoing connections.

Parameters:

const TTelephoneCallHandle & callHandle -Identifies the specified connection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneLine::GetFeature

virtual TTelephoneLineFeature * GetFeature (const TTypeDescription & featureType) const

Interface Category:

API.

Purpose:

Locates a telephone line feature and returns a pointer to it.

Calling Context:

Called by derived classes to access configured features.

Parameters:

const TTypeDescription & featureType -Identifies the desired feature.

Return Value:

Returns a pointer to a feature of the specified type. Returns NIL if no feature of the specified type has been configured.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTelephoneLine::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 line'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: TTelephoneLine::CreateRingNotification

virtual TNotification * CreateRingNotification (const TText & phoneNumber) 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.

Member Function: TTelephoneLine::CreateCallNotification

virtual TNotification * CreateCallNotification (const TToken & callState, const TTelephoneCallHandle &, TTelephoneStatusNotification :: ETelephoneStatusClassification classification =TTelephoneStatusNotification :: kSuccess) const

Interface Category:

API.

Purpose:

Allocates a notification object for a call status event. The resulting pointer should be passed as a parameter to the ReceiveUpdate function in order to update the specified connection's 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 & callState -Specifies the new call state. (Potential values are defined in the class TTelephoneStatusNotification.)
const TTelephoneCallHandle & -Identifies the connection to be updated.
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: TTelephoneLine::CreateFeatureNotification

virtual TNotification * CreateFeatureNotification (const TToken & featureState, const TTelephoneLineFeature &, TTelephoneStatusNotification :: ETelephoneStatusClassification classification =TTelephoneStatusNotification :: kSuccess) const

Interface Category:

API.

Purpose:

Allocates a notification object for a feature status event. The resulting pointer should be passed as a parameter to the ReceiveUpdate function to update the specified feature's 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 & featureState -Specifies the new feature state. (Potential values are defined in the class TTelephoneStatusNotification.)
const TTelephoneLineFeature & -Identifies the feature to be updated.
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: TTelephoneLine::CreateDigitsNotification

virtual TNotification * CreateDigitsNotification (const TText & phoneCharacters) const

Interface Category:

API.

Purpose:

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

Calling Context:

Called by derived classes in response to telephony hardware activity.

Parameters:

const TText & phoneCharacters -Specifies the incoming digit string.

Return Value:

Returns a TNotification pointer referencing a TTelephoneDigitsNotification 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.