lineTranslateDialog
The lineTranslateDialog
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.
LONG lineTranslateDialog(
|
HLINEAPP hLineApp, |
|
|
DWORD dwDeviceID, |
|
|
DWORD dwAPIVersion, |
|
|
HWND hwndOwner, |
|
|
LPCSTR lpszAddressIn |
|
|
); |
|
Parameters
hLineApp
The
application handle returned by lineInitializeEx. If an application has not yet called the lineInitializeEx
function, it can set the hLineApp parameter to NULL.
dwDeviceID
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.
dwAPIVersion
Indicates the
highest version of TAPI supported by the application (not necessarily
the value negotiated by lineNegotiateAPIVersion on the line device indicated
by dwDeviceID).
hwndOwner
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 window.
lpszAddressIn
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.
Return Values
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.
Remarks
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
or lineTranslateAddress) 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.
See Also