Call States

Most functions on calls only make sense while the call is in one of certain call states. This call state is checked, and the function returns an error if the call is not in one these states. The effect of the successful execution of a request may be some typical call state transitions. Applications are notified about call state changes via call state messages. These messages report to the application what call state the application has just entered. Since unsolicited events may occur to calls (e.g., the other party disconnects), the application should let itself be driven by these call state messages rather than to assume the requests will always result in certain fixed call state transitions. This model also provides maximum flexibility across different telephony environments, and therefore maximum portability. If a request results in a error, there is no call state change as a result of the error.

lineAccept

Syntax

LONG lineAccept(hCall, lpsUserUserInfo, dwSize)
This function accepts the specified offered call. It may optionally send the specified user-to-user information to the calling party.

Parameters

HCALL hCall Specifies a handle to the call to be accepted. The app must be an owner of the call.

LPCSTR const lpsUserUserInfo
Specifies a far pointer to a string containing user-to-user information to be sent to the remote party as part of the call accept. This pointer can be left NULL if no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

DWORD dwSize
Specifies the size in bytes of the user-to-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-to-user information is sent to the calling party and dwSize is ignored.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALCALLSTATE
The specified call is not in a valid state for the requested operation.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall offering

Comments

lineAccept is used in telephony environments (like ISDN) that allow alerting associated with incoming calls to be separate from the initial offering of the call. When a call comes in, the call is first offered. For some small time duration, the application may have the option to reject the call using lineDrop, redirect the call to another station using lineRedirect, answer the call using lineAnswer, or accept the call using lineAccept. After a call has been successfully accepted, alerting at both the called and calling device will begin. After a call has been accepted by an application, the call state will typically transition to the accepted state.

To the application, alerting is reported via the LINE_LINEDEVSTATE message with the ringing indication.

lineAccept may also be supported by non-ISDN service providers. The call state transition to the accepted state can be used by other applications as an indication that another application has claimed responsibility for the call and has presented the call to the user.

The app has the option to send user-to-user information at the time of the accept. Even if user-to-user information can be sent, often no guarantees are made that the network will deliver this information to the calling party. An app should consult a line's device capabilities to determine whether or not call accept is available.

See Also

Functions: lineDrop, lineRedirect, lineAnswer
Messages: LINE_CALLSTATE, LINE_LINEDEVSTATE


lineAddToConference

Syntax

LONG lineAddToConference(hConfCall, hAddCall)
This function adds the call specified by hAddCall, to the conference call specified by hConfCall.

Parameters

HCALL hConfCall
Specifies a handle to the conference call. The app must be an owner of this call.

HCALL hAddCall
Specifies a handle to the call to be added to the conference call. The app must be an owner of this call.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCONFCALLHANDLE
The specified call handle for the conference call is invalid or is not a handle for a conference call.
LINEERR_INVALCALLHANDLE
The specified call handle for the added call is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call(s).
LINEERR_INVALCALLSTATE
One or both of the specified calls are not in a valid state for the requested operation.
LINEERR_CONFERENCEFULL
The maximum number of parties for a conference has been reached.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hConfCall onHoldPendingConference, onHold
hAddCall connected, onHold

Comments

Note that the call handle of the added party remains valid after adding the call to a conference; its state will typically change to conferenced while the state of the conference call will typically become connected. Using lineGetCalls, it is possible to obtain a handle for a conference call by providing the handle to any participating call, or to obtain handles to the participating calls given the conference call handle. The handle to an individual participating call can be used later to remove that party from the conference call using lineRemoveFromConference.

The call states of the calls participating in a conference are not independent. For example, when dropping a conference call, all participating calls may automatically become idle. An application should consult the line's device capabilities to determine what form of conference removal is available. The app should track the LINE_CALLSTATE messages to determine what really happened to the calls involved.

The conference call is established either via lineSetupConference or lineCompleteTransfer. The call added to a conference will typically be established using lineSetupConference or linePrepareAddToConference. Some switches may allow adding of an arbitrary calls to conference, and such a call may have been set up using lineMakeCall and be on (hard) hold.

See Also

Functions: lineSetupConference, linePrepareAddToConference, lineRemoveFromConference, lineCompleteTransfer

Messages: LINE_CALLSTATE


lineAnswer

Syntax

LONG lineAnswer(hCall, lpsUserUserInfo, dwSize)
This function answers the specified offering call.

Parameters

HCALL hCall
Specifies a handle to the call to be answered. The app must be an owner of this call.

LPCSTR const lpsUserUserInfo
Specifies a far pointer to a string containing user-to-user information to be sent to the remote party at the time of answering the call. This pointer can be left NULL if no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

DWORD dwSize
Specifies the size in bytes of the user-to-user information in lpsUserUserInfo. If lpsUserUserInfo is NULL, no user-to-user information is sent to the calling party and dwSize is ignored.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALCALLSTATE
The call is not in a valid state for the requested operation.
LINEERR_INUSE
The line is in use in a way that does not allow this call to be answered.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall
offering, accepted

Comments

When a new call arrives, apps with an interest in the call are sent a LINE_CALLSTATE message to provide the new call handle and to inform the app about the call's state and privileges to the new call (e.g., monitor, owner). The app with owner privileges for the call can answer this call using lineAnswer. After the call has been successfully answered, the call will typically transition to the connected state. Initially, only one application will be the given owner privileges to the inbound call.

In some telephony environments (like ISDN) where user alerting is separate from call offering, the app may have the option to first accept a call prior to answering, or instead to reject or redirect the offering call.

If a call comes in (is offered) at the time another call is already active, then the new call is connected to by invoking lineAnswer. The effect this has on the existing active call depends on the line's device capabilities. The first call may be unaffected, it may automatically be dropped, or it may automatically be placed on hold. The appropriate LINE_CALLSTATE messages will report state transitions to the application about both calls.

The app has the option to send user-to-user information at the time of the answer. Even if user-to-user information can be sent, often no guarantees are made that the network will deliver this information to the calling party. An app should consult a line's device capabilities to determine whether or not sending user-to-user information on answer is available.

See Also

Messages: LINE_CALLSTATE


lineBlindTransfer

Syntax

LONG lineBlindTransfer(hCall, lpszDestAddress, dwCountryCode)
This function performs a blind or single-step transfer of the specified call to the specified destination address.

Parameters

HCALL hCall
Specifies a handle to the call to be transferred. The app must be an owner of this call.

LPCSTR const lpszDestAddress
Specifies a far pointer to a NULL-terminated string identifying where the call is to be transferred to. The destination address uses the standard dialable number format.

DWORD dwCountryCode
Specifies the country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of zero is specified, then a service provider defined default call progress protocol is used.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALCALLSTATE
The specified call is not in a valid state for the requested operation.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall connected

Comments

Blind transfer differs from a consultation transfer in that no consultation call is made visible to the app. After the blind transfer successfully completes the specified call will typically be cleared from the application's line and transition to the idle state. Note that the app's call handle will remain valid after the transfer has completed. The app must deallocate its handle when it is no longer interested in the transferred call using lineHandoff.

See Also

Functions: lineHandoff
Messages: LINE_CALLSTATE


lineClose

Syntax

LONG lineClose(hLine)
This function closes the specified open line device.

Parameters

HLINE hLine
Specifies a handle to the open line device to be closed. After the line has been successfully closed, this handle is no longer valid.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

Not applicable

Comments

If an application calls lineClose while it still has active calls on the opened line, then the app's ownership of these calls is revoked. If the app was the sole owner of these calls, then the calls are dropped as well. It is good programming practice for an application to dispose of the calls it owns on an opened line by explicity relinquishing ownership and/or by dropping these calls prior to closing the line.

If the close was successful, a LINE_LINEDEVSTATE message is sent all applications that are monitoring the line status of open/close changes.

Certain environments may find it useful or necessary to forcibly reclaim line devices from an application that has the line open. This may be useful to prevent a misbehaved application form monopolizing the line device for too long. If this happens, a LINE_CLOSE message is sent to the application, specifying the line handle of the line device that was closed.

lineOpen allocates resources to the invoking application, and applications may be prevented from opening a line if resources are unavailable. Therefore, an application that only occasionally uses a line device (e.g., for outbound calls) should close the line to free resources and allow other applications to open the line.

See Also

Messages: LINE_CLOSE, LINE_LINEDEVSTATE


lineCompleteCall

Syntax

LONG lineCompleteCall(hCall, lpdwCompletionID, dwCompletionMode, dwMessageID)
This function is used to specify how a call that could not be connected normally should be completed instead. The network or switch may not be able to complete a call because network resources are busy or the remote station is busy or doesn't answer. The application can request that the call be completed in one of a number of ways.

Parameters

HCALL hCall
Specifies a handle to the call whose completion is requested. The app must be an owner of the call.

LPDWORD lpdwCompletionID
Specifies a far pointer to a DWORD-sized memory location. The completion ID is used to identify individual completion requests in progress. A completion ID becomes invalid and may be reused after the request completes or after an outstanding request is canceled.

DWORD dwCompletionMode
Specifies the way in which the call is to be completed, of type LINECALLCOMPLMODE. Values are:

LINECALLCOMPLMODE_CALLBACK
Requests the called station to return the call when it returns to idle.
LINECALLCOMPLMODE_INTRUDE
Adds the app to the existing physical call at the called station (barge in).
LINECALLCOMPLMODE_MESSAGE
Leave a short predefined message for the called station (Leave Word Calling). The message to be sent is specified via dwMessageID.

DWORD dwMessageID
Specifies the message that is to be sent when completing the call using LINECALLCOMPLMODE_MESSAGE. This ID selects the message from a small number of predefined messages.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALCALLSTATE
The call is not in a valid state for the requested operation.
LINEERR_INVALCALLCOMPLMODE
The specified completion is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_COMPLETIONOVERRUN
The maximum number of outstanding call completions has been exceeded.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall busy, noAnswer

Comments

This function is considered complete when the request has been accepted by the network or switch; not when the request is fully completed in the way specified. After this function completes, the call will typically transition to idle. When the called station or network enters a state where the call can be completed as requested, the application will be notified via a LINE_CALLSTATE message with the call state equal to offering. The call's LINECALLINFO record will list the reason for the call as CALLCOMPLETION and provide the completion ID as well. It is possible to have multiple call completion requests outstanding at any given time; the maximum number is device dependent. The completion ID is also used to refer to each individual request so requests can be canceled by calling lineUncompleteCall.

See Also

Functions: lineGetCallInfo, lineUncompleteCall
Messages: LINE_CALLSTATE
Data Types: LINECALLSTATUS, LINECALLINFO, LINECALLCOMPLMODE


lineCompleteTransfer

Syntax

LONG lineCompleteTransfer(hCall, hConsultCall, lphConfCall, dwTransferMode)
This function completes the transfer of the specified call to the party connected in the consultation call.

Parameters

HCALL hCall
Specifies a handle to the call to be transferred. The app must be an owner of this call.

HCALL hConsultCall
Specifies a handle to the call that represents a connection with the destination of the transfer. The app must be an owner of this call.

LPHCALL lphConfCall
Specifies a far pointer to a memory location where a HCALL handle can be returned. If dwTransferMode is specified as LINETRANSFERMODE_CONFERENCE then the newly created conference call is returned in lphConfCall and the app will be the initial sole owner of the conference call. Otherwise, this parameter may be left NULL.

DWORD dwTransferMode
Specifies how the initiated transfer request is to be resolved, of type LINETRANSFERMODE. Values are:

LINETRANSFERMODE_TRANSFER
Resolve the initiated transfer by transferring the initial call to the consultation call.

LINETRANSFERMODE_CONFERENCE
Resolve the initiated transfer by conferencing all three parties into a three-way conference call. A conference call is created and returned to the application.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALCONSULTCALLHANDLE
The specified consultation call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call(s).
LINEERR_INVALCALLSTATE
One or both calls are not in a valid state for the requested operation.
LINEERR_INVALTRANSFERMODE
The specified transfer mode parameter is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall onHoldPendingTransfer
hConsultCall connected, ringback, busy

Comments

This operation completes the transfer of the original call, hCall, to the party currently connected via hConsultCall. The consultation call will typically have been dialed on the consultation call allocated as part of lineSetupTransfer, but it may be any call to which the switch is capable of transferring hCall.

The transfer request can be resolved either as a transfer or as a three-way conference call. When resolved as a transfer, the parties connected via hCall and hConsultCall will be connected to each other, and both hCall and hConsultCall will typically be cleared from the application's line and both will transition to the idle state. Note that the app's call handle will remain valid after the transfer has completed. The app must deallocate its handle when it is no longer interested in the transferred call using lineHandoff.

When resolved as a conference, all three parties will enter in a conference call. Both existing call handles remain valid, but will transition to the conferenced state. A conference call handle will created and returned, and it will transition to the connected state.

It may also be possible to perform a blind transfer of a call using lineBlindTransfer.

See Also

Functions: lineSetupTransfer, lineBlindTransfer
Messages: LINE_CALLSTATE


lineDevSpecific

Syntax

UINT lineDevSpecific(hLine, dwAddressID, hCall, lpParams, dwSize)
This function is used as a general extension mechanism to enable service providers to provide access to features not described in other operations. The meaning of the extensions are device-specific, and taking advantage of these extensions requires the application to be fully aware of them.

Parameters

HLINE hLine
Specifies a handle to a line device.
DWORD dwAddressID
Specifies an address ID on the given line device.
HCALL hCall
Specifies a handle to a call.
LPVOID lpParams
Specifies a far pointer to a memory area used to hold a parameter block. The format of this parameter block is device specific and its contents is passed through by the Telephony DLL to or from the service provider.
DWORD dwSize
The size in bytes of the parameter block area.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred.

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.
LINEERR_INVALADDRESSID
The specified address ID is invalid.
LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.
Additional error returns are device specific.

Call States

hCall
Device specific

Comments

This operation provides a generic parameter profile. The interpretation of the parameter structure is device specific. Whether hLine, dwAddressID or hCall are expected to be valid is device-specific. Indications and replies sent back the application that are device specific should use the LINE_DEVSPECIFIC message.

A service provider can provide access to device specific functions by defining parameters for use with this operation. Applications that want to make use of these device specific extensions should consult the device specific (i.e., vendor specific) documentation that describes what extensions are defined. Note that an app that relies on these device specific extensions will typically not be portable to work with other service provider environments.

This operation is part of the extended telephony services. It only provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

See Also

Messages: LINE_DEVSPECIFIC


lineDevSpecificFeature

Syntax

LONG lineDevSpecificFeature(hLine, dwFeature, lpParams, dwSize)
This function is used as an extension mechanism to enable service providers to provide access to features not described in other operations. The meaning of these extensions are device-specific, and taking advantage of these extensions requires the application to be fully aware of them.

Parameters

HLINE hLine
Specifies a handle to the line device.
DWORD dwFeature
Specifies the feature to invoke on the line device, of type PHONEBUTTONFUNCTION.
LPVOID lpParams
Specifies a far pointer to a memory area used to hold a feature-dependent parameter block. The format of this parameter block is device specific and its contents is passed through by the Telephony DLL to or from the service provider.
DWORD dwSize
Specifies the size of the buffer in bytes.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.
Additional error returns are device specific.

Call States

hCall Device specific

Comments

This function provides the application with phone feature button emulation capabilities. When an application invokes this operation, it specifies the equivalent of a button press event. This method of invoking features is highly device dependent, as the API does not define the their meaning. Note that an app that relies on these device specific extensions will typically not be portable to work with other service provider environments.

Note also that the lpParams data structure should not contain any pointers since they would not be properly translated (thunked) when running a 16 bit application in a 32 bit version of the Telephony DLL and vice versa.

This operation is part of the extended telephony services. It only provides access to a device-specific feature without defining its meaning. This operation is only available if the application has successfully negotiated a device-specific extension version.

See Also

Messages: LINE_DEVSPECIFICFEATURE

Data Types: PHONEBUTTONFUNCTION


lineDial

Syntax

LONG lineDial(hCall, lpszDestAddress, dwCountryCode)
This function dials the specified dialable number on the specified call.

Parameters

HCALL hCal
Specifies a handle to the call on which a number is to be dialed. The app must be an owner of the call.

LPCSTR const lpszDestAddress
Specifies the destination to be dialed using the standard dialable number format.

DWORD dwCountryCode
Specifies the country code of the destination. This is used by the implementation to select the call progress protocols for the destination address. If a value of zero is specified, then a service provider defined default call progress protocol is used.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_INVALADDRESS
The specified character buffer for the destination address to be dialed contains invalid characters or digits (i.e., syntax error); no dialing has been done.
LINEERR_INVALPARAM
The specified country code is invalid.
LINEERR_INVALCALLSTATE
The current state of the call does not allow dialing.
LINEERR_ADDRESSBLOCKED
The specified address is blocked from being dialed on the specified call.
LINEERR_BILLINGREJECTED
The billing information specified as part of the destination address has been rejected.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall Any state except idle and disconnected

Comments

lineDial is used for dialing on an existing call appearance. For example, after a call has been set up for transfer or conference, a consultation call is automatically allocated. lineDial would be used to perform the dialing of this consultation call. Note that lineDial may be invoked multiple times in the course of dialing in the case of multi-stage dialing, if the line's device capabilities allows it. Also, multiple addresses may be provided in a single dial string separated by CRLF. Service providers that provide inverse multiplexing can establish individual physical calls with each of the addresses, and return a single call handle to the aggregate of all calls to the application. All addresses would use the same country code.

Dialing is considered completed after the address has been passed on to the service provider; not after the call is finally connected. Service providers that provide inverse multiplexing may allow require multiple addresses to be provided at onece. The service provider sends LINE_CALLSTATE messages to the application to inform it about the progress of the call. To abort a call attempt while a call is being established, the invoking application should use lineDrop.

See Also

Messages: LINE_CALLSTATE


lineDrop

Syntax

LONG lineDrop(hCall, lpsUserUserInfo, dwSize)
This functions drops or disconnects the specified call. The application has the option to specify user-to-user information to be transmitted as part of the call disconnect.

Parameters

HCALL hCall
Specifies a handle to the call to be dropped. The app must be an owner of the call.

LPCSTR const lpsUserUserInfo
Specifies a far pointer to a string containing user-to-user information to be sent to the remote party as part of the call disconnect. This pointer can be left NULL if dwUserUserInfoSize is zero and no user-to-user information is to be sent. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

DWORD dwSize
Specifies the size in bytes of the user-to-user information in lpsUserUserInfo. If zero, then lpsUserUserInfo can be left NULL, and no user-to-user information will be sent to the remote party.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_INVALCALLSTATE
The current state of the call does not allow the call to be dropped.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall
The specified operation failed for unspecified reasons.

Comments

When invoking lineDrop related calls may sometimes be affected as well. For example, dropping a conference call may drop all individual participating calls. LINE_CALLSTATE messages are sent to the application for all calls whose call state is affected. A dropped call will typically transition to the idle state.

Invoking lineDrop on a call in the offering state rejects the call. Not all telephone networks provide this capability.

Invoking lineDrop on a consultation call that was set up using either lineSetupTransfer or lineSetupConference, will cancel the consultation call. Some switches automatically unhold the other call.

The app has the option to send user-to-user information at the time of the drop. Even if user-to-user information can be sent, often no guarantees are made that the network will deliver this information to the remote party.

