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