The lineTranslateDialog function displays an application-modal dialog box that allows the user to change the current location of a phone number about to be dialed, adjust location and calling card parameters, and see the effect.
LONG lineTranslateDialog(
HLINEAPP hLineApp,
DWORD dwDeviceID,
DWORD dwAPIVersion,
HWND hwndOwner,
LPCSTR lpszAddressIn
);
Returns zero if the request succeeds or a negative error number if an error occurs. Possible return values are:
LINEERR_BADDEVICEID, LINEERR_INVALPARAM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_INVALPOINTER, LINEERR_INIFILECORRUPT, LINEERR_NODRIVER, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED.
In TAPI version 2.0 or later, it is possible for multiple instances of this dialog box to be opened. In TAPI versions earlier than 2.0, LINEERR_INUSE is returned if the dialog box is already displayed by another application (cannot be open more than once). In these versions, TAPI brings the existing dialog box to the front, and the error indicates that any particulars related to the address passed in by the current application have not been handled, because that address was not processed by the function.
The application must call lineGetTranslateCaps after this function to obtain any changes the user made to the telephony address translation parameters, and call lineTranslateAddress to obtain a dialable string based on the user's new selections.
If any function related to address translation (for example, lineGetTranslateCaps or lineTranslateAddress) returns LINEERR_INIFILECORRUPT, the application should call lineTranslateDialog. The lineTranslateDialog function detects the errors and corrects them, and reports the action taken to the user. LINEERR_INIFILECORRUPT is returned the first time any of these functions are used after installation of Windows 95, because the parameters are uninitialized (lineTranslateDialog takes care of initializing them, using the user-specified default country to select the default country code).
Although this is a new function which older applications would not be expected to call, for backward compatibility they should not be prevented from doing so; the full range of API versions supported by TAPI (0x00010003 to 0x00010004) should work the same way.
Version: Use TAPI version 1.4 and later.
Header: Declared in tapi.h.
Import Library: Link with tapi32.lib.
TAPI Reference Overview, Basic Telephony Services Reference, lineGetTranslateCaps, lineInitializeEx, lineNegotiateAPIVersion, lineTranslateAddress