Note that in various bridged or party line configurations when multiple parties are on the call, lineDrop by the application may not actually clear the call.

See Also

Functions: lineGetDevCaps


lineForward

Syntax

LONG lineForward(hLine, bAllAddresses, dwAddressID, lpForwardList, dwNumRingsNoAnswer, lphConsultCall)
This function forwards calls destined for the specified address on the specified line, according to the specified forwarding instructions. When an originating address (dwAddressID) is forwarded, the specified incoming calls for that address are deflected to the other number by the switch. This function provides a combination of forward and do-not-disturb features. This function can also cancel specific forwarding currently in effect.

Parameters

HLINE hLine
Specifies a handle to the line device.
BOOL bAllAddresses
Specifies whether all originating addresses on the line or just the one specified is to be forwarded. If TRUE, all addresses on the line are forwarded and dwAddressID is ignored; if FALSE, only the address specified as dwAddressID is forwarded.
DWORD dwAddressID
Specifies the address on the specified line whose incoming calls are to be forwarded. This parameter is ignored if bAllAddresses is TRUE.
LPLINEFORWARDLIST const lpForwardList
Specifies a far pointer to a variable size data structure that describes the specific forwarding instructions, of type LINEFORWARDLIST.
DWORD dwNumRingsNoAnswer
Specifies the number of rings before a call is considered a "no answer".
LPHCALL lphConsultCall
Specifies a far pointer to a HCALL location. In some telephony environments, this location is loaded with a handle to a consultation call used to consult the party that is being forwarded to, and the app will be the initial sole owner of this call. This pointer must be valid even in environments where call forwarding does not require a consultation call.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line device handle is invalid.
LINEERR_INVALADDRESSID
The specified address ID is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_INVALPARAM
The specified forward list parameter contains invalid information.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

Not applicable.

Comments

Forwarding of the address(es) remains in effect until this function is called again. The most recent forwarding list replaces the old one. Forwarding can be canceled by specifying a NULL pointer as lpForwardList. If a NULL destination address is specified for an entry in the forwarding list, then the operation acts as a do not disturb.

Be aware that forwarding status of an address may also be affected externally. For example via administrative actions at the switch, or by a user from another station. It may not be possible for the service provider to be aware of this state change, and may not be able to keep in sync with the forwarding state known to the switch.

See Also

Functions: lineGetAddressStatus

Messages: LINE_ADDRESSSTATUS

Data Types: LINEFORWARDLIST


lineGatherDigits

Syntax

LONG lineGatherDigits(hCall, dwDigitModes, lpsDigits, dwNumDigits, lpszTerminationDigits, dwFirstDigitTimeout, dwInterDigitTimeout)
This function initiates the buffered gathering of digits on the specified call. The app specifies a buffer in which to place the digits and the maximum number of digits to be collected.

Digit collection is terminated in a variety of ways. Firstly, the requested number of digits has been collected. Secondly, one of the digits detected matches a digit in szTerminationDigits before the specified number of digits has been collected. The detected termination digit is also placed in the buffer and the partial buffer is returned. Thirdly, one of the timeouts expires. The dwFirstDigitTimeout expires if the first digit is not received in this time period. The dwInterDigitTimout expires if the second, third, etc. digit is not received within that time amount from the previously detected digit, and a partial buffer is returned. A fourth method for terminating (i.e., canceling) digit detection is by calling this operation again while collection is in progress. The old collection session is terminated and the content of the old buffer is undefined. The mechanism for canceling digit gathering without initiating another is by invoking this operation with lpsDigits equal to NULL.

Parameters

HCALL hCall
Specifies a handle to the call on which digits are to be gathered. The app must be an owner of the call.

DWORD dwDigitModes
Specifies the digit mode(s) that are to be monitored, of type LINEDIGITMODE.

LINEDIGITMODE_PULSE
Detect digits as audible click that are the result of the use of rotary pulse sequences. Valid digits for pulse mode are '0' through '9'.
LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

LPSTR lpsDigits
Specifies a far pointer to the buffer where detected digits are to be stored as ASCII characters. Note that digits may not show up in the buffer one at a time as they are collected. Only after a LINE_GATHERDIGITS message is received should the content of the buffer be assumed to be valid. If lpsDigits is specified as NULL the digit gathering currently in progress on the call is canceled and the dwNumDigits parameter is ignored. Otherwise, lpsDigits is assumed to have room for dwNumDigits digits.

DWORD dwNumDigits
Specifies the number of digits to be collected before a LINE_GATHERDIGITS message is sent to the application. dwNumDigits is ignored when lpsDigits is NULL. This function will fail if dwNumDigits is zero.

LPCSTR const lpszTerminationDigits
Specifies a NULL-terminated string of termination digits as ASCII characters. If one of the digits in the string is detected, then that termination digit is appended to the buffer, digit collection is terminated and the LINE_GATHERDIGITS message is sent to the application.

Valid characters for pulse mode are '0' through '9'. Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

DWORD dwFirstDigitTimeout Specifies the time duration in milliseconds in which the first digit is expected. If the first digit is not received in this timeframe, then digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the NULL character, indicating no digits were received and the first digit timeout terminated digit gathering. The call's line device capabilities specifies the valid range for this parameter or indicates that timeouts are not supported.

DWORD dwInterDigitTimeout
Specifies the maximum time duration in milliseconds between consecutive digits. If no digit is received in this timeframe, then digit collection is aborted and a LINE_GATHERDIGITS message is sent to the application. The buffer only contains the digits collected up to this point followed by a NULL character, indicating that an interdigit timeout terminated digit gathering. The call's line device capabilities specifies the valid range for this parameter or indicates that timeouts are not supported.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALDIGITMODE
The specified digit mode is not available.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_INVALDIGITS
The specified termination digits are not valid.
LINEERR_INVALPARAM
The dwNumDigits parameter is invalid.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall
Any state

Comments

This function is considered successful if digit collection has been correctly initiated; not when digit collection has terminated. In all cases where a partial buffer is returned, valid digits (if any) are followed by an ASCII NULL character.

Although this function can be invoked in any call state, digits can typically only be gathered while the call is in the connected state.

The message LINE_GATHERDIGITS is sent only to the application that initiated the request. It is also sent when partial buffers are returned because of timeouts or matching termination digits, or when the request is canceled via another lineGatherDigits request on the call. Only one gather digits request can be active on call at any given time across all apps that are owners for the call. Given the asynchronous behavior of the operation, an app that issues multiple lineGatherDigits in quick succession may be able to do so and receive several LINE_GATHERDIGITS messages only later. While this would be unusual application behavior, the app will be able to count the number of these messages to allow cancel messages to be matched up with the earlier requests. In any case, at most the most recent request should be assumed to be valid.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. Each time a digit is detected in this fashion, a LINE_MONITORDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be enabled for the same call simultaneously.

See Also

Functions: lineGetDevCaps, lineMonitorDigits

Messages: LINE_GATHERDIGITS

Data Types: LINEDEVCAPS, LINEDIGITMODE


lineGenerateDigits

Syntax

LONG lineGenerateDigits(hCall, dwDigitMode, lpszDigits, dwDuration)
This function initiates the generation of the specified digits on the specified call as in band tones using the specified signaling mode. Invoking this function with a NULL value for lpszDigits aborts any digit generation currently in progress. Invoking lineGenerateDigits or lineGenerateTone while digit generation is in progress aborts the current digit generation or tone generation in progress and initiates the generation of the most recently specified digits or tone.

Parameters

HCALL hCall
Specifies a handle to the call. The app must be an owner of the call.

DWORD dwDigitMode
Indicates the format to be used for signaling these digits, of type LINEDIGITMODE. Values are:

LINEDIGITMODE_PULSE
Uses pulse/rotary for digit signaling. Valid digits for pulse mode are '0' through '9'.
LINEDIGITMODE_DTMF
Uses DTMF tones for digit signaling. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.
LPCSTR const lpszDigits
Specifies a far pointer to a NULL terminated character buffer that contains the digits to be generated.

Valid characters for pulse mode are '0' through '9' and ',' (comma). Valid characters for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#', and ',' (comma). A comma injects an extra delay between the signaling of the previous and next digits it separates. The duration of this pause is configuration defined. The line's device capabilities indicates what this duration is. Multiple commas may be used to inject longer pauses. Invalid digits are ignored during the generation.

DWORD dwDuration
Specifies both the duration in milliseconds of DTMF digits and pulse and DTMF inter-digit spacing. A value of zero will use a default value.

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.

Return Value

LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALDIGITMODE
The specified digit mode is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

hCall Any state

The lineGenerateDigits function is considered to have completed successfully when the digit generation has been successfully initiated; not when all digits have been generated. Contrary to lineDial, which dials digits in a network dependent fashion, lineGenerateDigits guarantees to produce the digits as inband tones over the voice channel using DTMF or hookswitch dial pulses when using pulse. lineGenerateDigits is generally not suitable for making calls or dialing, it is intendent for end-to-end signaling over an established call.

Call States

After all digits in lpszDigits have been generated, or after digit generation has been aborted or canceled, a LINE_GENERATE message is sent to the application.

Comments

Note that only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all apps that are owners of the call.

Be aware that, depending on the service provider and hardware, the app may monitor the digits it generates itself. If that is not desired, then the app can disable digit monitoring while generating digits.

Functions: lineGenerateTone

Messages: LINE_GENERATE

See Also

Data Types: LINEDIGITMODE


lineGenerateTone

Syntax

LONG lineGenerateTone(hCall, dwToneMode, dwDuration, dwNumTones, lpTones)
This function generates the specified tone inband over the specified call. Invoking this function with a zero for dwToneMode aborts the tone generation generation currently in progress on the specified call. Invoking lineGenerateTone or lineGenerateDigits while tone generation is in progress aborts the current tone generation or digit generation in progress and initiates the generation of the newly specified tone or digits.

Parameters

HCALL hCall
Specifies a handle to the call on which a tone is to be generated. The app must be an owner of the call.

DWORD dwToneMode
Defines the tone to be generated, of type LINETONEMODE. Tones can be either standard or custom. A custom tone is composed of set of arbitrary frequencies. A small number of standard tones are predefined. The duration of the tone is specified via dwDuration for both standard and custom tones. Values are:

LINETONEMODE_CUSTOM
The tone is a custom tone, defined by the specified frequencies.
LINETONEMODE_RINGBACK
The tone to be generated is ring tone. The exact ringback tone is service provider defined.
LINETONEMODE_BUSY
The tone is a standard (station) busy tone. The exact busy tone is service provider defined.
LINETONEMODE_BEEP
The tone is a beep, as used to announce the beginning of a recording. The exact beep tone is service provider defined.
LINETONEMODE_BILLING
The tone is billing information tone such as a credit card prompt tone. The exact billing tone is service provider defined.

A value of zero for dwToneMode cancels tone generation.

DWORD dwDuration
Specifies duration in milliseconds during which the tone should be sustained.

DWORD dwNumTones
Specifies the number of entries in the lpTones array. This field is ignored if dwToneMode is not equal to CUSTOM.

LPLINEGENERATETONE const lpTones
Specifies a far pointer to a LINEGENERATETONE array that specifies the tone's components. This parameter may be left NULL for non custom tones.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_INVALTONEMODE
The specified tone mode parameter is invalid.
LINEERR_INVALTONE
The specified custom tone does not represent a valid tone, or is made up of too many frequencies.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

hCall Any state

Comments

lineGenerateTone is considered to have completed successfully when the tone generation has been successfully initiated; not when the generation of the tone is done. The function allows the inband generation of several predefined tones, such as ring back, busy tones, and beep. It also allows for the fabrication of custom tones by specifying their component frequencies, cadence and volume. Since these tones are generated as inband tones, the call would typically have to be in the connected state for tone generation to be effective. When the generation of the tone is complete, or when tone generation is canceled, a LINE_GENERATE message is sent to the application.

Note that only one inband generation request (tone generation or digit generation) is allowed to be in progress per call across all apps that are owners of the call. This implies that if tone generation is currently in progress on a call, invoking lineGenerateDigits will cancel the tone generation.

See Also

Functions: lineGenerateDigits
Messages: LINE_GENERATE
Data Types: LINEGENERATETONE


lineGetAddressCaps

Syntax

LONG lineGetAddressCaps(hApp, dwDeviceID, dwAddressID, dwAPIVersion, dwExtVersion, lpAddressCaps)

This function queries the specified address on the specified line device to determine its telephony capabilities.

Parameters

HLINEAPP hApp
Specifies the handle to the app's registration with the API.
DWORD dwDeviceID
Specifies the line device containing the address to be queried.
DWORD dwAddressID
Specifies the address on the given line device whose capabilities are to be queried.
DWORD dwAPIVersion
Specifies the version number of the Telephony API to be used. The high order word contains the major version number; the low order word contain the minor version number.
DWORD dwExtVersion
Specifies the version number of the service provider-specific extensions to be used. This number can be left zero if no device specific extensions are to be used. Otherwise, the high order word contains the major version number; the low order word contain the minor version number.
LPLINEADDRESSCAPS lpAddressCaps
Specifies a far pointer to a variable sized structure of type LINEADDRESSCAPS. Upon successful completion of the request, this structure is filled with address capabilities information.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALAPPHANDLE
The specified app registration handle is invalid.
LINEERR_BADDEVICEID
The specified line device ID is out of range.
LINEERR_INVALADDRESSID
The specified address ID is out of range.
LINEERR_INCOMPATIBLEVERSION
The app requested an incompatible API version number.
LINEERR_INVALEXTVERSION
The app requested an invalid extension version number.
LINEERR_NODRIVER
The driver was not installed.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable

Comments

Valid address IDs range from zero to one less than the number of addresses returned by lineGetDevCaps.
The version number to be supplied is the version number that was returned as part of the line's device capabilities via lineGetDevCaps.

See Also

Data Types: LINEADDRESSCAPS


lineGetAddressID

Syntax

LONG lineGetAddressID(hLine, lpdwAddressID, dwAddressMode, lpsAddress, dwSize)
This operation returns the address ID associated with address in a different format on the specified line.

Parameters

HLINE hLine
Specifies a handle to the open line device.

LPDWORD lpdwAddressID
Specifies a far pointer to a DWORD-sized memory location where the address ID is returned.

DWORD dwAddressMode
Specifies the address mode of the address contained in lpAddress, of type LINEADDRESSMODE. Values are:
LINEADDRESSMODE_ADDRESSID
The address is specified via a small integer in the range 0 to dwNumAddresses - 1, where dwNumAddresses is the value in the line's device capabilities.
LINEADDRESSMODE_DIALABLEADDR
The address is specified via its dialable address. lpAddress is the dialable address or canonical address format.
LPCSTR const lpsAddress
Specifies a far pointer to a data structure holding the address assigned to the specified line device. The format of the address is determined by dwAddressMode parameter. If a DIALABLEADDR, the lpsAddress uses the common dialable number format and is NULL-terminated.
DWORD dwSize
Specifies the size of the address contained in lpAddress.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified device handle is invalid.
LINEERR_INVALADDRESSMODE
The specified address mode is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_INVALADDRESS
The specified address is not assigned to the specified line or is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

This function is used to map a phone number (address) assigned to a line device back to its dwAddressID in the range 0 to the number of addresses - 1 returned in the line's device capabilities. lineMakeCall allows the app to make a call by specifying a line handle and an address on the line. The address can be specified either as a dwAddressID, as a phone number, or as a device specific name or identifier. Using a phone number may be practical in environments where a single line is assigned lots of addresses.

See Also

Functions: lineMakeCall

Data Types: LINEADDRESSMODE


lineGetAddressStatus

Syntax

LONG lineGetAddressStatus(hLine, dwAddressID, lpAddressStatus)
This operation allows an application to query the specified address for its current status.

Parameters

HLINE hLine
Specifies a handle to the open line device.

DWORD dwAddressID
Specifies an address on the given open line device. This is the address to be queried.

LPLINEADDRESSSTATUS lpAddressStatus
Specifies a far pointer to a variable sized data structure of type LINEADDRESSSTATUS.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:
LINEERR_INVALLINEHANDLE
The specified device handle is invalid.
LINEERR_INVALADDRESSID
The specified address ID is out of range.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

None.

See Also

Data Types: LINEADDRESSSTATUS


lineGetCallInfo

Syntax

LONG lineGetCallInfo(hCall, lpCallInfo)
This operation enables an application to obtain fixed information about the specified call.

Parameters

HCALL hCall
Specifies a handle to the call to be queried.

LPLINECALLINFO lpCallInfo
Specifies a far pointer to a variable sized data structure of type LINECALLINFO. Upon successful completion of the request, this structure is filled with call related information.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:
LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

hCall any state

Comments

A separate LINECALLINFO structure exists for every (inbound or outbound) call. The structure contains primarily fixed information about the call. An application would typically be interested in checking this information when it receives its handle for a call via the LINE_CALLSTATE message, or each time it receives notification via a LINE_CALLINFO message that parts of the call information structure have changed. These messages supply the handle for the call as a parameter.

See Also

Messages: LINE_CALLINFO

Data Types: LINECALLINFO


lineGetCalls

Syntax

LONG lineGetCalls(hLine, dwAddressID, hCall, dwCallSelect, dwPrivilegeSelect, dwCallPrivilege, lpCallList)
This operation returns call handles selected by the specified set of parameters. The app can specify the privileges it wants to these calls.

Parameters

HLINE hLine
Specifies a handle to an open line device.
DWORD dwAddressID
Specifies an address on the given open line device.
HCALL hCall
Specifies a handle to a call.
DWORD dwCallSelect
Specifies the selection of calls that are requested, of type LINECALLSELECT. Values are:
LINECALLSELECT_LINE
Selects calls on this specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.
LINECALLSELECT_ADDRESS
Selects call on the specified address. Both hLine and dwAddressID must be valid; hCall is ignored.
LINECALLSELECT_CALL
Selects calls related to the specified call. hCall must be valid; hLine and dwAddressID are both ignored. If hCall is a participating call in a conference call, then the conference call handle is returned; if hCall is a conference call, then handles for all participating calls are returned.
DWORD dwPrivilegeSelect
Specifies the privilege(s) the application must currently have to the calls to be selected, of type LINECALLPRIVILEGE. Multiple flags can be combined. Values are:
LINECALLPRIVILEGE_NONE
Included in the selection are calls for which the app does not have any access privileges, i.e., calls for which the app currently has no handle.
LINECALLPRIVILEGE_MONITOR
Included in the selection are calls for which the app has monitor privileges.
LINECALLPRIVILEGE_OWNER
Included in its selection are calls for which the app currently has owner privileges.
DWORD dwCallPrivilege
Specifies the privilege the application wants to have for the returned calls, of type LINECALLPRIVILEGE. If multiple values are specified, then the highest privilege will be assigned. Values are:
LINECALLPRIVILEGE_NONE
The app requests no privileges to the call, i.e., it wants to get rid of its current handles for the calls.
LINECALLPRIVILEGE_MONITOR
The app requests monitor privileges to the call. These privileges allow the app to monitor state changes and query information and status about the call.
LINECALLPRIVILEGE_OWNER
The app requests owner privileges to the call. These privileges allow the app to manipulate the call in ways that affect the state of the call.
LPLINECALLLIST lpCallList
Specifies a far pointer to a variable sized data structure of type LINECALLLIST. Upon successful completion of the request, call handles to all selected calls are returned in this structure. Only calls whose handles are returned in this list are affected.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line device handle is invalid and is expected to be valid.
LINEERR_INVALADDRESSID
The specified address ID is invalid and is expected to be valid.
LINEERR_INVALCALLHANDLE
The specified call handle is invalid and is expected to be valid.
LINEERR_INVALCALLSELECT
The specified call select parameter is invalid.
LINEERR_INVALPRIVSELECT
The specified call privilege selection parameter is invalid.
LINEERR_INVALCALLPRIVILEGE
The specified call privilege parameter is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

