function displays an application-modal dialog which allows the user to change
the current location, adjust location and calling card parameters, and see the
effect on a phone number about to be dialed.
| HLINEAPP hLineApp,
| DWORD dwDeviceID,
| DWORD dwAPIVersion,
| HWND hwndOwner,
| LPCSTR lpszAddressIn
The application handle returned by lineInitializeEx
. If an application has not yet called the lineInitializeEx
function, it can set the hLineApp
parameter to NULL.
The device ID for the line device upon which the call is intended to be
dialed, so that variations in dialing procedures on different lines can be applied to
the translation process.
Indicates the highest version of TAPI supported by the application (not
necessarily the value negotiated by lineNegotiateAPIVersion
on the line device indicated by dwDeviceID
A handle to a window to which the dialog is to be attached. Can be a NULL
value to indicate that any window created during the function should have no owner
A pointer to a NULL-terminated ASCII string containing a phone number which
will be used, in the lower portion of the dialog, to show the effect of the
user's changes to the location parameters. The number must be in canonical format;
if non-canonical, the phone number portion of the dialog will not be displayed.
This pointer can be left NULL, in which case the phone number portion of the
dialog will not be displayed. If the AddressIn
contains a subaddress or name field, or additional addresses separated from
the first address by ASCII CR and LF characters, only the first address is used
in the dialog.
Returns zero if the request is successful or a negative error number if an
error has occurred. 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 API versions 0x00020000 and greater, it is possible for multiple instances
of this dialog to be opened. In API versions less than 0x00020000,
LINEERR_INUSE is returned if the dialog is already displayed by another application (cannot
be open more than once). In these versions, TAPI brings the existing dialog 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
) returns LINEERR_INIFILECORRUPT, the application should call lineTranslateDialog
. The lineTranslateDialog
function will detect the errors and correct them, and report the action taken
to the user. Note that LINEERR_INIFILECORRUPT will be returned the first time
any of these functions are used after installation of Windows 95, because the
parameters will be uninitialized (lineTranslateDialog
will take 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.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages