lineTranslateDialog-Funktion (tapi.h)

Artikel
08/26/2023

Die lineTranslateDialog-Funktion zeigt ein anwendungsmodales Dialogfeld an, das es dem Benutzer ermöglicht, den aktuellen Speicherort einer Telefonnummer zu ändern, die gerade gewählt werden soll, den Standort anzupassen und Karte Parametern zu aufrufen und den Effekt anzuzeigen.

Syntax

LONG lineTranslateDialog(
  HLINEAPP hLineApp,
  DWORD    dwDeviceID,
  DWORD    dwAPIVersion,
  HWND     hwndOwner,
  LPCSTR   lpszAddressIn
);

Parameter

hLineApp

Von lineInitializeEx zurückgegebenes Anwendungshandle. Wenn eine Anwendung die lineInitializeEx-Funktion noch nicht aufgerufen hat, kann sie den hLineApp-Parameter auf Null festlegen.

dwDeviceID

Gerätebezeichner für das Leitungsgerät, über das der Anruf gewählt werden soll, sodass Variationen in Wählverfahren auf verschiedene Leitungen auf den Übersetzungsprozess angewendet werden können.

dwAPIVersion

Höchste TAPI-Version, die von der Anwendung unterstützt wird (nicht unbedingt der wert, der von lineNegotiateAPIVersion auf dem von dwDeviceID angegebenen Line-Gerät ausgehandelt wird).

hwndOwner

Handle für ein Fenster, an das das Dialogfeld angefügt werden soll. Kann ein NULL-Wert sein, der angibt, dass jedes während der Funktion erstellte Fenster kein Besitzerfenster haben darf.

lpszAddressIn

Zeiger auf eine NULL-endende Zeichenfolge, die eine Telefonnummer enthält, die im unteren Teil des Dialogfelds verwendet wird, um die Auswirkungen der Änderungen des Benutzers auf die Standortparameter anzuzeigen. Die Zahl muss im kanonischen Format vorliegen; wenn nichtcanonisch, wird der Telefonnummernteil des Dialogfelds nicht angezeigt. Dieser Zeiger kann NULL bleiben. In diesem Fall wird der Telefonnummernteil des Dialogfelds nicht angezeigt. Wenn der parameter lpszAddressIn eine Unteradresse oder ein Namensfeld enthält oder zusätzliche Adressen, die von der ersten Adresse durch CR- und LF-Zeichen getrennt sind, wird im Dialogfeld nur die erste Adresse verwendet.

Rückgabewert

Gibt null zurück, wenn die Anforderung erfolgreich ist, oder eine negative Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

LINEERR_BADDEVICEID, LINEERR_INVALPARAM, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_INVALPOINTER, LINEERR_INIFILECORRUPT, LINEERR_NODRIVER, LINEERR_INUSE, LINEERR_NOMEM, LINEERR_INVALADDRESS, LINEERR_INVALAPPHANDLE, LINEERR_OPERATIONFAILED.

Hinweise

In TAPI Version 2.0 oder höher ist es möglich, dass mehrere Instanzen dieses Dialogfelds geöffnet werden. In TAPI-Versionen vor 2.0 wird LINEERR_INUSE zurückgegeben, wenn das Dialogfeld bereits von einer anderen Anwendung angezeigt wird (es kann nicht mehr als einmal geöffnet werden). In diesen Versionen bringt TAPI das vorhandene Dialogfeld in den Vordergrund, und der Fehler gibt an, dass alle Angaben im Zusammenhang mit der von der aktuellen Anwendung übergebenen Adresse nicht verarbeitet wurden, da diese Adresse nicht von der Funktion verarbeitet wurde.

Die Anwendung muss lineGetTranslateCaps nach dieser Funktion aufrufen, um alle Änderungen abzurufen, die der Benutzer an den Parametern für die Übersetzung der Telefonadresse vorgenommen hat, und lineTranslateAddress aufrufen, um eine wählbare Zeichenfolge basierend auf den neuen Auswahlmöglichkeiten des Benutzers abzurufen.

Wenn eine Funktion im Zusammenhang mit der Adressübersetzung (z. B. lineGetTranslateCaps oder lineTranslateAddress) LINEERR_INIFILECORRUPT zurückgibt, sollte die Anwendung lineTranslateDialog aufrufen. Die lineTranslateDialog-Funktion erkennt die Fehler und korrigiert sie und meldet die ausgeführte Aktion an den Benutzer.