hCall Any state

Comments

An application can use lineGetCalls to get handles to calls, to change its privileges to calls, or to get rid of handles it currently has to calls. The app can select for which calls handles are to be returned and what privilege it wants to these calls. The selection is based on scope (call on a line, calls on an address, calls related to another call) and the privilege the app currently has to the calls. For example, an app can request call handles with owner privileges to all calls on a given address for which it currently has either no handle or only monitoring privileges. The app can, for example, also use this operation to get rid of all its call handles for all calls on the opened line device. Note that, as with lineHandoff, the handle will not be deallocated if the app is the sole owner of a non idle call. The app must first either explicitly drop the call or successfully hand off ownership to another app before it can do so.

The app can invoke lineGetCallInfo and/or lineGetCallStatus for each call in the list to determine the call's information or status.

See Also

Functions: lineHandoff

Data Types: LINECALLSELECT, LINECALLPRIVILEGE, LINECALLLIST


lineGetCallStatus

Syntax

LONG lineGetCallStatus(hCall, lpCallStatus)
This operation returns the current status of the specified call.

Parameters

HCALL hCall
Specifies a handle to the call to be queried.

LPLINECALLSTATUS lpCallStatus
Specifies a far pointer to a variable sized data structure of type LINECALLSTATUS. Upon successful completion of the request, this structure is filled with call status information.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

hCall
Any state

Comments

lineCallStatus returns the dynamic status of a call, whereas lineGetCallInfo returns primarily static information about a call. Call status information includes the current call state, detailed mode information related to the call while in this state (if any), as well as a list of the available API functions the application can invoke on the call while the call is in this state. An application would typically be interested in requesting this information when it receives notification about a call state change via the LINE_CALLSTATE message.

See Also

Data Types: LINECALLSTATUS


lineGetDevCaps

Syntax

LONG lineGetDevCaps(hApp, dwDeviceID, dwAPIVersion, dwLowVersion, dwHighVersion, lpLineDevCaps)
This function queries a specified line device to determine its telephony capabilities. The returned information is valid for all addresses on the line device.

Parameters

HLINEAPP hApp
Specifies the handle to the app's registration with the API.

DWORD dwDeviceID
Specifies the line device to be queried.

DWORD dwAPIVersion
This number is zero if the API version number is to be negotiated, and dwLowVersion and dwHighVersion specify the API version range the application can operate with. lpLineDevCaps will contain the selected API version number and the Extension ID that defines any available device specific extensions.

dwAPIVersion is non-zero if the API version number has been previously negotiated, and dwLowVersion and dwHighVersion specify the Extension version range of the device specific extensions (specific to the Extension ID) the app can operate with. lpLineDevCaps will contain the selected Extension version number.

DWORD dwLowVersion
If dwAPIVersion is zero, this field specifies the earliest API version the app is compliant with. The high order word is the major version number, the low order word is the minor version number.

If dwAPIVersion is non zero, this field specifies the earliest Extension version the app is compliant with (specific to the Extension ID returned in lpLineDevCaps). The high order word is the major version number, the low order word is the minor version number.

DWORD dwHighVersion
If dwAPIVersion is zero, this field specifies the latest API version the app is compliant with. The high order word is the major version number, the low order word is the minor version number.

If dwAPIVersion is non zero, this field specifies the latest Extension version the app is compliant with (specific to the Extension ID returned in lpLineDevCaps). The high order word is the major version number, the low order word is the minor version number.

LPLINEDEVCAPS lpLineDevCaps
Specifies a far pointer to a variable sized structure of type LINEDEVCAPS. Upon successful completion of the request, this structure is filled with line device capabilities information.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALAPPHANDLE
The specified app registration handle is invalid.
LINEERR_BADDEVICEID
The specified line device ID is out of range.
LINEERR_NODRIVER
The driver was not installed.
LINEERR_INCOMPATIBLEVERSION
The app requested a version range that cannot supported by the Telephony API implementation and/or corresponding service provider version.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

Use lineInitialize to determine the number of line devices present in the system. The device ID specified by dwDeviceID varies from zero to one less than the number of line devices present.

LineGetDevCaps is invoked either once or twice, depending on whether or not the application wants to use device specific extensions.

When called for the first time, the app must negotiate the API version number to use. It does by specifying dwAPIVersion as zero and providing the API version range in dwLowVersion and dwHighVersion. lpLineDevCaps returns the selected API version number, and Extension ID, and the line's device capabilities for the selected API version.

If the app wants to enable the extensions defined by the Extension ID, it call lineGetDevCaps a second time. The app specifies the previously negotiated API version as dwAPIVersion, and provides the Extension ID-compatible version range in dwLowVersion and dwHighVersion. In addition to the information returned previously, lpLineDevCaps also returns the selected Extension version number and any device specific device capabilities for this extension.

The API and Extension version numbers are those under which the API, Telephony DLL and service provider must operate. If version ranges do not overlap, then the app and API or service provider versions are incompatible and an error is returned.

One of the fields in the LINEDEVCAPS structure returned by this function contains the number of addresses assigned to the specified line device. The actual address IDs used to reference individual addresses vary from zero to one less than the returned number. The capabilities of each address may be different. Use lineGetAddressCaps for each available <dwDeviceID, dwAddressID> combination to determine the exact capabilities of each address.

See Also

Data Types: LINEDEVCAPS


lineGetID

Syntax

LONG lineGetID(hLine, dwAddressID, hCall, dwSelect, lpDeviceID, lpszDeviceClass)
This function returns a device ID for the specified device class associated with the selected line, address or call.

Parameters

HLINE hLine
Specifies a handle to an open line device.

DWORD dwAddressID
Specifies an address on the given open line device.

HCALL hCall
Specifies a handle to a call.

DWORD dwSelect
Specifies the whether the device ID requested is associated with the line, address or a single call, of type LINECALLSELECT. Values are:

LINECALLSELECT_LINE
Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.
LINECALLSELECT_ADDRESS
Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.
LINECALLSELECT_CALL
Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.
LPVARSTRING lpDeviceID
Specifies a far pointer to the memory location of type VARSTRING where the device ID is returned. Upon successful completion of the request, this location is filled with the device ID. The format of the returned information depends on the method used by the device class (API) for naming devices.
LPCSTR const lpszDeviceClass
Specifies a far pointer to a NULL-terminated ASCII string that specifies the device class of the device whose ID is requested. Valid device class strings are those used in the SYSTEM.INI section to identify device classes.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The hLine parameter is an invalid handle.
LINEERR_INVALADDRESSID
The specified dwAddressID parameter is invalid.
LINEERR_INVALCALLHANDLE
The hCall parameter is an invalid handle.
LINEERR_INVALCALLSELECT
The specified dwCallSelect parameter is invalid.
LINEERR_NODEVICE
The line device has no associated device for the given device class.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

This function can be used to retrieve a line device ID given a line handle. This is useful after a line device has been opened using LINE_MAPPER as a device ID in order to determine the real line device ID of the opened line. This function can also be used to obtain the device ID of a phone device or media device (e.g., mci waveform, mci midi, wave, fax, etc.) associated with a call, address or line. This ID can then be used with the appropriate API (e.g., phone, mci, midi, wave, etc.) to select the corresponding media device associated with the specified call.

Note that the notion of Windows device class is different from that of media mode. For example, the interactive voice or stored voice media modes may be accessed using either the mci waveaudio or the low level wave device classes. A media modes describes a format of information on a call, a device class defines a Windows API used to manage that stream. Often, a single media stream may be accessed using multiple device classes, or a single device class (e.g., the Windows COMM API) may provide access to multiple media modes.

See Also

None.


lineGetLineDevStatus

Syntax

LONG lineGetLineDevStatus(hLine, lpLineDevStatus)
This operation enables an application to query the specified open line device for its current status.

Parameters

HLINE hLine
Specifies a handle to the open line device to be queried.

LPLINEDEVSTATUS lpLineDevStatus
Specifies a far pointer to a variable sized data structure of type LINEDEVSTATUS. Upon successful completion of the request, this structure is filled with the line's device status.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line device handle is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

An application uses lineGetLineDevStatus to query the line device for its current line status. This status information applies globally to all addresses on the line device. Use lineGetAddressStatus to determine status information about a specific address on a line.

See Also

Messages: LINE_LINEDEVSTATE

Data Types: LINEDEVSTATUS


lineGetNumRings

Syntax

LONG lineGetNumRings(hLine, dwAddressID, lpdwNumRings)
This function can be used by any application to determine the number of rings an inbound call on the given address should ring prior to answering the call.

Parameters

HLINE hLine
Specifies a handle to the open line device.

DWORD dwAddressID
Specifies an address on the line device.

LPDWORD lpdwNumRings
Specifies the number of rings that is the minimum of all current lineSetNumRings requests.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified device handle is invalid.
LINEERR_INVALADDRESSID
The specified address ID is out of range.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

lineGetNumRings and lineSetNumRings when used in combination provide a mechanism to support the implementation of toll saver features across multiple independent applications.

An application that receives a handle for a call in the offering state and a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll saver settings across all applications. lineGetNumRings returns the minimum of all application's number of rings specified via lineSetNumRings. Since this number may vary dynamically, an application should invoke lineGetNumRings each time it has the option to answer a call. If no application has called lineSetNumRings, then the number or rings returned is 0xFFFFFFFF. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle.

If call classification is performed by the API implementation by means of answering all calls of unknown media mode and filtering the media stream, then the API implementation will honor this number as well.

Note that this operation is purely informational and does not in itself affect the state of any calls on the line device.

See Also

Functions: lineSetNumRings

Messages: LINE_LINEDEVSTATE


lineGetRequest

Syntax

LONG lineGetRequest(hApp, dwRequestMode, lpRequestBuffer)
This function retrieves the next by-proxy request for the specified request mode.

Parameters

HLINEAPP hApp
Specifies the application's usage handle for the line portion of the API.

DWORD dwRequestMode
Specifies the type of request that is to be obtained, of type LINEREQUESTMODE. Values are:

LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.
LINEREQUESTMODE_MEDIACALL
A tapiRequestMediaCall request.
LINEREQUESTMODE_DROP
A tapiRequestDrop request.
LINEREQUESTMODE_LOGENTRY
A lineRequestLogEntry request.

LPVOID lpRequestBuffer
Specifies a far pointer to a memory buffer where the parameters of the request are to be placed. The size of the buffer and the interpretation of the information placed in the buffer depends on the request mode. The application-allocated buffer is assumed to be of sufficient size to hold the request.
If dwRequestMode is LINEREQUEST_MAKECALL, then interpret the content of the request buffer using the LINEREQMAKECALL structure.
If dwRequestMode is LINEREQUEST_MEDIACALL, then interpret the content of the request buffer using the LINEREQMEDIACALL structure.
If dwRequestMode is LINEREQUEST_DROP, then interpret the content of the request buffer using the LINEREQDROP structure.
If dwRequestMode is LINEREQUEST_LOGENTRY, then interpret the content of the request buffer using the LINEREQLOGENTRY structure.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALAPPHANDLE
The specified application handle is invalid.
LINEERR_INVALREQUESTMODE
The specified request mode is invalid.
LINEERR_NOTREGISTERED
The specified request mode is invalid.
LINEERR_NOREQUEST
There currently is no request pending of the indicated mode.
LINEERR_INVALPOINTER
The specified request buffer pointer parameter is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

An telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall or tapiRequestMediaCall, and drop a media call via tapiRequestDrop. Additionally, other applications can request information be logged with a given call using lineRequestLogEntry. These requests are queued by the Telephony DLL and the (highest priority) application that has registered to handle the request is sent a LINE_REQUEST message with indication of the mode of the request that is pending. This application will typically be the user's call control application. Next, the call control application that receives this message invokes lineGetRequest specifying the request mode and a buffer that is large enough to hold the request. The call control application then interprets and executes the request. For media mode handling, the serving application may need to send Windows messages back to the original application that made the request. The TAPI_REPLY message is used for this purpose.

After execution of lineGetRequest, the Telephony DLL purges the request from its internal queue, making available room for a subsequent request. It is possible, therefore, for a new LINE_REQUEST message to be received immediately upon execution of lineGetRequest, should the same or another application issue another request. It is the responsibility of the request recipient application to handle this eventuality by some mechanism (e.g., making note of the additional LINE_REQUEST and deferring a subsequent lineGetRequest until processing of the preceeding request completes, get the subsequent request and buffer as necessary, or other appropriate handling). Note that the subsequent LINE_REQUEST should not be ignored because it will not be repeated by the Telephony DLL.

See Also

Functions: tapiRequestMakeCall, tapiRequestMediaCall, tapiRequestDrop, tapiRequestLogEntry, lineRegisterRequestRecipient

Messages: TAPI_REPLY, LINE_REQUEST

Data Types: LINEREQUESTMODE, LINEREQMAKECALL, LINEREQMEDIACALL, LINEREQDROP, LINEREQLOGENTRY


lineGetStatusMessages

Syntax

LONG lineGetStatusMessages(hLine, lpdwLineStates, lpdwAddressStates)
This operation enables an application to query for which notification messages the app is set up to receive for events related to status changes for the specified line or any of its addresses

Parameters

HLINE hLine
Specifies a handle to the line device.

LPDWORD lpdwLineStates
Specifies a bit array that identifies for which line device status changes a message is to be sent to the application, of type LINEDEVSTATE. If a flag is TRUE, then that message is enabled; FALSE if disabled. Values are:

LINEDEVSTATE_OTHER
An other device status item has changed.
LINEDEVSTATE_RINGING
The switch tells the line to alert the user.
LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to the API.
LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from the API.
LINEDEVSTATE_MSGWAITON
The message waiting indicator is turned on.
LINEDEVSTATE_MSGWAITOFF
The message waiting indicator is turned off.
LINEDEVSTATE_INSERVICE
The line is connected to the API. This happens when the API is first activated, or when the line wire is physically plugged in and in service at the switch while the API is active.
LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. The API cannot be used to operate on the line device.
LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. The API cannot be used to operate on the line device.
LINEDEVSTATE_OPEN
The line has been opened by some application.
LINEDEVSTATE_CLOSE
The line has been closed by some application.
LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.
LINEDEVSTATE_TERMINALS
The terminal settings have changed.
LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.
LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).
LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).
LINEDEVSTATE_DEVSPECIFIC
The line's device specific information has changed.
LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (e.g., new line devices) the app should reinitialize its use of the API. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system.
LINEDEVSTATE_LOCK
The locked status of the line device has changed.
LPDWORD lpdwAddressStates
Specifies a bit array that identifies for which address status changes a message is to be sent to the application, of type LINEADDRESSSTATE. If a flag is TRUE, then that message is enabled; FALSE if disabled. Values are:
LINEADDRESSSTATE_OTHER
An status item or multiple items in the address' status not listed below have changed. The app should check the current address status to determine which items have changed.
LINEADDRESSSTATE_DEVSPECIFIC
The device specific item of the address status has changed.
LINEADDRESSSTATE_INUSEZERO
The address has changed to idle; i.e., it is now in use by zero stations.
LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.
LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed to being in use by one station to being used by more than one station.
LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of either a new inbound call, or an outbound call on the address, a call changing its hold status, etc.
LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed including the number of rings for determining a no answer condition. The app should check the address status to determine details about the address' current forwarding status.
LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

Not applicable.

Comments

The API defines a number of messages that notify applications about events occurring on lines and addresses. An app may not be interested in receiving all address and line status change messages. lineSetStatusMessages can be used to select which messages the app wants to receive. By default, address status and line status reporting is disabled.

See Also

Functions: lineSetStatusMessages

Messages: LINE_LINEDEVSTATE, LINE_ADDRESSSTATE

Data Types: LINEDEVSTATE, LINEADDRESSSTATE


lineHandoff

Syntax

LONG lineHandoff(hCall, lpsModuleName, dwSize, dwMediaMode, dwCallPrivilege)
This function is used to pass ownership of the specified call to another application. The application can be either specified directly via its module name, or indirectly as the highest priority application that handles call of the specified media mode. Handing off of calls can also be used to alter one's privilege to a specified call, including deallocating one's call handle.

Parameters

HCALL hCall
Specifies a handle to the call to be handed off.

LPCSTR const lpsModuleName
Specifies a far pointer to a string of the format specified in the dwStringFormat field of the line device capabilities. If this parameter is non-NULL, then it contains the module name of the application that is the target of the handoff. If NULL, then the handoff target is the highest priority application that has opened the line for owner privileges for the specified media mode.

DWORD dwSize
Specifies the size in bytes of the string pointed at by the lpsModuleName parameter. This parameter is ignored in lpsModuleName is NULL.

DWORD dwMediaMode
Specifies the media mode used to identify the target for the handoff, of type LINEMEDIAMODE. The dwMediaMode parameter indirectly identifies the target application that is to receive ownership of the call. The highest priority application that has opened the line device for the specified media mode will be the application that receives the call. Values are:

LINEMEDIAMODE_NONE
This is used as a NULL value for the data type. If specified, handoff target it none, i.e., the app just wants to alter its privilege to a call. This is used if an app wants to deallocate its call handle.
LINEMEDIAMODE_UNKNOWN
The target app is the one that handles calls of unknown media mode; i.e., unclassified calls.
LINEMEDIAMODE_INTERACTIVEVOICE
The target app is the one that handles calls with the interactive voice media mode; i.e., live conversations.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DIGITALDATA
The target app is the one that handles calls that are digital data calls.
LINEMEDIAMODE_G3FAX
The target app is the one that handles calls with the group 3 fax media mode.
LINEMEDIAMODE_G4FAX
The target app is the one that handles calls with the group 4 fax media mode.
LINEMEDIAMODE_DATAMODEM
The target app is the one that handles calls with the data modem media mode.
LINEMEDIAMODE_TELETEX
The target app is the one that handles calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The target app is the one that handles calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The target app is the one that handles calls with the telex media mode.
LINEMEDIAMODE_MIXED
The target app is the one that handles calls with the ISDN mixed media mode.
LINEMEDIAMODE_TDD
The target app is the one that handles calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_ADSI
The target app is the one that handles calls with the ADSI (Analog Display Services Interface) media mode.
DWORD dwCallPrivilege
Specifies the call privileges the invoking app wants to remain with for the specified call, of type LINECALLPRIVILEGE. Values are:
LINECALLPRIVILEGE_NONE
The application wants to get rid of its call handle. This corresponds to a request to deallocate the app's call handle.
LINECALLPRIVILEGE_MONITOR
The application only wants to monitor the specified call.
LINECALLPRIVILEGE_OWNER
The application wants to remain co-owner of the call.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALMEDIAMODE
The specified media mode parameter is invalid.
LINEERR_INVALMODULENAME
The specified module name parameter is invalid.
LINEERR_INVALCALLPRIVILEGE
The specified call privilege parameter is invalid.
LINEERR_TARGETNOTFOUND
A target for the call handoff was not found.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall Any state

Comments

Call handoff allows ownership of a call to be passed among applications. There are two flavors of handoff. If the application knows the module name of the target application, then it can specify the module name of the application. If an instance of the target application has opened the line device, then ownership of the call will be passed to the other app; otherwise, the handoff will fail and an error is returned.

The second type of handoff is based on media mode. Here, the application indirectly specifies the target application by means of a media mode. The highest priority app that has currently opened the line device for that media mode is the target for the handoff. If there is no such application, then the handoff fails and an error is returned.

lineHandoff does not change the media mode of a call. To change the media mode of a call the app should use lineSetMediaMode on the call specifying the new media mode. This changes the call's media as stored in the call's LINECALLINFO structure.

If handoff is successful, then the receiving application will receive a LINE_CALLSTATE message for the call. This message indicates that the receiving application has owner privileges to the call. Additionally, the change in the number of owners and/or monitors for the call may have changed which is reported via the LINE_CALLINFO message. The receiving app can then invoke lineGetCallStatus and lineGetCallInfo to find out more information about the received call.

If the operation fails, then the privileges of the invoking application to the call are unchanged. Instead of being given handles to existing calls, any application that has opened a line device can also ask for handles to calls on the line device by invoking lineGetCalls.

An app that has obtained a call handle for a call must deallocate the call handle when it is finished using the call handle. To deallocate a call handle, an app must invoke lineHandoff providing the call handle to be deallocated, with dwMediaMode equal to LINEMEDIAMODE_NONE and dwCallPrivilege equal to LINECALLPRIVILEGE_NONE. The app's call handle is void as soon as the function returns successful. Multiple call handles can also be deallocated at once via lineGetCalls. A call handle cannot be deallocated if the app is the sole owner of the call and the call is not idle.

See Also

Functions: lineGetCalls

Messages: LINE_CALLSTATE

Data Types: LINEMEDIAMODE, LINECALLPRIVILEGE


lineHold

Syntax

LONG lineHold(hCall)
This function places the specified call on hold.

Parameters

HCALL hCall
Specifies a handle to the call to be placed on hold. The app must be an owner of the call.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALCALLSTATE
The specified call is not in a valid state for the requested operation.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall connected

Comments

The call on hold is temporarily disconnected allowing the application to use the line device for making or answering other calls. lineHold performs a so-called "hard hold" of the specified call, as opposed to a "consultation call". A call on hard hold typically cannot be transferred or included in a conference call, whereas a consultation call can. Consultation calls are initiated using lineSetupTransfer, lineSetupConference, or linePrepareAddToConference.

After a call has been successfully placed on hold, the call state will typically transition to onHold. A held call is retrieved via lineUnhold. While a call is on hold, the app may receive LINE_CALLSTATE messages about state changes of the held call. For example, if held party hangs up, the call state may transition to disconnected.

See Also

Functions: lineUnhold

Messages: LINE_CALLSTATE


lineInitialize

Syntax

LONG lineInitialize(lphApp, hInstance, lpfnCallback, lpsAppName, dwSize, lpdwNumDevs)
This function initializes the application's use of the Telephony API DLL for subsequent use of the line abstraction. It registers the application's specified notification mechanism and returns the number of line devices available to the application. A line device is any device that provides an implementation for the line-prefixed functions in the Telephony API.

Parameters

LPHLINEAPP lphApp
Specifies a far pointer to a location that is filled with the app's usage handle for the API.

HINSTANCE hInstance
Specifies the instance handle of the client application or DLL.

LINECALLBACK lpfnCallback
Specifies the address of a callback function to be invoked related to status and events on the line device, addresses, or calls.

LPCSTR const lpsAppName
Specifies a far pointer to a string of the format specified in the dwStringFormat field of the line device capabilities. If this parameter is non-NULL, then it contains an application-supplied name of the app. This name is provided in the LINECALLINFO structure to indicate in a user-friendly way, which application originated, or orignally accepted or answered the call. This information can be useful for call logging purposes. If lpsAppName is NULL, then the application's module name will used instead.

DWORD dwSize
Specifies the size in bytes of the string pointed at by the lpsAppName parameter. This parameter is ignored in lpsAppName is NULL.

LPDWORD lpdwNumDevs
Specifies a far pointer to a DWORD sized location. Upon successful completion of this request, this location is filled with the number of line devices available to the application.

Return Value

Returns zero if the function is successful, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALAPPNAME
The specified app name is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Callback

VOID FAR PASCAL lineCallbackFunc(hDevice, dwMsg, dwCallbackInstance, dwParam1, dwParam2, dwParam3)
lineCallbackFunc is a placeholder for the application-supplied function name.

Parameters

HANDLE hDevice
Specified a handle to either a line device or a call associated with the callback. The nature of this handle (line handle or call handle) can be determined by the context provided by dwMsg.

DWORD dwMsg
Specifies a line or call device message.

DWORD dwCallbackInstance
Specifies callback instance data passed back to the application in the callback. This DWORD is not interpreted by the API.

DWORD dwParam1
Specifies a parameter for the message.

DWORD dwParam2
Specifies a parameter for the message.

DWORD dwParam3
Specifies a parameter for the message.

Comments

The actual parameters passed to the application's callback function are described in the Messages Chapter of this document.

All callbacks occur in the application's context. The callback function must reside in a dynamic link library (DLL) or application module and be exported in the module definition file. You must use MakeProcInstance to get a procedure-instance address for the callback function.

Comments

The app can refer to individual line devices by using line device IDs that range from zero to dwNumDevs - 1. An application should not assume that these line devices are capable of anything beyond what is specified by the simple telephony subset without first querying their device capabilities via lineGetDevCaps and lineGetAddressCaps.

See Also

Functions: lineShutdown


lineMakeCall

Syntax

LONG lineMakeCall(hLine, lphCall, lpszDestAddress, dwCountryCode, lpCallParams)
This function places a call on the specified line to the specified destination address. Optionally, call parameters can be specified if anything but default call setup parameters are requested.

Parameters

HLINE hLine
Specifies a handle to the open line device on which a call is to be originated.

LPHCALL lphCall
Specifies a far pointer to a HCALL handle. This location is filled with a handle identifying the new call as soon as this function call returns. Use this handle to identify the call when invoking other telephony operations on the call. The app will initially be the sole owner of this call. This handle is void if the function returns an error (synchronously or asynchronously via the reply message).

LPCSTR const lpszDestAddress
Specifies a far pointer to the destination address. This follows the standard dialable number format. This pointer may be specified as NULL for non-dialed addresses (i.e., a hot phone) or when all dialing will be performed using lineDial. In the latter case, lineMakeCall will allocate an available call appearance which would typically remain in the dialtone state until dialing begins. Service providers that have inverse multiplexing capabilities may allow an application to specify multiple addresses at once.

DWORD dwCountryCode
Specifies the country code of the called party. If a value of zero is specified, then a default will be used by the implementation.

LPLINECALLPARAMS const lpCallParams
Specifies a far pointer to a LINECALLPARAMS structure. This structure allows the application to specify how it wants the call to be set up. If NULL is specified, then a default 3.1kHz voice call is established, and an arbitrary origination address on the line is selected.

This structure allows the application to select such elements as the call's bearer mode, data rate, expected media mode, origination address, blocking of caller ID information, dialing parameters, etc.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line device handle is invalid.
LINEERR_INVALADDRESS
The specified address is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_CALLUNAVAIL
All call appearances on the specified address are currently in use.
LINEERR_INVALPARAM
The specified country code is invalid.
LINEERR_INVALCALLPARAMS
The specified call parameter structure is invalid.
LINEERR_ADDRESSBLOCKED
The specified address is blocked from being dialed on the specified call.
LINEERR_BILLINGREJECTED
The billing information specified as part of the destination address has been rejected.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

Not applicable

Comments

After dialing has completed, several LINE_CALLSTATE messages will typically be sent to the application to notify it about the progress of the call. No generally valid sequence of call state transitions is specified as no single fixed sequence of transitions can be guaranteed in practice. A typical sequence may cause a call to transition from dialtone, dialing, proceeding, ringback, to connected. With non-dialed lines, the call may typically transition directly to connected state.

An application has the option to specify an originating address on the specified line device. A service provider that models all stations on a switch as addresses on a single line device allows the application to originate calls from any of these stations using lineMakeCall.

The call parameters allow the application to make non voice calls or request special call setup options that are not available by default.

An application can partially dial using lineMakeCall and continue dialing using lineDial. To abandon a call attempt, use lineDrop.

See Also

Functions: lineDial

Messages: LINE_CALLSTATE

Data types: LINECALLPARAMS


lineMonitorDigits

Syntax

LONG lineMonitorDigits(hCall, dwDigitModes)
This function enables and disables the unbuffered detection of digits received on the call. Each time a digit of the specified digit mode(s) is detected a message is sent to the application indicating which digit has been detected.

Parameters

HCALL hCall
Specifies a handle to the call on which digits are to be detected.

DWORD dwDigitModes
Specifies the digit mode(s) that are to be monitored, of type LINEDIGITMODE. Values are:

LINEDIGITMODE_PULSE
Detect digits as audible clicks that are the result of rotary pulse sequences. Valid digits for pulse are '0' through '9'.

LINEDIGITMODE_DTMF
Detect digits as DTMF tones. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.

LINEDIGITMODE_DTMFEND
Detect and provide application notification of DTMF down edges. Valid digits for DTMF are '0' through '9', 'A', 'B', 'C', 'D', '*', and '#'.
A dwDigitModes with a value of zero cancels digit monitoring.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALDIGITS
The specified digits are not valid.
LINEERR_INVALDIGITMODE
The specified digit mode is invalid.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The operation is not available.
LINEERR_OPERATIONFAILED
The operation failed for unspecified reasons.

Call States

hCall Any state

Comments

This function is considered successful if digit monitoring has been correctly initiated; not when digit monitoring has terminated. Digit monitoring will remain in effect until it is explicitly disabled by calling lineMonitorDigits with dwDigitModes set to zero, or until the call transitions to idle.

Although this function can be invoked in any call state, digits will typically only be detected while the call is in the connected state.

Each time a digit is detected, a LINE_MONITORDIGITS message is sent to the application passing the detected digit as a parameter.

An application can use lineMonitorDigits to enable or disable unbuffered digit detection. It can use lineGatherDigits for buffered digit detection. After buffered digit gathering is complete, a LINE_GATHERDIGITS message is sent to the application. Both buffered and unbuffered digit detection can be enabled on the same call simultaneously.

See Also

Functions: lineGetDevCaps, lineGatherDigits, lineSetMediaControl

Messages: LINE_MONITORDIGITS

Data Types: LINEDEVCAPS, LINEDIGITMODE


lineMonitorMedia

Syntax

LONG lineMonitorMedia(hCall, dwMediaModes)
This function enables and disables the detection of media modes on the specified call. When a media mode is detected, a message is sent to the application.

Parameters

HCALL hCall
Specifies a handle to the call.

DWORD dwMediaModes
Specifies the media modes to be monitored, of type LINEMEDIAMODE. Values are:

LINEMEDIAMODE_NONE
This is used as a NULL value for the data type.
LINEMEDIAMODE_INTERACTIVEVOICE
The app wants to handle calls of the interactive voice media type; i.e., it manages live voice calls.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DIGITALDATA
The app wants to handle calls of the digital data media type
LINEMEDIAMODE_G3FAX
The app wants to handle calls of the group 3 fax media type.
LINEMEDIAMODE_G4FAX
The app wants to handle calls of the group 4 fax media type.
LINEMEDIAMODE_DATAMODEM
The app wants to handle calls with the data modem media mode.
LINEMEDIAMODE_TELETEX
The app wants to handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The app wants to handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The app wants to handle calls with the telex media mode.
LINEMEDIAMODE_MIXED
The app wants to handle calls with the telex media mode.
LINEMEDIAMODE_TDD
The app wants to handle calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_ADSI
The app wants to handle calls with the ADSI (Analog Display Services Interface) media mode.

A value of zero for the dwMediaModes parameter cancels all media mode detection.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALMEDIAMODE
The list of media types to be monitored contains invalid information.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation is failed for unspecified reasons.

Call States

hCall Any state

Comments

This function is considered successful if media mode monitoring has been correctly initiated; not when media mode monitoring has terminated. Media monitoring for a given media mode will remain in effect until it is explicitly disabled by calling lineMonitorMedia with a dwMediaModes parameter with the media mode set to zero, or until the call transitions to idle. lineMonitorMedia is primarily an event reporting mechanism. the media mode of call, as indicated in LINECALLINFO, is not affected by the service provider's detection of the media mode. Only the controlling application can change a call's media mode.

Default media monitoring performed by the service provider corresponds to the union of all media modes specified on lineOpen.

Although this function can be invoked in any call state, a call's media mode can typically only be detected while the call is certain call states. These states may be device specific. For example, in ISDN a message may indicate the media mode of the media stream before the media stream exists. Similarly, distinctive ringing or the called ID information about the call can be used to identify the media mode of a call. Otherwise, the call may have to be answered (call in the connected state) to allow a service provider to determine the call's media mode by filtering of the media stream. Since filtering of a call's media stream implies a computational overhead, apps should disable media monitoring when not required. By default, media monitoring will be enabled for newly inbound calls since a call's media mode selects the app that should handle the call.

An outbound application that deals with voice media modes may want to monitor the call for silence (a tone) in order to distinguish who or what is at the called end of a call. For example, a person at home may answer calls with just a short "hello". A person in the office may provide a longer greeting, indicating name and company name. An answering machine may typically have an even longer greeting.

See Also

Functions: lineGetDevCaps, lineSetMediaControl

Messages: LINE_MONITORMEDIA

Data Types: LINEDEVCAPS, LINEMEDIAMODE


lineMonitorTones

Syntax

LONG lineMonitorTones(hCall, lpToneList, dwNumEntries)
This function enables and disables the detection of inband tones on the call. When a specified tone is detected, a message is sent to the application.

Parameters

HCALL hCall
Specifies a handle to the call on whose voice channel tones are to be monitored.

LPLINEMONITORTONE const lpToneList
Specifies a list of tones to be monitored, of type LINEMONITORTONE. Each tone in this list has an app defined tag field that is used to identify individual tones in the list for the purpose of reporting a tone detection. Tone monitoring in progress is canceled or changed by calling this operation with either NULL for lpToneList or with another tone list.

DWORD dwNumEntries
Specifies the number of entries in lpToneList.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALTONE
The specified tone structure does not describe a valid tone.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall Any state

Comments

This function is considered successful if tone monitoring has been correctly initiated; not when tone monitoring has terminated. Tone monitoring will remain in effect until it is explicitly disabled by calling lineMonitorTones with another tone list (or NULL), or until the call transitions to idle.

Although this function can be invoked in any call state, tones can typically only be detected while the call is in the connected state. Tone detection typically requires computational resources. Depending on the service provider and other activities that compete for such resources, the number of tones that can be detected may vary over time. Also, an equivalent amount of resources may be consumed for monitoring a single triple frequency tone versus three single frequency tones. If resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.

Note that lineMonitorTones is also used to detect silence. Silence is specified as a tone with all zero frequencies.

See Also

Functions: lineGetDevCaps, lineSetMediaControl

Messages: LINE_MONITORTONE

Data Types: LINEDEVCAPS, LINEMONITORTONE


lineOpen

Syntax

LONG lineOpen(hApp, dwDeviceID, lphLine, dwAPIVersion, dwExtVersion, dwCallbackInstance, dwPrivilege, dwMediaModes, lpCallParams)
This functions opens the line device specified by its device ID and returns a line handle for the corresponding opened line device. This line handle is used in subsequent operations on the line device.

Parameters

HLINEAPP hApp
Specifies a handle to the app's registration with the API.

DWORD dwDeviceID
Identifies the line device to be opened. It can either be a valid device ID or the value:

LINE_MAPPER
This value is used to open a line device in the system that supports the properties specified in lpCallParams. The application can use lineGetID to determine the ID of the line device that was opened.

LPHLINE lphLine
Specifies a far pointer to an HLINE handle, which is then loaded with the handle representing the opened line device. Use this handle to identify the device when invoking other functions on the open line device.

DWORD dwAPIVersion
Specifies the API version number under which the app and Telephony API have agreed to operate. This number is obtained from lineGetDevCaps.

DWORD dwExtVersion
Specifies the Extension version number under which the app and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained from lineGetDevCaps.

DWORD dwCallbackInstance
Specifies user instance data passed back to the application's callback. This parameter is not interpreted by the Telephony API.

DWORD dwPrivileges
Specifies the privilege the app wants for the calls it is notified for, of type LINECALLPRIVILEGE. Values are:

LINECALLPRIVILEGE_NONE
The app does not want to get handles to calls other than those it initiates itself.
LINECALLPRIVILEGE_MONITOR
The app wants to monitor other inbound and outbound calls on the line device.
LINECALLPRIVILEGE_OWNER
The app wants to own calls of the specified media mode(s).

DWORD dwMediaModes
Specifies the media mode(s) of interest to the app, of type LINEMEDIAMODE. The dwMediaModes parameter is used to register the app as a potential target for inbound call and call hand off for the specified media mode. This parameter is ignored if the OWNER flag is not set in dwPrivileges. Values are:

LINEMEDIAMODE_NONE
This is used as a NULL value for the data type. The app is not interested to be the target of any handoff or inbound calls.
LINEMEDIAMODE_UNKNOWN
The app wants to handle calls of unknown media type; i.e., unclassified calls.
LINEMEDIAMODE_INTERACTIVEVOICE
The app wants to handle calls of the interactive voice media type; i.e., it manages voice calls with the human user on this end of the call.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DIGITALDATA
The app wants to handle calls of the digital data media type.
LINEMEDIAMODE_G3FAX
The app wants to handle calls of the group 3 fax media type.
LINEMEDIAMODE_G4FAX
The app wants to handle calls of the group 4 fax media type.
LINEMEDIAMODE_DATAMODEM
The app wants to handle calls with the data modem media mode.
LINEMEDIAMODE_TELETEX
The app wants to handle calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The app wants to handle calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The app wants to handle calls with the telex media mode.
LINEMEDIAMODE_MIXED
The app wants to handle calls with the ISDN mixed media mode.
LINEMEDIAMODE_TDD
The app wants to handle calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_ADSI
The app wants to handle calls with the ADSI (Analog Display Services Interface) media mode.
LPLINECALLPARAMS const lpCallParams
Specifies a far pointer to a structure of type LINECALLPARAMS. This pointer is only used if LINE_MAPPER is used; otherwise lpCallParams is ignored. It describes the call parameter that the line device should be able to provide.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALAPPHANDLE
The specified app registration handle is invalid.
LINEERR_BADDEVICEID
The specified line device ID is out of range.
LINEERR_INCOMPATIBLEVERSION
The app requested an incompatible API version number.
LINEERR_INVALEXTVERSION
The app requested an invalid extension version number.
LINEERR_ALLOCATED
The specified line device has no resources available for another open request.
LINEERR_NOMEM
Unable to allocate or lock memory.
LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
LINEERR_NODRIVER
The driver was not installed.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

Not applicable.

Comments

Opening a line always entitles the application to make calls on any address available on the line. The ability of the app to deal with inbound calls or to be the target of call handoffs on the line is determined by the dwMediaModes parameter. The lineOpen function registers the app as having an interest in monitoring calls or receiving ownership of calls that are of the specified media modes. If the app just wants monitor calls then it can specify LINECALLPRIVILEGES_MONITOR. If the app just wants to make outbound calls then it can specify LINECALLPRIVILEGES_NONE. If the app is willing to control unclassified calls, i.e., calls of unknown media mode, then it can specify LINECALLPRIVILEGES_OWNER and LINEMEDIAMODE_UNKNOWN. Otherwise, the app should specify the media mode it is interested in handling.

Note that a single app may specify multiple flags simultaneously if it wants to handle multiple media modes. Conflicts may arise if multiple apps open the same line device for the same media mode. These conflicts are resolved via a priority scheme where the user assigns relative priorities to the apps. Only the highest priority app for a given media mode will ever receive ownership (unsolicited) of a call of that media mode. Ownership can be received when an inbound call first arrives or when a call is handed off. Note that any app (including any lower priority app) can always acquire ownership via lineGetCalls.

An application that handles automated voice should also select the interactive voice open mode and be assigned the lowest priority for interactive voice. The reason for this is that service providers will report all voice media modes as interactive voice. If media mode determination is not performed by the application for the UNKNOWN media type, and no interactive voice app has opened the line device, then voice calls would be unable to reach the automated voice app, but be dropped instead.

The same application or different instantiations of the same application may open the same line multiple times, possibly with the same or different parameters.

When an app opens a line device it must specify the negotiated API version and, if it wants to use the line's extensions, the line's device specific Extension version. This version numbers should have been obtained via lineGetDevCaps. Version numbering allows the mix and match of different app versions with different API versions and service provider versions.

The notion of LINE_MAPPER allows an app to select a line indirectly; i.e., by means of the services it wants from it.

See Also

Functions: lineClose

Data Types: LINEMEDIAMODE, LINECALLPARAMS


linePark

Syntax

LONG linePark(hCall, dwParkMode, lpszDirAddress, lpNonDirAddress)
This function parks the specified call according to the specified park mode.

Parameters

HCALL hCall
Specifies a handle to the call to be parked. The app must be an owner of the call.

DWORD dwParkMode
Specifies the park mode with which the call is to be parked, of type LINEPARKMODE. Values are:

LINEPARKMODE_DIRECTED
The app specifies the address at which address the call is to be parked in lpszDirAddress.
LINEPARKMODE_NONDIRECTED
This operation reports to the app where the call has been parked in lpNonDirAddress.
LPCSTR const lpszDirAddress
Specifies a far pointer to NULL-terminated string that indicates the address where the call is to be parked when using directed park. The address in dialable number format. This parameter is ignored for non directed park.
LPVARSTRING lpNonDirAddress
Specifies a far pointer to structure of type VARSTRING. For non directed park, the address where the call is parked is returned in this structure. This parameter is ignored for directed park.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified device handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALPARKMODE
The specified park mode is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_INVALCALLSTATE
The call is not in a valid state for the requested operation.
LINEERR_INVALADDRESS
The specified address is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall connected

Comments

Under directed park, the application determines the address at which it wants to park the call. Under non directed park, the switch determines the address and provides this to the application. In either case, a parked call can be unparked by specifying this address.

The parked call typically enters the idle call state after it has been successfully parked.

Some switches may remind the user after a call has been parked for some long amount of time. The application will see an offering call with a call reason set to reminder.

See Also

Functions: lineUnpark

Data Structures: LINEPARKMODE


linePickup

Syntax

LONG linePickup(hLine, dwAddressID, lphCall, lpszDestAddress, lpszGroupID)
This function picks up a call alerting at the specified destination address and returns a call handle for the picked up call. If invoked with NULL for the lpszDestAddress parameter, then a group pickup is performed. If required by the device capabilities, lpszGroupID specifies the group ID to which the alerting station belongs.

Parameters

HLINE hLine
Specifies a handle to the open line device on which a call is to be picked up.

DWORD dwAddressID
Specifies the address on hLine at which the pickup is to be originated.

LPHCALL lphCall
Specifies a far pointer to a memory location where the handle to picked up call will be returned. The app will be initial sole owner of the call.

LPCSTR const lpszDestAddress
Specifies a far pointer to a NULL terminated character buffer that contains the address whose call is to be picked up. The address is standard dialable address format.

LPCSTR const lpszGroupID
Specifies a far pointer to a NULL terminated character buffer containing the group ID to which the alerting station belongs. This parameter is required on some switches to pick up calls outside of the current pickup group.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.
LINEERR_INVALADDRESSID
The specified address ID is invalid.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_INVALADDRESS
The specified address is not a valid number.
LINEERR_INVALGROUPID
The specified group ID is invalid.
LINEERR_NOMEM
Unable to allocate or lock memory.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

Not applicable.

Comments

When a call has been picked up successfully the app is notified via the LINE_CALLSTATE message about call state changes. The LINECALLINFO structure supplies information about the call that was picked up. It will list the reason for the call as pickup. This structure is available via lineGetCallInfo.

See Also

Functions: lineGetCallInfo, lineGetCallStatus

Messages: LINE_CALLSTATE

Structures: LINECALLINFO, LINECALLSTATUS


linePrepareAddToConference

Syntax

LONG linePrepareAddToConference(hConfCall, lphAddCall, lpCallParams)
This function prepares an existing conference call for the addition of another party.

Parameters

HCALL hConfCall
Specifies a handle to a conference call. The app must be an owner of this call.

LPHCALL lphAddCall
Specifies a far pointer to an HCALL handle. This location is then loaded with a handle identifying the consultation call to be added. Initially, the app will be the sole owner for this call.

LPLINECALLPARAMS const lpCallParams
Specifies a far pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCONFCALLHANDLE
The specified call handle for the conference call is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified conference call.
LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
LINEERR_INVALCALLSTATE
The conference call is not in a valid state for the requested operation.
LINEERR_CALLUNAVAIL
All call appearances on the specified address are currently allocated.
LINEERR_CONFERENCEFULL
The maximum number of parties for a conference has been reached.
LINEERR_INVALCALLPARAMS
The specified call parameters are invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hConfCall connected hAddCall Not applicable

Comments

A conference call handle can be obtained via lineSetupConference or via lineCompleteTransfer that is resolved as a three-way conference call. The function linePrepareAddToConference typically places the existing conference call in the onHoldPendingConference state and creates a consultation call that can be added later to the existing conference call via lineAddToConference.

The consultation call can be canceled using lineDrop. It may also be possible for an application to swap between the consultation call and the held conference call via lineSwapHold.

See Also

Functions: lineDial, lineSwapHold, lineSetupConference,

lineAddToConference, lineRemoveFromConference

Messages: LINE_CALLSTATE


lineRedirect

Syntax

LONG lineRedirect(hCall, lpszDestAddress, dwCountryCode)
This function redirects the specified offering call to the specified destination address.

Parameters

HCALL hCall
Specifies a handle to the call to be redirected. The app must be an owner of the call.

LPCSTR const lpszDestAddress
Specifies a far pointer to the destination address. This follows the standard dialable number format.

DWORD dwCountryCode
Specifies the country code of the party the call is redirected to. If a value of zero is specified, then a default will be used by the implementation.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALCALLSTATE
The call is not in a valid state for the requested operation.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_INVALADDRESS
The specified character buffer for the destination address contains invalid characters or digits (i.e., syntax error); the call has not been redirected.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall offering

Comments

Call redirection allows an application to deflect an offering call to another address without first answering the call. Call redirect differs from call forwarding in that call forwarding is performed by the switch without the involvement of the application; redirection can be done on a call by call basis by the application, for example driven by caller ID information. It differs from call transfer in that transferring a call requires the call first be answered.

After a call has been successfully redirected, the call will typically transition to idle.

Besides redirecting an incoming call, an application may have the option to accept the call using lineAccept, reject the call via lineDrop, or answer the call using lineAnswer. The availability of these operations is dependent on device capabilities.

See Also

Functions: lineAccept, lineDrop, lineGetDevCaps

Messages: LINE_CALLSTATE


lineRegisterRequestRecipient

Syntax

LONG lineRegisterRequestRecipient(hApp, dwRegistrationInstance, dwRequestMode, bEnable)
This function registers the invoking application as a recipient of requests for the specified request mode.

Parameters

HLINEAPP hApp
Specifies the application's usage handle for the line portion of the API.

DWORD dwRegistrationInstance
Specifies an app-specific DWORD that is passed back as a parameter of the LINE_REQUEST message. This message notifies the application that a request is pending.

DWORD dwRequestMode
Specifies the type(s) of request for which the application registers, of type LINEREQUESTMODE. Values are:

LINEREQUESTMODE_MAKECALL
A tapiRequestMakeCall request.
LINEREQUESTMODE_MEDIACALL
A tapiRequestMediaCall/tapiRequestDrop request.
LINEREQUESTMODE_LOGENTRY
A lineRequestLogEntry request.
BOOL bEnable
If TRUE, the application registers; if FALSE, the app deregisters for the specified request modes.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALAPPHANDLE
The specified application handle is invalid.
LINEERR_INVALREQUESTMODE
The specified request mode is invalid.
LINEERR_OPERATIONFAILED
The specified operation failed for unknown reasons.

Call States

Not applicable.

Comments

An telephony-enabled application can request that a call be placed on its behalf by invoking tapiRequestMakeCall, tapiRequestMediaCall, and drop a media call via tapiRequestDrop. Additionally, other applications can request information be logged with a given call. These requests are queued by the Telephony DLL and the (highest priority) application that has registered to handle the request is sent a LINE_REQUEST message with indication of the mode of the request that is pending. This application will typically be the user's call control application. Next, the call control application that receives this message invokes lineGetRequest specifying the request mode and a buffer that is large enough to hold the request. The call control application then interprets and executes the request. For media mode handling, the serving application may need to send Windows messages back to the original application that made the request. The TAPI_REPLY message is used for this purpose.

The recipient app is also automatically deregistered for all requests when it does a lineShutdown.

See Also

Functions: lineGetRequest

Messages: LINE_REQUEST


lineRemoveFromConference

Syntax

LONG lineRemoveFromConference(hCall)
This function removes the specified call from the conference call to which it currently belongs. The remaining calls in the conference call are unaffected.

Parameters

HCALL hCall
Specifies a handle to the call to be removed from the conference. The app must be an owner of this call.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALCALLSTATE
The call is not in a valid state for the requested operation.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall conferenced

Comments

This operation removes a party that currently belongs to a conference call. After the call has been successfully removed, it may be possible to further manipulate it using its handle. The availability of this operation and its result are likely to be limited in many implementations. For example, in many implementations, only the most recently added party may be removed from a conference, and the removed call may be automatically dropped (becomes idle). Consult the line's device capabilities to determine the available effects of removing a call from a conference.

See Also

Functions: lineSetupConference, lineAddToConference, lineGetDevCaps

Messages: LINE_CALLSTATE

Data Types: LINEDEVCAPS


lineRequestLogEntry

Syntax

LONG lineRequestLogEntry(hCall, lpsComment, dwSize)
This function requests that a comment be added to the call log for the given call.

Parameters

HCALL hCall
Specifies a handle to the call for which information logging is requested.

LPCSTR const lpsComment
Specifies a far pointer to a comment string. The string uses the format specified as the dwStringFormat field in the call's line device capabilities. If the string is longer than LINEMAXCOMMENTSIZE, then the given string is truncated.

DWORD dwSize
Specifies the size of the comment string in bytes.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall
Any state

Comments

None.

See Also

Functions: lineGetRequest

Messages: LINE_REQUEST


lineSecureCall

Syntax

LONG lineSecureCall(hCall)
This function secures the call from any interruptions or interference that may affect the call's media stream.

Parameters

HCALL hCall
Specifies a handle to the call to be secured. The app must be an owner of the call.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall Any state

Comments

A call can be secured to avoid interference. For example, in an analog environment, call waiting tones may destroy a fax or modem session on the original call. LineSecureCall allows an existing call to be secured, lineMakeCall provides the option to secure the call from the time of call setup. The securing of a call remains in effect for the duration of the call.

See Also

Functions: lineMakeCall


lineSendUserUserInfo

Syntax

LONG lineSendUserUserInfo(hCall, lpsUserUserInfo, dwSize)
This function send user-to-user information to the remote party on the specified call.

Parameters

HCALL hCall
Specifies a handle to the call on which to send user-to-user information. The app must be an owner of the call.

LPCSTR const lpsUserUserInfo
Specifies a far pointer to a string containing user-to-user information to be sent to the remote party. User-to-user information is only sent if supported by the underlying network (see LINEDEVCAPS).

DWORD dwSize
Specifies the size in bytes of the user-to-user information in lpsUserUserInfo.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALCALLSTATE
The call is not in a valid state for the requested operation.
LINEERR_INVALPOINTER
The specified pointer parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall connected

Comments

This function can be used to send user-to-user information at any time during a connected call. If the size of the specified information to be sent is larger than what may fit into a single network message (e.g., ISDN), then the service provider is responsible for breaking the information up into a sequence of chained network messages (using "more data").

User-to-user information can also be sent as part of call accept, call reject, call redirect, and when making calls. User-to-user information can also be received. The received information is available via the call's call information record. Whenever user-to-user information arrives after call offering or prior to call disconnect, a LINE_CALLINFO message with a UserUserInfo parameter will notify the app that user-to-user information in the call information record has changed. If multiple network messages are chained, then the information is assembled by the service provider and a single message is sent to the app.

See Also

Functions: lineMakeCall, lineAccept, lineRedirect, lineDrop, lineGetCallInfo

Messages: LINE_CALLINFO

Data Types: LINECALLINFO


lineSetAppSpecific

Syntax

LONG lineSetAppSpecific(hCall, dwAppSpecific)
This operation enables an application to set the application specific field of the specified call's call information record.

Parameters

HCALL hCall
Specifies a handle to the call whose application specific field needs to be set. The app must be an owner of the call.

DWORD dwAppSpecific
Specifies the new content of the dwAppSpecific field for the call's LINECALLINFO structure. This value is uninterpreted by the Telephony API.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall Any state

Comments

The app specific field in the LINECALLINFO data structure that exists for each call is uninterpreted by the Telephony API or any of its service providers. Its usage is entirely defined by the applications. The field can be read from the LINECALLINFO record returned by lineGetCallInfo. However, lineSetAppSpecific must be used to set the field so that changes become visible to other apps. When this field is changed, all other apps with call handles are sent a LINE_CALLINFO message with an indication that the AppSpecific field has changed.

See Also

Functions: lineGetCallInfo

Messages: LINE_CALLINFO

Data Types: LINECALLINFO


lineSetCallParams

Syntax

LONG lineSetCallParams(hCall, dwBearerMode, dwMinRate, dwMaxRate, lpDialParams)
This function allows an application to change bearer mode and/or the rate parameters of an existing call.

Parameters

HCALL hCall
Specifies a handle to the call whose parameters are to be changed. The app must be an owner of the call.

DWORD dwBearerMode
Specifies the new bearer mode for the call, of type LINEBEARERMODE. Values are:

LINEBEARERMODE_VOICE
This is a regular 3.1kHz analog voice grade bearer service. Bit integrity is not assured. Voice can support fax and modem media modes.
LINEBEARERMODE_SPEECH
This corresponds to G.711 speech transmission on the call. The network may use processing techniques such as analog transmission, echo cancellation and compression/decompression. Bit integrity is not assured. Speech is not intended to support fax and modem media modes.
LINEBEARERMODE_MULTIUSE
The multi-use mode defined by ISDN.
LINEBEARERMODE_DATA
The unrestricted data transfer on the call. The data rate is specified separately.
LINEBEARERMODE_ALTSPEECHDATA
The alternate transfer of speech or unrestricted data on the same call (ISDN).
LINEBEARERMODE_NONCALLSIGNALING
This corresponds to a non call-associated signaling connection from the app to the service provider or switch (treated as a "media stream" by the Telephony API).
DWORD dwMinRate
Specifies a lower bound for the call's new data rate. The app is willing to accept a new rate as low as this one.
DWORD dwMaxRate
Specifies an upper bound for the call's new data rate. This is the maximum data rate the application would like. If an exact data rate is required, then dwMinRate and dwMaxRate should be specified as equal.
LPLINEDIALPARAMS lpDialParams
Specifies a far pointer to the new dial parameters for the call, of type LINEDIALPARAMS. This parameter can be left NULL if the call's current dialing parameters are to be used.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
he specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALBEARERMODE
The specified bearer mode is invalid.
LINEERR_INVALRATE
The specified bearer mode is invalid.
LINEERR_BEARERMODEUNAVAIL
The call's bearer mode cannot be changed to the specified bearer mode.
LINEERR_RATEUNAVAIL
he service provider does currently not have enough bandwidth available for the specified rate.
LINEERR_RESOURCEUNAVAIL
The service provider does not have enough resources available to complete the request.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

Any state

Comments

This operation is used to change the parameters of an existing call. Examples of its usage include changing the bearer mode and/or the data rate of an existing call.

See Also

Functions: lineMakeCall

Messages: LINECALLPARAMS


lineSetMediaControl

Syntax

LONG lineSetMediaControl(hLine, dwAddressID, hCall, dwSelect, lpDigitList, dwDigitNumEntries, lpMediaList, dwMediaNumEntries, lpToneList, dwToneNumEntries, lpCallStateList, dwCallStateNumEntries)
This function enables and disables control actions on the media stream associated with the specified line, address, or call. Media control actions can be triggered by the detection of specified digits, media modes, custom tones, and call states.

Parameters

HLINE hLine
Specifies a handle to an open line device.

DWORD dwAddressID
Specifies an address on the given open line device.

HCALL hCall
Specifies a handle to a call. The application must be an owner of the call.

DWORD dwSelect
Specifies the whether media control is requested is associated with a single call, is the default for all calls on an address, or is the default for all calls on a line. This field is of type LINECALLSELECT. Values are:

LINECALLSELECT_LINE
Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.
LINECALLSELECT_ADDRESS
Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.
LINECALLSELECT_CALL
Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.
LPLINEMEDIACONTROLDIGIT const lpDigitList
Specifies a far pointer to the array that contains the digits that are to trigger media control actions, of type LINEMEDIACONTROLDIGIT. Each time a digit listed in the digit list is detected, the specified media control action is carried out on the call's media stream.

Valid digits for pulse mode are '0' through '9'. Valid digits for DTMF mode are '0' through '9', 'A', 'B', 'C', 'D', '*', '#'.

DWORD dwDigitNumEntries
Specifies the number of entries in the lpDigitList.

LPLINEMEDIACONTROLMEDIA const lpMediaList
Specifies a far pointer to an array with entries of type LINEMEDIACONTROLMEDIA. The array has dwMediaNumEntries entries. Each entry contains a media mode to be monitored, media type specific information (e.g., duration), and a media control field. If a media mode in the list is detected, then the corresponding media control action is performed on the call's media stream.

DWORD dwMediaNumEntries
Specifies the number of entries in lpMediaList.

LPLINEMEDIACONTROLTONE const lpToneList
Specifies a far pointer to an array with entries of type LINEMEDIACONTROLTONE. The array has dwToneNumEntries entries. Each entry contains a description of a tone to be monitored, duration of the tone, and a media control field. If a tone in the list is detected, then the corresponding media control action is performed on the call's media stream.

DWORD dwToneNumEntries
Specifies the number of entries in lpToneList.

LPLINEMEDIACONTROLCALLSTATE const lpCallStateList
Specifies a far pointer to an array with entries are of type LINEMEDIACONTROLSTATE. The array has dwCallStateNumEntries entries. Each entry contains a call state and a media control action. Whenever the given call transitions into one of the call states in the list, the corresponding media control action is invoked. A media control value of LINEMEDIACONTROL_NONE should be specified to cancel the media control of a call state.

DWORD dwCallStateNumEntries
Specifies the number of entries in lpCallStateList.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.
LINEERR_INVALADDRESSID
The specified address ID is invalid.
LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.
LINEERR_INVALCALLSELECT
The specified select parameter is invalid.
LINEERR_INVALDIGITLIST
The specified digit list is invalid.
LINEERR_INVALMEDIALIST
The specified media list is invalid.
LINEERR_INVALTONELIST
The specified tone list is invalid.
LINEERR_INVALCALLSTATELIST
The specified call state list is invalid.
LINEERR_RESOURCEUNAVAIL
The service provider does not have enough resources available to complete the request.
LINEERR_OPERATIONUNAVAIL
The operation is not available.
LINEERR_OPERATIONFAILED
The operation failed for unspecified reasons.

hCall Any state

This function is considered successful if media control has been correctly initiated; not when any media control has taken effect. Media control in progress is changed or is canceled by calling this function again with either different parameters or NULLs.
All apps that are owners of the call are in principle allowed to make media control requests on the call. Only a single media control request can be outstanding on a call across all applications that own the call. So the last application to make its request wins.
Depending on the service provider and other activities that compete for such resources, the amount of simultaneous detections that can be made may vary over time. If service provider resources are overcommitted, the LINEERR_RESOURCEUNAVAIL error is returned.
Whether or not media control is supported by the service provider is a device capability.

Functions: lineGetDevCaps

Data Types: LINECAPS, LINEDIGITMODE, LINEMEDIAMODE, LINEMEDIACONTROLMODE, LINEMEDIACONTROLCALLSTATE, LINEMEDIACONTROLDIGIT, LINEMEDIACONTROLMEDIA, LINEMEDIACONTROLTONE

Call States

Comments

See Also


lineSetMediaMode

Syntax

LONG lineSetMediaMode(hCall, dwMediaModes)
This function is sets the media mode(s) of the specified call in its LINECALLINFO structure.

Parameters

HCALL hCall
Specifies a handle to the call whose media mode is to be changed. The app must be an owner of the call.

DWORD dwMediaModes
Specifies the new media mode(s) for the call, of type LINEMEDIAMODE. As long as the UNKNOWN media mode flag is set, multiple other media mode flags may be set as well. This is used to indentify a call's media mode as not fully determined, but narrowed down to one of just a small set of specified media modes. If the UNKNOWN flag is not set, then only a single media mode can be specified. Values are:

LINEMEDIAMODE_NONE
This is used as a NULL value for the data type. This value may be used when the media stream of the call is not accessible by the application.
LINEMEDIAMODE_UNKNOWN
The target app is the one that handles calls of unknown media mode; i.e., unclassified calls.
LINEMEDIAMODE_INTERACTIVEVOICE
The target app is the one that handles calls with the interactive voice media mode; i.e., live conversations.
LINEMEDIAMODE_AUTOMATEDVOICE
The presence of voice energy on the call and the voice is locally handled by an automated application.
LINEMEDIAMODE_DIGITALDATA
The target app is the one that handles calls that are digital data calls.
LINEMEDIAMODE_G3FAX
The target app is the one that handles calls with the group 3 fax media mode.
LINEMEDIAMODE_G4FAX
The target app is the one that handles calls with the group 4 fax media mode.
LINEMEDIAMODE_DATAMODEM
The target app is the one that handles calls with the data modem media mode.
LINEMEDIAMODE_TELETEX
The target app is the one that handles calls with the teletex media mode.
LINEMEDIAMODE_VIDEOTEX
The target app is the one that handles calls with the videotex media mode.
LINEMEDIAMODE_TELEX
The target app is the one that handles calls with the telex media mode.
LINEMEDIAMODE_MIXED
The target app is the one that handles calls with the ISDN mixed media mode.
LINEMEDIAMODE_TDD
The target app is the one that handles calls with the TDD (Telephony Devices for the Deaf) media mode.
LINEMEDIAMODE_ADSI
The target app is the one that handles calls with the ADSI (Analog Display Services Interface) media mode.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.
LINEERR_INVALMEDIAMODE
The specified media mode parameter is invalid.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.
LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

hCall Any state

Comments

This function changes the call's media mode in its LINECALLINFO structure. Typical usage of this operation is to either set a call's media mode to a specific known media mode, or to exclude possible media modes as long as the call's media mode is officially unknown; i.e., the UNKNOWN media mode flag is set.

See Also

Functions: lineGetCallInfo


lineSetNumRings

Syntax

LONG lineSetNumRings(hLine, dwAddressID, dwNumRings)
This function is used by an app to set the number of rings it wants an incoming call to ring prior to answering the call. This function can be used to implement a toll saver-style function. It allows multiple independent apps to each register the number of rings. The function lineGetNumRings returns the minimum number of all number of rings requested. It can be used by the app that answers inbound calls to determine the number of rings it should wait before answering the call.

Parameters

HLINE hLine
Specifies a handle to the open line device.

DWORD dwAddressID
Specifies an address on the line device.

DWORD dwNumRings
Specifies the number of rings before a call should be answered in order to honor the toll saver requests from all apps.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified device handle is invalid.
LINEERR_INVALADDRESSID
The specified address ID is out of range.
LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

Call States

Not applicable.

Comments

lineGetNumRings and lineSetNumRings when used in combination provide a mechanism to support the implementation of toll saver features across multiple independent applications. If no application ever calls lineSetNumRings, then lineGetNumRings will return 0xFFFFFFFF.

An application that is the owner for a call in the offering state and that received a LINE_LINEDEVSTATE ringing message should wait a number of rings equal to the number returned by lineGetNumRings before answering the call in order to honor the toll saver settings across all applications. A separate LINE_LINEDEVSTATE ringing message is sent to the application for each ring cycle, so the app should count these messages. If this call disconnects before being answered, and another call comes in shortly thereafter, then the LINE_CALLSTATE message should allow the app to determine that ringing is related to the second call.

If call classification is performed by the API implementation by means of answering inbound calls of unknown media mode and filtering the media stream, then the API implementation will honor this number as well.

Note that this operation is purely informational and does not in itself affect the state of any calls on the line device.

See Also

Functions: lineGetNumRings


lineSetStatusMessages

Syntax

LONG lineSetStatusMessages(hLine, dwLineStates, dwAddressStates)
This operation enables an application to specify which notification messages the app wants to receive for events related to status changes for the specified line or any of its addresses.

Parameters

HLINE hLine
Specifies a handle to the line device.

DWORD dwLineStates
Specifies a bit array that identifies for which line device status changes a message is to be sent to the application, of type LINEDEVSTATE. Values are:

LINEDEVSTATE_OTHER
An other device status item has changed.

LINEDEVSTATE_RINGING
The switch tells the line to alert the user.

LINEDEVSTATE_CONNECTED
The line was previously disconnected and is now connected to the API.

LINEDEVSTATE_DISCONNECTED
This line was previously connected and is now disconnected from the API.

LINEDEVSTATE_MSGWAITON
The message waiting indicator is turned on.

LINEDEVSTATE_MSGWAITOFF
The message waiting indicator is turned off.

LINEDEVSTATE_INSERVICE
The line is connected to the API. This happens when the API is first activated, or when the line wire is physically plugged in and in service at the switch while the API is active.

LINEDEVSTATE_OUTOFSERVICE
The line is out of service at the switch or physically disconnected. The API cannot be used to operate on the line device.

LINEDEVSTATE_MAINTENANCE
Maintenance is being performed on the line at the switch. The API cannot be used to operate on the line device.

LINEDEVSTATE_OPEN
The line has been opened by some application.

LINEDEVSTATE_CLOSE
The line has been closed by some application.

LINEDEVSTATE_NUMCALLS
The number of calls on the line device has changed.

LINEDEVSTATE_TERMINALS
The terminal settings have changed.

LINEDEVSTATE_ROAMMODE
The roam mode of the line device has changed.

LINEDEVSTATE_BATTERY
The battery level has changed significantly (cellular).

LINEDEVSTATE_SIGNAL
The signal level has changed significantly (cellular).

LINEDEVSTATE_DEVSPECIFIC
The line's device specific information has changed.

LINEDEVSTATE_REINIT
Items have changed in the configuration of line devices. To become aware of these changes (e.g., new line devices) the app should reinitialize its use of the API. New lineInitialize and lineOpen requests will be denied until apps have shut down their usage of the API. The hDevice parameter is left NULL for this state change as it applies to any of the lines in the system.

LINEDEVSTATE_LOCK
The locked status of the line device has changed.

DWORD dwAddressStates
Specifies a bit array that identifies for which address status changes a message is to be sent to the application, of type LINEADDRESSSTATE. Values are:

LINEADDRESSSTATE_OTHER
An other address status item than those listed below has changed.

LINEADDRESSSTATE_DEVSPECIFIC
The device specific item of the address status has changed.

LINEADDRESSSTATE_INUSEZERO
The address has changed to idle; i.e., it is now in use by zero stations.

LINEADDRESSSTATE_INUSEONE
The address has changed from being idle or from being in use by many bridged stations to being in use by just one station.

LINEADDRESSSTATE_INUSEMANY
The monitored or bridged address has changed to being in use by one station to being used by more than one station.

LINEADDRESSSTATE_NUMCALLS
The number of calls on the address has changed. This is the result of either a new inbound call, or an outbound call on the address, a call changing its hold status, etc.

LINEADDRESSSTATE_FORWARD
The forwarding status of the address has changed including the number of rings for determining a no answer condition. The app should check the address status to determine details about the address' current forwarding status.

LINEADDRESSSTATE_TERMINALS
The terminal settings for the address have changed.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.

LINEERR_INVALPARAM
One or both of the states parameters is invalid.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

Not applicable.

Comments

The API defines a number of messages that notify applications about events occurring on lines and addresses. An app may not be interested in receiving all address and line status change messages. lineSetStatusMessages can be used to select which messages the app wants to receive. By default, address and line status reporting is disabled.

See Also

Functions: lineGetStatusMessages

Messages: LINE_LINEDEVSTATE, LINE_ADDRESSSTATE

Data Types: LINEDEVSTATE, LINEADDRESSSTATE


lineSetTerminal

Syntax

LONG lineSetTerminal(hLine, dwAddressID, hCall, dwSelect, dwTerminalModes, dwTerminalID, bEnable)
This operation enables an application to specify to which terminal information related the specified line, address or call is to be routed. This operation can be used while calls are in progress on the line, to allow an application to route these events to different devices as required.

Parameters

HLINE hLine
Specifies a handle to an open line device.

DWORD dwAddressID
Specifies an address on the given open line device.

HCALL hCall
Specifies a handle to a call.

DWORD dwSelect
Specifies whether the terminal setting is requested for the line, the address or just the specified call. If line or address is specified, then events either apply to the line or address itself or serves as a default initial setting for all new calls on the line or address. This parameter is of type LINECALLSELECT. Values are:

LINECALLSELECT_LINE
Selects the specified line device. The hLine parameter must be a valid line handle; hCall and dwAddressID are ignored.

LINECALLSELECT_ADDRESS
Selects the specified address on the line. Both hLine and dwAddressID must be valid; hCall is ignored.

LINECALLSELECT_CALL
Selects the specified call. hCall must be valid; hLine and dwAddressID are both ignored.

DWORD dwTerminalModes
Specifies the class(es) of low level events to be routed to the given terminal.

LINETERMMODE_BUTTONS
The button presses from the terminal to the line.

LINETERMMODE_DISPLAY
The display events from the line to the terminal.

LINETERMMODE_LAMPS
The lamp lighting events from the line to the terminal.

LINETERMMODE_RINGER
The ring requests from the line to the terminal.

LINETERMMODE_HOOKSWITCH
The hookswitch events between the terminal and the line.

LINETERMMODE_MEDIAFROMTERM
This is the unidirectional media stream from the terminal to the line associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIATOTERM
This is the unidirectional media stream from the line to the terminal associated with a call on the line. Use this value when routing of both unidirectional channels of a call's media stream can be controlled independently.

LINETERMMODE_MEDIABIDIR
This is the bidirectional media stream associated with a call on the line and the terminal. Use this value when routing of both unidirectional channels of a call's media stream cannot be controlled independently.

DWORD dwTerminalID
Specifies the device ID of the terminal device where the given events are to be routed. Terminal IDs are small integers in the range of 0 to dwNumTerminals -1, where dwNumTerminals, and the terminal modes each terminal is capable of handling, are returned by lineGetDevCaps. Note that these terminal IDs have no relation to other device IDs and are defined by the service provider via device capabilities.

BOOL bEnable
If TRUE, dwTerminalID is valid and the specified event classes are routed to or from that terminal. If FALSE, these events are not routed to or from the dwTerminalID.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.

LINEERR_INVALADDRESSID
The specified address ID is invalid.

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.

LINEERR_INVALCALLSELECT
The specified select parameter is invalid.

LINEERR_INVALTERMINALMODE
The specified terminal modes parameter is invalid.

LINEERR_INVALTERMINALID
The specified terminal mode parameter is invalid.

LINEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available for the given device.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall Any state

Comments

An application can use this operation to route certain classes of low level line events to the specified terminal device, or to suppress the routing of these events altogether. For example, voice may be routed to a separate audio I/O device (headset), lamps and display events may be routed to the local phone device, and button events and ringer events may be suppressed altogether.

This operation can be called any time, even when a call is active on the given line device. This, for example, allows a user to switch from using the local phone set to another audio I/O device.

This function may be called multiple times to possibly route the same events to multiple terminals simultaneously. To reroute event to a different terminal, it is recommended that the app first disable routing to the existing terminal and next route the events to the new terminal.

Terminal ID assignments are made by the line's service provider. Device capabilities only indicate which terminal IDs the service provider has available. Service providers that don't support this type of event routing would indicate that they have no terminal devices (dwNumTerminals in LINEDEVCAPS is zero).

See Also

Data Types: LINETERMMODE, LINECALLSELECT


lineSetupConference

Syntax

LONG lineSetupConference(hCall, hLine, lphConfCall, lphAddCall, dwNumParties, lpCallParams)
This function sets up a conference call for the addition of the third party.

Parameters

HCALL hCall
Specifies the initial call that identifies the first party of a conference call. In some environments (as described in device capabilities), a call must exist in order to start a conference call, and the app must be an owner of this call. In other telephony environments, no call initially exists, hCall must be left NULL and hLine must be specified to identify the line on which the conference call is to be initiated.

HLINE hLine
Specifies a handle to the line. This handle is used to identify the line device on which to originate the conference call if hCall is NULL. The hLine parameter is ignored if hCall is non-NULL.

LPHCALL lphConfCall
Specifies a far pointer to an HCALL handle. This location is then loaded with a handle identifying the newly created conference call. The app will be the initial sole owner of this call.

LPHCALL lphAddCall
Specifies a far pointer to an HCALL handle. When setting up a call for the addition of a new party, a new temporary call (consultation call) is automatically allocated. Initially, the app will be the sole owner for this call.

DWORD dwNumParties
Specifies the expected number of parties in the conference call. This number is passed on to the service provider. The service provider is free to do with this number as it pleases; ignore it, use it a hint to allocate the right size conference bridge inside the switch, etc.

LPLINECALLPARAMS const lpCallParams
Specifies a far pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle for the conference call is invalid.

LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.

LINEERR_INVALCALLSTATE
The call is not in a valid state for the requested operation.

LINEERR_CALLUNAVAIL
All call appearances on the specified address are currently allocated.

LINEERR_CONFERENCEFULL
The requested number of parties cannot be satisfied.

LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.

LINEERR_INVALCALLPARAMS
The specified call parameters are invalid.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall connected
hConfCall Not applicable
hAddCall Not applicable

Comments

LineSetupConference provides two ways for establishing a new conference call, depending on whether a normal two-party call is required to pre-exist or not. When setting up a conference call from an existing two-party call, the hCall parameter is a valid call handle that is initially added to the conference call by the lineSetupConference request; hLine is ignored. On switches where conference call setup does not start with an existing call, hCall must be NULL and hLine must be specified to identify the line device on which to initiate the conference call. In either case, a consultation call is allocated for connecting to the party that is to be added to the call. The app can then use lineDial to dial the address of the other party.

The conference call will typically transition into the onHoldPendingConference state, the consultation call dialtone state and the initial call (if one) into the conferenced state.

A conference call can also be set up via a lineCompleteTransfer that is resolved into a three-way conference.

The app may be able to toggle between the consultation call and the conference call by using lineSwapHold.

See Also

Functions: lineDial, lineSwapHold, linePrepareAddToConference, lineAddToConference, lineRemoveFromConference

Messages: LINE_CALLSTATE


lineSetupTransfer

Syntax

LONG lineSetupTransfer(hCall, lphConsultCall, lpCallParams)
This function initiates a transfer of the call specified by hCall. It establishes a consultation call, lphConsultCall, on which the party can be dialed that can become the destination of the transfer.

Parameters

HCALL hCall
Specifies the handle of the call to be transferred. The app must be an owner of the call.

LPHCALL lphConsultCall
Specifies a far pointer to an HCALL handle. This location is then loaded with a handle identifying the temporary consultation call. When setting a call up for transfer, another call (a consultation call) is automatically allocated to enable the application to dial the address (using lineDial) of the party to where the call is to be transferred. The originating party can carry on a conversation over this consultation call prior to completing the transfer.
This transfer procedure may not be valid for some line devices. The application may need to ignore the new consultation call and unhold an existing held call (using lineUnhold) to identify the destination of the transfer. On switches that support cross-address call transfer, the consultation call may exist on a different address than the call to be transferred. It may also be necessary that the consultation call be set up as an entirely new call, via lineMakeCall, to the destination of the transfer. Which forms of transfer as available are specified in the call's address capabilities.

LPLINECALLPARAMS const lpCallParams
Specifies a far pointer to call parameters to be used when establishing the consultation call. This parameter may be set to NULL if no special call setup parameters are desired.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.

LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.

LINEERR_INVALCALLSTATE
The call to be transferred is not in a valid state.

LINEERR_CALLUNAVAIL
All call appearances on the specified address are currently allocated.

LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.

LINEERR_INVALCALLPARAMS
The specified call parameters are invalid.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall connected, onHoldPendingTransfer, onHold

hConsultCall Not applicable

Comments

This operation sets up the transfer of the call specified by hCall. The setup phase of a transfer establishes a consultation call that enables the application to send the address of the destination (the party to be transferred to) to the switch, while the call to be transferred is kept on hold. This new call is referred to as a consultation call (hConsultCall) and can be manipulated independently of the original call (e.g., dropped, etc.).

When the consultation call has reached the dialtone call state, the application may proceed transferring the call either by dialing the destination address and tracking its progress, or by unholding an existing call. The transfer of the original call to the selected destination is completed using lineCompleteTransfer.

While the consultation call exists, the original call will typically transition to the onholdPendingTransfer state. The app may be able to toggle between the consultation call and the original call by using lineSwapHold.

The app may also transfer calls in a single step, without having to deal with the intervening consultation call by using lineBlindTransfer.

See Also

Functions: lineDial, lineCompleteTransfer, lineBlindTransfer, lineSwapHold

Messages: LINE_CALLSTATE


lineShutdown

Syntax

LONG lineShutdown(hApp)
This function shuts down the application's usage of the line abstraction of API.

Parameters

HLINEAPP hApp
Specifies the app's usage handle for the line API.

Return Value

Returns zero if the function is successful or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALAPPHANDLE
The app's specified usage handle is invalid.

Comments

If this function is called when the application has lines open or calls active, then the call handles will be deleted and open lines closed.

See Also

Functions: lineInitialize


lineSwapHold

Syntax

LONG lineSwapHold(hActiveCall, hConsultCall)
This function swaps the specified active call with the specified call on consultation hold.

Parameters

HCALL hActiveCall
Specifies the handle to the active call. The app must be an owner of the call.

HCALL hConsultCall
Specifies the handle to the consultation call. The app must be an owner of the call.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
One or both of the specified call handles are invalid.

LINEERR_NOTOWNER
The app does not have owner privileges to the specified calls.

LINEERR_INVALCALLSTATE
The call states of the calls are invalid.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hConsultCall onHoldPendingTransfer, onHoldPendingConference, onHold

hActiveCall connected

Comments

Swapping the active call with the call on consultation hold allows the application to alternate or toggle between these two calls. One example where this is typical behavior is in call waiting.

See Also

Functions: lineSetupTransfer, lineSetupConference


lineTranslateAddress

This function is being expanded to accommodate alternative call methods.

Syntax

LONG lineTranslateAddress(hLine, lpszAddressIn, lpAddressOut, lpdwCountryCode)
This function is used to translate between an address in canonical format and its dialable address and country code equivalent.

Parameters

HLINE hLine
Specifies a handle to the line device to which the translation is to apply.

LPCSTR const lpszAddressIn
Specifies a far pointer to a NULL terminated string containing the address that is to be translated.

LPVARSTRING lpAddressOut
Specifies a far pointer to a structure of type VARSTRING. This structure is used to return the address that is the result of the translation.

LPDWORD lpdwCountryCode
Specifies a far pointer to a DWORD-sized location. This location is loaded with the country code of the translated address.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The handle for the specified line device is invalid.

LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.

LINEERR_INVALADDRESS
The specified address is invalid.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

Not applicable.

Comments

None.

See Also

Functions: lineMakeCall, lineDial, lineRedirect


lineUncompleteCall

Syntax

LONG lineUncompleteCall(hline, dwCompletionID)
This function is used to cancel the specified call competion request on the specified line.

Parameters

HLINE hLine
Specifies a handle to the line device on which a call completion is to be canceled.

DWORD dwCompletionID
Specifies the completion ID for the request that is to be canceled.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified line handle is invalid.

LINEERR_INVALCOMPLETIONID
The completion ID is invalid.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

Not applicable.

Comments

None.

See Also

Functions: lineCompleteCall


lineUnhold

Syntax

LONG lineUnhold(hCall)
This function retrieves the specified held call.

Parameters

HCALL hCall
Specifies the handle to the call to be retrieved.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALCALLHANDLE
The specified call handle is invalid.

LINEERR_NOTOWNER
The app does not have owner privileges to the specified call.

LINEERR_INVALCALLSTATE
The call is not currently on hold.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

hCall onHold

Comments

This operation works only for calls on hard hold, i.e., call placed on hold using lineHold.

See Also

Functions: lineHold


lineUnpark

Syntax

LONG lineUnpark(hLine, dwAddressID, lphCall, lpszDestAddress)
This function retrieves the call parked at the specified address and returns a call handle for it.

Parameters

HLINE hLine
Specifies a handle to the open line device on which a call is to unparked.

DWORD dwAddressID
Specifies the address on hLine at which the unpark is to be originated.

LPHCALL lphCall
Specifies a far pointer to the location of type HCALL where the handle to the unparked call is returned. The app will be the initial sole owner of this call.

LPCSTR const lpszDestAddress
Specifies a far pointer to a NULL terminated character buffer that contains the address where the call is parked. The address is in standard dialable address format.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

LINEERR_INVALLINEHANDLE
The specified call handle is invalid.

LINEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.

LINEERR_INVALADDRESSID
The specified address ID is invalid.

LINEERR_INVALADDRESS
The specified address is invalid.

LINEERR_NOMEM
Unable to allocate or lock memory.

LINEERR_OPERATIONUNAVAIL
The specified operation is not available.

LINEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Call States

Not applicable.

Comments

None.

See Also

Functions: lineHold


phoneClose

Syntax

LONG phoneClose(hPhone)
This function closes the specified open phone device.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device to be closed. If the function is successful, then the handle is no longer valid.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.

Comments

After the open phone device has been successfully closed, the implementation sends a PHONE_CLOSE message to the application. Note that these messages can also be sent unsolicited as a result the phone device being reclaimed somehow. An application should therefore be prepared to handle these unsolicited close messages.

See Also

Messages: PHONE_CLOSE


phoneDevSpecific

Syntax

LONG phoneDevSpecific(hPhone, lpParams, dwSize)
This function is used as a general extension mechanism to enable a Telephony API implementation to provide features not described in the other operations. The meanings of these extensions are device specific.

Parameters

HPHONE hPhone
Specifies a handle to a phone device.
LPVOID lpParams
Specifies a far pointer to a memory area used to hold a parameter block. Its interpretation is device specific. The contents of the parameter block is passed unchanged to or from the service provider by the Telephony DLL.
DWORD dwSize
The size in bytes of the parameter block area.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns include:

PHONEERR_INVALPHONEHANDLE
The specified phone handle is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Additional error returns are device specific.

Comments

This operation provides a generic parameter profile. The interpretation of the parameter block is device specific. Indications and replies that are device specific should use the PHONE_DEVSPECIFIC message.

A service provider can provide access to device specific functions by defining parameters for use with this operation. Applications that want to make use of these device specific extensions should consult the device specific (i.e., vendor specific) documentation that describes what extentions are defined. Note that an app that relies on these device specific extensions will typically not be portable to work with other service provider environments.

See Also

Messages: PHONE_DEVSPECIFIC


phoneGetButtonInfo

Syntax

LONG phoneGetButtonInfo(hPhone, dwButtonLampID, lpButtonInfo)
This function returns information about the specified button.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device.
DWORD dwButtonLampID
Specifies a button on the phone device.
LPPHONEBUTTONINFO lpButtonInfo
Specifies a far pointer to a variable sized structure of type PHONEBUTTONINFO. This data structure describes the mode, the function, and provides additional descriptive text corresponding to the button.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALBUTTOMLAMPID
The specified button/lamp ID is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

None.

See Also

Functions: phoneSetButtonInfo
Data Types: PHONEBUTTONINFO, PHONECAPS


phoneGetData

Syntax

LONG phoneGetData(hPhone, dwDataID, lpData, dwSize)
This function uploads the information from the specified location in the open phone device to the specified buffer.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone.
DWORD dwDataID
Specifies where in the phone device the buffer is to be uploaded from.
LPVOID lpData
Specifies a far pointer to the memory buffer where the data is to be uploaded to.
DWORD dwSize
Specifies the size of the data buffer in bytes.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALDATAID
The specified data ID is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

The function uploads a maximum of dwSize bytes from the phone device into lpData. If dwSize is zero, nothing is copied. The size of each data area is listed in the phone's device capabilities.

See Also

Functions: phoneGetDevCaps, phoneSetData

Data Types: PHONECAPS


phoneGetDevCaps

Syntax

LONG phoneGetDevCaps(hApp, dwDeviceID, dwAPIVersion, dwLowVersion,

dwHighVersion, lpPhoneCaps)
This function queries the specified phone device to determine its telephony capabilities.

Parameters

HPHONEAPP hApp
Identifies a handle to the app's registration with the API.
DWORD dwDeviceID
Identifies the phone device to be queried.
DWORD dwAPIVersion
Specifies the negotiated API version number. This number is zero if the API version number has not yet been defined, and dwLowVersion and dwHighVersion specify the API version range the application can operate with. lpPhoneCaps will contain the selected API version number and the Extension ID that defines any available device specific extensions.

dwAPIVersion is non-zero if the API version number is known, and dwLowVersion and dwHighVersion specify the Extension version range of the device specific extensions (specific to the Extension ID) the app can operate with. lpPhoneCaps will contain the selected Extension version number.

DWORD dwLowVersion
If dwAPIVersion is zero, this field specifies the earliest Telephony API version the app is compliant with. The high order word is the major version number, the low order word is the minor version number.

If dwAPIVersion is non zero, this field specifies the earliest Extension version the app is compliant with (specific to the Extension ID returned in lpPhoneCaps). The high order word is the major version number, the low order word is the minor version number.

DWORD dwHighVersion
If dwAPIVersion is zero, this field specifies the latest Telephony API version the app is compliant with. The high order word is the major version number, the low order word is the minor version number.
If dwAPIVersion is non zero, this field specifies the latest Extension version the app is compliant with (specific to the Extension ID returned in lpPhoneCaps). The high order word is the major version number, the low order word is the minor version number.

LPPHONECAPS lpPhoneCaps
Specifies a far pointer to a variable sized PHONECAPS structure, which is then loaded with the returned information about the capabilities of the device.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALAPPHANDLE
The specified app registration handle is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_BADDEVICEID
The specified device ID is out of range.
PHONEERR_NODRIVER
The driver was not installed.
PHONEERR_INCOMPATIBLEVERSIONS
The app requested a version range that cannot supported by the Telephony API implementation and corresponding service provider version.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

Use phoneInitialize to determine the number of phone devices present in the system. The device ID specified by dwDeviceID varies from zero to one less than the number of phone devices present.

PhoneGetDevCaps is invoked either once or twice, depending on whether or not the application wants to use device specific extensions.

When called for the first time, the app specifies dwAPIVersion to zero and provides the API version range in dwLowVersion and dwHighVersion. lpPhoneCaps returns the selected API version number, and Extension ID, and the phone's device capabilities for the selected API version.

If the app wants to enable the extensions defined by the Extension ID, it call lineGetDevCaps again. The app specifies the selected API version as dwAPIVersion, and provides the Extension ID-compatible version range in dwLowVersion and dwHighVersion. In addition to the information returned previously, lpPhoneCaps also returns the selected Extension version number and any device specific device capabilities for this extension.

The API and Extension version numbers are those under which the API, Telephony DLL and service provider must operate. If version ranges do not overlap, then the app and API or service provider versions are incompatible and an error is returned.

See Also

Structure: PHONECAPS


phoneGetDisplay

Syntax

LONG phoneGetDisplay(hPhone, lpDisplay)
This function returns the current contents of the specified phone display.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device.
LPVARSTRING lpDisplay
Specifies a far pointer to the memory location where the display content is to be stored, of type VARSTRING.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

The lpDisplay memory area should be at least (dwNumRows * dwNumColumns) elements in size to receive all of the display information. dwNumRows and dwNumColumns are available in the PHONECAPS structure returned by phoneGetDevCaps.

See Also

Functions: phoneGetDevCaps, phoneSetDisplay

Data Types: PHONECAPS


phoneGetGain

Syntax

LONG phoneGetGain(hPhone, dwHookSwitchDev, lpdwGain)
This function returns the gain setting of the mic of specified phone's hookswitch device.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device.
DWORD dwHookSwitchDev
Identifies the hookswitch device whose gain level is queried, of type PHONEHOOKSWITCHDEV.
PHONEHOOKSWITCHDEV_HANDSET
This is the phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
This is the phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
This is the phone's headset.
LPDWORD lpdwGain
Specifies a far pointer to a DWORD sized location containing the current gain setting of the hookswitch mic component. dwGain specifies the volume level of the hookswitch device. This is a number in the range 0x00000000, which is silence to 0x0000FFFF which is maximum volume. The actual granularity and quantization of gain settings in this range are service provider specific.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch device parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

None.

See Also

Functions: phoneGetDevCaps, phoneSetGain

Data Types: PHONECAPS


phoneGetHookSwitch

Syntax

LONG phoneGetHookSwitch(hPhone, lpdwHookSwitchDevs)
This function returns the current hook switch mode of the specified open phone device.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device.
LPDWORD lpdwHookSwitchDevs
Specifies a far pointer to a DWORD-sized location to be filled with the mode of the phone's hookswitch devices, of type PHONEHOOKSWITCHDEV. If a bit position is FALSE, then the corresponding hookswitch device is on hook; if TRUE, then the mic and/or speaker part of the corresponding hookswitch device is offhook. To find out whether mic and/or speaker are enabled, the app can use phoneGetStatus. Values are:
PHONEHOOKSWITCHDEV_HANDSET
This is the phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
This is the phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
This is the phone's headset.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

After the hookswitch state of a device changes, and if hookswitch monitoring is enabled, the application is sent a PHONE_STATE message.

See Also

Functions: phoneSetHookSwitch

Messages: PHONE_STATE

Data types: PHONESTATUS, PHONEHOOKSWITCHDEV


phoneGetID

Syntax

LONG phoneGetID(hPhone, lpDeviceID, lpszDeviceClass)
This function returns a device ID for the given device class associated with the specified phone device.

Parameters

HPHONE hPhone
Specifies a handle to an open phone device.
LPVARSTRING lpDeviceID
Specifies a far pointer to a data structure of type VARSTRING where the device ID is returned. Upon successful completion of the request, this location is filled with the device ID. The format of the returned information depends on the method used by the device class (API) for naming devices.
LPCSTR const lpszDeviceClass
Specifies a far pointer to a NULL-terminated string that specifies the device class of the device whose ID is requested. Valid device class strings are those used in the SYSTEM.INI section to identify device classes.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The hPhone parameter is an invalid handle.
PHONEERR_INVALPOINTER
One of the specified pointer parameters are invalid.
PHONEERR_NODEVICE
The phone device has no associated device for the given device class.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

This operation can be used to retrieve a phone device ID given a phone handle. It can also be used to obtain the device ID of the media device (e.g., mci waveform, mci midi, waveform, etc.) associated with the opened phone device. This ID can then be used with the appropriate media API (e.g., mci, midi, wav, etc.) to select the corresponding device.

See Also

None.


phoneGetLamp

Syntax

LONG phoneGetLamp(hPhone, dwButtonLampID, lpdwLampMode)
This function returns the current lamp mode of the specified lamp.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device.
DWORD dwButtonLampID
Specifies the ID of the lamp to be queried.
LPDWORD lpdwLampMode
Specifies a far pointer to a memory location that will hold the lamp mode status of the given lamp, of type PHONELAMPMODE. Values are:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.
PHONELAMPMODE_UNKNOWN
The lamp mode is currently unknown.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALBUTTONLAMPID
The specified Button ID is out of range.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

Phone sets that have multiple lamps per button, should be modeled using multiple button/lamps pairs. Each extra button/lamp pair should use a DUMMY button.

See Also

Functions: phoneGetDevCaps, phoneSetLamp

Data Types: PHONECAPS, PHONELAMPMODE


phoneGetRing

Syntax

LONG phoneGetRing(hPhone, lpdwRingMode, lpdwVolume)
This function enables an application to query the specified open phone device as to its current ring mode.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device.

LPDWORD lpdwRingMode
Specifies the ringing pattern with which the phone is ringing. Zero indicates that the phone is not ringing.
LPDWORD lpdwVolume
Specifies the volume level with which the phone is ringing. This is a number in the range 0x00000000, which is silence to 0x0000FFFF which is maximum volume. The actual granularity and quantization of volume settings in this range are service provider specific.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

The service provider defines the actual audible ringing patterns corresponding to each of phone's ring modes.

See Also

Functions: phoneGetDevCaps, phoneSetRing

Data Types: PHONECAPS


phoneGetStatus

Syntax

LONG phoneGetStatus(hPhone, lpPhoneStatus)
This operation enables an application to query the specified open phone device for its overall status.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device to be queried.
LPPHONESTATUS lpPhoneStatus
Specifies a far pointer to a variable sized data structure of type PHONESTATUS, which is loaded with the returned information about the phone's status.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

An application can use this function to determine the current state of an open phone device. The status information describes information about the phone device's hook switch devices, ringer, volume, display, and lamps of the open phone.

See Also

Messages: PHONE_STATE

Data Types: PHONESTATUS


phoneGetStatusMessages

Syntax

LONG phoneGetStatusMessages(hPhone, lpdwPhoneStates, lpdwButtonModes,

lpdwButtonStates)
This operation returns which phone state changes on the specified phone device will generate a callback to the application.

Parameters

HLINE hPhone
Specifies a handle to the open line device to be monitored.
LPDWORD lpdwPhoneStates
Specifies a far pointer to a variable of type PHONESTATE. These flags specify the set of phone status changes and events for which the application wishes to receive notification messages. Monitoring can be individually enabled and disabled for:
PHONESTATE_OTHER
An other phone status information item not listed below has changed.
PHONESTATE_CONNECTED
The connection between the phone device and the API was just made. This happens when the API is first invoked, or when the wire connection the phone to the PC is plugged in with the API active.
PHONESTATE_DISCONNECTED
The connection between the phone device and the API was just broken. This happens when the wire connecting the phone set to the PC is unplugged while the API is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's mic gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's mic gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's mic gain setting has changed.
PHONESTATE_SUSPEND
The app's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The app's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device specific information has changed.
LPDWORD lpdwButtonModes
Specifies a far pointer to a PHONEBUTTONMODE. These flags specify the set of phone button modes for which the application wishes to receive notification messages. Values are:
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, transfer, etc.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.
LPDWORD lpdwButtonStates
Specifies a far pinter to a PHONEBUTTONSTATE. These flags specify the set of phone button state changes for which the application wishes to receive notification messages. Values are:
PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (i.e., pressed down).

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified phone device handle is invalid.
PHONEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

Not applicable.

Comments

An application can use this function to query the generation of the corresponding messages. Message generation can be controlled by phoneSetStatusMessages. All phone status messages are disabled by default.

See Also

Functions: phoneSetStatusMessages

Messages: PHONE_STATE, PHONE_BUTTON

Data Types: PHONESTATE


phoneGetVolume

Syntax

LONG phoneGetVolume(hPhone, dwHookSwitchDev, lpdwVolume)
This function returns the volume setting of the specified phone's hookswitch device.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device.
DWORD dwHookSwitchDev
Identifies a single hook switch device whose volume level is queried, of type PHONEHOOKSWITCHDEV. Values are:
PHONEHOOKSWITCHDEV_HANDSET
This is the phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
This is the phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
This is the phone's headset.
LPDWORD lpdwVolume
Specifies a far pointer to a DWORD sized location containing the current volume setting of the hookswitch device. dwVolume specifies the volume level of the hookswitch device. This is a number in the range 0x00000000, which is silence to 0x0000FFFF which is maximum volume. The actual granularity and quantization of volume settings in this range are service provider specific.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch device parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

None.

See Also

Functions: phoneGetDevCaps, phoneSetVolume

Data Types: PHONECAPS


phoneInitialize

Syntax

LONG phoneInitialize(lphApp, hInstance, lpfnCallback, lpsAppName, dwSize,

lpdwNumDevs)
This function initializes the application's use of the Telephony API DLL for subsequent use of the phone abstraction. It registers the application's specified notification mechanism and returns the number of phone devices that are available to the application.

Parameters

LPHPHONEAPP lphApp
Specifies a far pointer to a location that is filled with the app's usage handle for the API.
HINSTANCE hInstance
Specifies the instance handle of the client application or DLL.
PHONECALLBACK lpfnCallback
Specifies the address of a callback function to be invoked related to status and events on the phone device.
LPCSTR const lpsAppName
Specifies a far pointer to a string of the format specified in the dwStringFormat field of the phone device capabilities. If this parameter is non-NULL, then it contains an application-supplied name of the app. This name is provided in the PHONESTATUS structure to indicate in a user-friendly way, which application is the current owner of the phone device. This information can be useful for call logging purposes. If lpsAppName is NULL, then the application's module name will used instead.
DWORD
dwSize
Specifies the size in bytes of the string pointed at by the lpsAppName parameter. This parameter is ignored in lpsAppName is NULL.
LPDWORD lpdwNumDevs
Specifies a far pointer to DWORD-sized memory location. This location is loaded with the number of phone devices available to the application.

Return Value

Returns zero if the function is successful, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALAPPNAME
The specified app name is invalid.
PHONEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
PHONEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Callback

VOID FAR PASCAL phoneCallbackFunc(hDevice, dwMsg, dwCallbackInstance,

dwParam1, dwParam2, dwParam3)

phoneCallbackFunc is a placeholder for the application-supplied function name.

Parameters

HANDLE hDevice
Specified a handle to a phone device associated with the callback.
DWORD dwMsg
Specifies a line or call device message.
DWORD dwCallbackInstance
Specifies callback instance data passed back to the application in the callback. This DWORD is not interpreted by the API.
DWORD dwParam1
Specifies a parameter for the message.
DWORD dwParam2
Specifies a parameter for the message.
DWORD dwParam3
Specifies a parameter for the message.

Comments

The actual parameters passed to the application's callback function are described in the Messages Chapter of this document.

All callbacks occur in the application's context. The callback function must reside in a dynamic link library (DLL) or application module and be exported in the module definition file. You must use MakeProcInstance to get a procedure-instance address for the callback function.

Comments

The app can refer to individual line devices by using line device IDs that range from zero to dwNumDevs - 1. An application should not assume that these line devices are capable of anything beyond what is specified by the simple telephony subset without first querying their device capabilities via lineGetDevCaps and lineGetAddressCaps.

See Also

Functions: phoneShutdown


phoneOpen

Syntax

LONG phoneOpen(hApp, dwDeviceID, lphPhone, dwAPIVersion, dwExtVersion, dwCallbackInstance, dwPrivilege)
This function opens the specified phone device. A phone device can be opened using either owner privileges or monitor privileges. An application that opens the phone with owner privileges can control the phone's lamps, display, ringer, and hook switch(es). An application that opens the phone device with monitor privileges is only notified about events occurring at the phone; i.e., hookswitch changes, button presses via messages sent to its window or callback. Ownership of a phone device is exclusive; i.e., at most one application can have a phone device opened with owner privileges at once. It can, however, be opened multiple times with monitor privileges.

Parameters

HPHONEAPP hApp
Specifies a handle to the app's registration with the API.
DWORD dwDeviceID
Identifies the phone device be opened.
LPHPHONE lphPhone
Specifies a far pointer to a HPHONE handle. This location is then loaded with a handle that identifies the open phone device. Use this handle to identify the device when invoking other phone control functions.
DWORD dwAPIVersion
Specifies the API version number under which the app and Telephony API have agreed to operate. This number is obtained from phoneGetDevCaps.
DWORD dwExtVersion
Specifies the Extension version number under which the app and the service provider agree to operate. This number is zero if the application does not use any extensions. This number is obtained from phoneGetDevCaps.
DWORD dwCallbackInstance
Specifies user instance data passed back to the application's callback. This parameter is not interpreted by the Telephony API.

DWORD dwPrivilege
Specifies the privilege requested, of type PHONEPRIVILEGE. Values are:
PHONEPRIVILEGE_MONITOR
An application that opens a phone device with this privilege is informed about events and state changes occurring on the phone. The application cannot invoke any operations on the phone device that would change its state.
PHONEPRIVILEGE_OWNER
An application that opens a phone device in this mode is allowed to change the state of the lamps, ringer, display, and hook switch devices of the phone. Having owner privileges to a phone device automatically includes monitor privileges as well.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALAPPHANDLE
The specified resource is already allocated.
PHONEERR_BADDEVICEID
The specified device ID is out of range.
PHONEERR_INCOMPATIBLEVERSION
The app requested an incompatible API version number.
PHONEERR_INVALEXTVERSION
The app requested an invalid extension version number.
PHONEERR_ALLOCATED
The specified resource is already allocated.
PHONEERR_NOMEM
Unable to allocate or lock memory.
PHONEERR_NODRIVER
The driver was not installed.
PHONEERR_INVALPOINTER
One or more of the specified pointer parameters are invalid.
PHONEERR_RESOURCEUNAVAIL
The specified operation cannot be completed because of resource overcommitment.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

When opening a phone device with monitor privileges, the application is sent messages when events occur that change the status of the phone. Message sent to the application include PHONE_BUTTON and PHONE_STATE. The latter provides an indication of the phone's status item that has changed.
When opening a phone with owner privileges, the phone device can be manipulated in ways that affect the state of the phone device. An application should only open a phone using owner privileges is to actively wants to manipulate the phone device, and close the phone device when done to allow other applications to control the phone.
When an app opens a phone device it must specify the negotiated API version and, if it wants to use the phone's extensions, the phone's device specific Extension version. This version numbers should have been obtained via phoneGetDevCaps. Version numbering allows the mix and match of different app versions with different API versions and service provider versions.

See Also

Functions: phoneClose

Data Types: PHONEPRIVILEGE


phoneSetButtonInfo

Syntax

LONG phoneSetButtonInfo(hPhone, dwButtonLampID, lpButtonInfo)
This function sets information about the specified button on the specified phone.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone device.
DWORD dwButtonLampID
Specifies a button on the phone device.
LPPHONEBUTTONINFO const lpButtonInfo
Specifies a far pointer to a variable sized structure of type PHONEBUTTONINFO. This data structure describes the mode, the function, and provides additional descriptive text corresponding to the button.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_INVALBUTTONLAMPID
The specified button/lamp ID is invalid.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.

Comments

This function sets the meaning and associated descriptive text of a phone's buttons.

See Also

Functions: phoneGetButtonInfo
Data Types: PHONEBUTTONINFO, PHONECAPS


phoneSetData

Syntax

LONG phoneSetData(hPhone, dwDataID, lpData, dwSize)
This function downloads the information in the specified buffer to the opened phone device at the selected data ID.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone.

DWORD dwDataID
Specifies where in the phone device the buffer is to be downloaded.
LPVOID const lpData
Specifies a far pointer to the memory location where the data is to be downloaded from.

DWORD dwSize
Specifies the size of the buffer in bytes.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_INVALDATAID
The specified data ID is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Comments

The function downloads a maximum of dwSize bytes from lpData to the phone device. The format of the data, its meaning to the phone device, the meaning of the data ID are service provider specific. The data in the buffer or the selection of a data ID may act as commands to the phone device.

See Also

Functions: phoneGetDevCaps, phoneGetData
Data Types: PHONECAPS


phoneSetDisplay

Syntax

LONG phoneSetDisplay(hPhone, dwRow, dwColumn, lpsDisplay, dwSize)
This function causes the specified string to be displayed on the specified open phone device.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone.
DWORD dwRow
Specifies the row on the display where the new text is to be displayed.
DWORD dwColumn
Specifies the column position on the display where the new text is to be displayed.
LPCSTR const lpsDisplay
Specifies a far pointer to the memory location where the display content is stored. The display information must have the format specified as dwStringFormat in the phone's device capabilities.
DWORD dwSize
Specifies the size in bytes of the information pointed to by lpDisplay.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALPOINTER
The specified pointer parameter is invalid.
PHONEERR_INVALPARAM
The row or column parameters are invalid or out of range.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons

Comments

The specified display information is written to the phone's display, starting at the specified positions. This operation overwrites previously displayed information. If the amount of information exceeds the size of the display, then the information will be truncated. The amount of information that can be displayed is at most (dwNumRows * dwNumColumns) elements in size. dwNumRows and dwNumColumns are available in the PHONECAPS structure returned by phoneGetDevCaps; they are zero-based.

See Also

Functions: phoneGetDevCaps, phoneGetDisplay
Data Types: PHONECAPS


phoneSetGain

Syntax

LONG phoneSetGain(hPhone, dwHookSwitchDev, dwGain)
This function sets the gain of the mic of the specified hook switch device to the specified gain level.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone.
DWORD dwHookSwitchDev
Identifies the hook switch device whose mic's gain is to be set, of type PHONEHOOKSWITCHDEV. Values are:
PHONEHOOKSWITCHDEV_HANDSET
This is the phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
This is the phone's speakerphone or adjunct.
PHONEHOOKSWITCH_HEADSET
This is the phone's headset.
DWORD dwGain
Specifies a far pointer to a DWORD sized location containing the current gain setting of the device. dwGain specifies the gain level of the hookswitch device. This is a number in the range 0x00000000, which is silence to 0x0000FFFF which is maximum volume. The actual granularity and quantization of gain settings in this range are service provider specific.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch device parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Comments

None.

See Also

Functions: phoneGetDevCaps, phoneSetGain

Data Types: PHONECAPS


phoneSetHookSwitch

Syntax

LONG phoneSetHookSwitch(hPhone, dwHookSwitchDevs,

dwHookSwitchMode)
This function sets the hook state of the specified open phone's hookswitch devices to the specified mode. Only the hookswitch state of the hookswitch devices listed is affected.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone.

DWORD dwHookSwitchDevs
Specifies the device(s) whose hookswitch mode is to be set, of type PHONEHOOKSWITCHDEV. Values are:
PHONEHOOKSWITCHDEV_HANDSET
This is the phone's handset.
PHONEHOOKSWITCHDEV_SPEAKER
This is the phone's speakerphone or adjunct.
PHONEHOOKSWITCHDEV_HEADSET
This is the phone's headset.

DWORD dwHookSwitchMode
Specifies the hookswitch mode to set, of type PHONEHOOKSWITCHMODE. Values are:
PHONEHOOKSWITCHMODE_ONHOOK
The device's mic and speaker are both onhook.
PHONEHOOKSWITCHMODE_MIC
The devicer's mic is active, the speaker is mute.
PHONEHOOKSWITCHMODE_SPEAKER
The device's speaker is active, the mic is mute.
PHONEHOOKSWITCHMODE_MICSPEAKER
The device's mic and speaker are both active.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified phone device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch device parameter is invalid.
PHONEERR_INVALHOOKSWITCHMODE
The hookswitch mode parameter is invalid.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Comments

The hookswitch mode is the same for all devices specified. If different settings are desired, then this function can be invoked multiple times with a different set of parameters. A PHONE_STATE message is sent to the application after the hookswitch state has changed.

See Also

Functions: phoneGetHookSwitch
Messages: PHONE_STATE
Data types: PHONESTATUS, PHONEHOOKSWITCHDEV,
PHONEHOOKSWITCHMODE


phoneSetLamp

Syntax

LONG phoneSetLamp(hPhone, dwButtonLampID, dwLampMode)
This function causes the specified lamp to be lit on the specified open phone device in the specified lamp mode.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone.
DWORD dwButtonLampID
Identifies the button whose lamp is to be lit.

DWORD dwLampMode
Specifies how the lamp is to be lit, of type PHONELAMPMODE. Values are:
PHONELAMPMODE_BROKENFLUTTER
Broken flutter is the superposition of flash and flutter.
PHONELAMPMODE_FLASH
Flash means slow on and off.
PHONELAMPMODE_FLUTTER
Flutter means fast on and off.
PHONELAMPMODE_OFF
The lamp is off.
PHONELAMPMODE_STEADY
The lamp is continuously lit.
PHONELAMPMODE_WINK
The lamp is winking.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_INVALBUTTONLAMPID
The specified button/lampID is out of range.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALLAMPMODE
The specified lamp mode parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Comments

None.

See Also

Functions: phoneGetDevCaps, phoneGetLamp
Data Types: PHONELAMPMODE


phoneSetRing

Syntax

LONG phoneSetRing(hPhone, dwRingMode, dwVolume)
This function rings the specified open phone device using the specified ring mode and volume.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone device.
DWORD dwRingMode
Specifies the ringing pattern with which to ring the phone.
DWORD dwVolume
Specifies the volume level with which the phone is ringing. This is a number in the range 0x00000000, which is silence to 0x0000FFFF which is maximum volume. The actual granularity and quantization of volume settings in this range are service provider specific.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALRINGMODE
The ring mode parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reason.

Comments

The service provider defines the actual audible ringing patterns corresponding to each of the phone's ring modes.

See Also

Functions: phoneGetDevCaps, phoneGetRing
Data Types: PHONECAPS


phoneSetStatusMessages

Syntax

LONG phoneSetStatusMessages(hPhone, dwPhoneStates, dwButtonModes,

dwButtonStates)
This operation enables an application to monitor the specified phone device for selected status events.

Parameters

HLINE hPhone
Specifies a handle to the open line device to be monitored.

DWORD dwPhoneStates
These flags specify the set of phone status changes and events for which the application wishes to receive notification messages, of type PHONESTATE. Values are:
PHONESTATE_OTHER
An other phone status information item not listed below has changed.
PHONESTATE_CONNECTED
The connection between the phone device and the API was just made. This happens when the API is first invoked, or when the wire connection the phone to the PC is plugged in with the API active.
PHONESTATE_DISCONNECTED
The connection between the phone device and the API was just broken. This happens when the wire connecting the phone set to the PC is unplugged while the API is active.
PHONESTATE_OWNER
The number of owners for the phone device has changed.
PHONESTATE_MONITORS
The number of monitors for the phone device has changed.
PHONESTATE_DISPLAY
The display of the phone has changed.
PHONESTATE_LAMP
A lamp of the phone has changed.
PHONESTATE_RINGMODE
The ring mode of the phone has changed.
PHONESTATE_RINGVOLUME
The ring volume of the phone has changed.
PHONESTATE_HANDSETHOOKSWITCH
The handset hookswitch state has changed.
PHONESTATE_HANDSETVOLUME
The handset's speaker volume setting has changed.
PHONESTATE_HANDSETGAIN
The handset's mic gain setting has changed.
PHONESTATE_SPEAKERHOOKSWITCH
The speakerphone's hookswitch state has changed.
PHONESTATE_SPEAKERVOLUME
The speakerphone's speaker volume setting has changed.
PHONESTATE_SPEAKERGAIN
The speakerphone's mic gain setting state has changed.
PHONESTATE_HEADSETHOOKSWITCH
The headset's hookswitch state has changed.
PHONESTATE_HEADSETVOLUME
The headset's speaker volume setting has changed.
PHONESTATE_HEADSETGAIN
The headset's mic gain setting has changed.
PHONESTATE_SUSPEND
The app's use of the phone is temporarily suspended.
PHONESTATE_RESUME
The app's use of the phone device is resumed after having been suspended for some time.
PHONESTATE_DEVSPECIFIC
The phone's device specific information has changed.

DWORD dwButtonModes
These flags specify the set of phone button modes for which the application wishes to receive notification messages, of type PHONEBUTTONMODE. Values are:
PHONEBUTTONMODE_CALL
The button is assigned to a call appearance.
PHONEBUTTONMODE_FEATURE
The button is assigned to requesting features from the switch, such as hold, conference, transfer, etc.
PHONEBUTTONMODE_KEYPAD
The button is one of the twelve keypad buttons, '0' through '9', '*', and '#'.
PHONEBUTTONMODE_LOCAL
The button is a local function button, such as mute or volume control.
PHONEBUTTONMODE_DISPLAY
The button is a "soft" button associated with the phone's display. A phone set can have zero or more display buttons.

DWORD dwButtonStates
These flags specify the set of phone button state changes for which the application wishes to receive notification messages, of type PHONEBUTTONSTATE. Values are:
PHONEBUTTONSTATE_UP
The button is in the "up" state.
PHONEBUTTONSTATE_DOWN
The button is in the "down" state (i.e., pressed down).

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified line device handle is invalid.
PHONEERR_INVALPHONESTATE
The specified phone states parameter is invalid.
PHONEERR_INVALBUTTONMODE
The button mode parameter is invalid.
PHONEERR_INVALBUTTONSTATE
The button states parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
The specified operation is not available.
PHONEERR_OPERATIONFAILED
The specified operation failed for unspecified reasons.

Call States

Not applicable

Comments

An application can use this function to enable or disable the generation of the corresponding messages. All phone status messages are disabled by default.

See Also

Functions: phoneGetStatusMessages
Messages: PHONE_STATE, PHONE_BUTTON
Data Types: PHONESTATE


phoneSetVolume

Syntax

LONG phoneSetVolume(hPhone, dwHookSwitchDev, dwVolume)
This function either sets the volume of the speaker component of the specified hookswitch device to the specified level.

Parameters

HPHONE hPhone
Specifies a handle to the open phone device. The app must be the owner of the phone.
DWORD dwHookSwitchDev
Identifies the hook switch device whose speaker's volume is to be set.
PHONEHOOKSWITCH_HANDSET
This is the phone's handset.
PHONEHOOKSWITCH_SPEAKER
This is the phone's speakerphone or adjunct.
PHONEHOOKSWITCH_HEADSET
This is the phone's headset.
DWORD dwVolume
Specifies the current volume setting of the device. dwVolume specifies the volume level of the hookswitch device. This is a number in the range 0x00000000, which is silence to 0x0000FFFF which is maximum volume. The actual granularity and quantization of volume settings in this range are service provider specific.

Return Value

Returns zero if the function is successful, a positive request ID if the function will be completed asynchronously, or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALPHONEHANDLE
The specified device handle is invalid.
PHONEERR_NOTOWNER
The app does not have owner privileges to the specified phone device.
PHONEERR_INVALPHONESTATE
The phone device is not in a valid state for the requested operation.
PHONEERR_INVALHOOKSWITCHDEV
The hookswitch dev parameter is invalid.
PHONEERR_OPERATIONUNAVAIL
PHONEERR_OPERATIONFAILED

None.

Functions:

phoneGetDevCaps, phoneSetVolume
Data Types: PHONECAPS
The specified operation is not available.
The specified operation failed for unspecified reason.

Comments

See Also


phoneShutdown

Syntax

LONG phoneShutdown(hApp)
This function shuts down the application's usage of the API's phone abstraction.

Parameters

HPHONEAPP hApp
Specifies the app's usage handle for the API.

Return Value

Returns zero if the function is successful or a negative error number if an error has occurred. Possible error returns are:

PHONEERR_INVALAPPHANDLE
The app's specified usage handle is invalid.

Comments

If this function is called when the application has open phone device, then these devices will be closed.

See Also

Functions: phoneInitialize