lineOpen-Funktion (tapi.h)

Artikel
03/06/2024

Die lineOpen-Funktion öffnet das durch den Gerätebezeichner angegebene Zeilengerät und gibt einen Zeilenhandle für das entsprechende geöffnete Zeilengerät zurück. Dieser Zeilenhandle wird in nachfolgenden Vorgängen auf dem Leitungsgerät verwendet.

Syntax

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parameter

hLineApp

Behandeln Sie die Registrierung der Anwendung bei TAPI.

dwDeviceID

Gibt das zu öffnende Leitungsgerät an. Es kann entweder ein gültiger Gerätebezeichner oder der Wert sein.

Wert	Bedeutung
LINEMAPPER	Dieser Wert wird verwendet, um ein Zeilengerät im System zu öffnen, das die in lpCallParams angegebenen Eigenschaften unterstützt. Die Anwendung kann lineGetID verwenden, um den Bezeichner des geöffneten Leitungsgeräts zu bestimmen.

lphLine

Zeiger auf ein HLINE-Handle, das dann mit dem Handle geladen wird, der das geöffnete Zeilengerät darstellt. Verwenden Sie dieses Handle, um das Gerät beim Aufrufen anderer Funktionen auf dem Open Line-Gerät zu identifizieren.

dwAPIVersion

API-Versionsnummer, unter der die Anwendung und die Telefonie-API ihren Betrieb vereinbart haben. Diese Nummer wird mit lineNegotiateAPIVersion abgerufen.

dwExtVersion

Versionsnummer der Erweiterung, unter der sich die Anwendung und der Dienstanbieter auf den Betrieb einigen. Diese Zahl ist 0, wenn die Anwendung keine Erweiterungen verwendet. Diese Nummer wird mit lineNegotiateExtVersion abgerufen.

dwCallbackInstance

Benutzer-instance Daten, die mit jeder Nachricht, die dieser Zeile zugeordnet ist, oder mit Adressen oder Aufrufen in dieser Zeile an die Anwendung zurückgegeben werden. Dieser Parameter wird von der Telefonie-API nicht interpretiert.

dwPrivileges

Privilegierung, die die Anwendung wünscht, wenn sie über einen Aufruf benachrichtigt wird Dieser Parameter enthält mindestens eine der LINECALLPRIVILEGE_ Konstanten. Für Anwendungen, die TAPI Version 2.0 oder höher verwenden, können Werte für diesen Parameter auch mit einer oder mehreren der LINEOPENOPTION_ Konstanten kombiniert werden.

Wenn die option LINEOPENOPTION_SINGLEADDRESS angegeben ist, ist die Anwendung nur an neuen Aufrufen interessiert, die für die Adresse angezeigt werden, die vom dwAddressID-Member in der LINECALLPARAMS-Struktur angegeben wird, auf die der lpCallParams-Parameter verweist (der angegeben werden muss).

Wenn LINEOPENOPTION_SINGLEADDRESS angegeben ist, aber lpCallParams ungültig ist oder die enthaltene dwAddressID nicht in der Zeile vorhanden ist, schlägt das Öffnen mit LINERR_INVALADDRESSID fehl.

Zusätzlich zum Festlegen des dwAddressID-Members der LINECALLPARAMS-Struktur auf die gewünschte Adresse muss die Anwendung auch dwAddressMode in LINECALLPARAMS auf LINEADDRESSMODE_ADDRESSID festlegen.

Die Option LINEOPENOPTION_SINGLEADDRESS wirkt sich nur auf die Zuweisung des anfänglichen Anrufbesitzes an Anrufen durch TAPI aus, die vom Dienstanbieter mithilfe einer LINE_NEWCALL Nachricht erstellt wurden. Eine Anwendung, die die Zeile mit LINECALLPRIVILEGE_MONITOR weiterhin Überwachungshandles für alle in der Zeile erstellten Aufrufe empfängt. Darüber hinaus ist die Anwendung in keiner Weise daran beschränkt, Anrufe auszuführen oder andere Vorgänge auszuführen, die sich auf andere Adressen in der geöffneten Zeile auswirken.

Wenn die Option LINEOPENOPTION_PROXY angegeben wird (nur TAPI 2.0 oder höher), muss die Anwendung auch angeben, welche spezifischen Proxyanforderungen für die Verarbeitung vorbereitet sind. Dazu wird im lpCallParams-Parameter ein Zeiger auf eine LINECALLPARAMS-Struktur übergeben, in der die Elemente dwDevSpecificSize und dwDevSpecificOffset festgelegt wurden, um ein Array von DWORD-Elementenzu trennen. Jedes Element dieses Arrays muss eine der LINEPROXYREQUEST_ Konstanten enthalten. Beispielsweise würde eine Proxyhandleranwendung, die alle fünf mit dem Agent verbundenen Funktionen unterstützt, in einem Array von fünf DWORD-Sübergeben (dwDevSpecificSize wäre 20 Dezimalstellen), die die fünf definierten LINEPROXYREQUEST_-Werte enthalten.

Die Proxyanforderungshandleranwendung kann auf jedem Computer ausgeführt werden, der über eine Autorisierung zum Steuern des Leitungsgeräts verfügt. Anforderungen werden jedoch immer über den Server weitergeleitet, auf dem der Dienstanbieter ausgeführt wird, der das Leitungsgerät tatsächlich steuert. Daher ist es am effizientesten, wenn die Anwendung, die Proxyanforderungen verarbeitet (z. B. die ACD-Agent-Steuerung), direkt auf dem Server zusammen mit dem Dienstanbieter ausgeführt wird.

Nachfolgende Versuche der gleichen Anwendung oder anderer Anwendungen, das Leitungsgerät zu öffnen und sich zu registrieren, um dieselben Proxyanforderungen wie eine bereits registrierte Anwendung zu verarbeiten, schlagen mit LINEERR_NOTREGISTERED fehl.

Um die Bearbeitung von Anforderungen in der Zeile zu beenden, ruft die Anwendung einfach lineClose auf.

Andere Flagkombinationen geben den LINEERR_INVALPRIVSELECT Fehler zurück.

dwMediaModes

Der Medientyp oder die Modi, die für die Anwendung von Interesse sind. Dieser Parameter wird verwendet, um die Anwendung als potenzielles Ziel für eingehenden Aufruf und Anrufübergabe für den angegebenen Medientyp zu registrieren. Dieser Parameter ist nur sinnvoll, wenn das Bit LINECALLPRIVILEGE_OWNER in dwPrivileges festgelegt ist (andernfalls ignoriert). Dieser Parameter verwendet mindestens eine der LINEMEDIAMODE_ Konstanten.

lpCallParams

Zeiger auf eine Struktur vom Typ LINECALLPARAMS. Dieser Zeiger wird nur verwendet, wenn LINEMAPPER oder LINEOPENOPTION_PROXY verwendet wird. andernfalls wird lpCallParams ignoriert. Es beschreibt den Aufrufparameter, den das Leitungsgerät bereitstellen soll.

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_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Hinweise

Wenn LINEERR_ALLOCATED zurückgegeben wird, kann die Zeile aufgrund einer "persistenten" Bedingung nicht geöffnet werden, z. B. aufgrund eines seriellen Ports, der ausschließlich von einem anderen Prozess geöffnet wird. Wenn LINEERR_RESOURCEUNAVAIL zurückgegeben wird, kann die Zeile aufgrund einer dynamischen Ressourcenüberlastung wie in DSP-Prozessorzyklen oder Arbeitsspeicher nicht geöffnet werden. Diese Überlastung kann vorübergehend sein, die durch die Überwachung des Medientyps oder der Töne verursacht wird, und Änderungen dieser Aktivitäten durch andere Anwendungen können es ermöglichen, die Linie innerhalb kurzer Zeit wieder zu öffnen. Wenn LINEERR_REINIT zurückgegeben wird und die TAPI-Neuinitialisierung angefordert wurde (z. B. durch Hinzufügen oder Entfernen eines Telefoniedienstanbieters), werden lineOpen-Anforderungen mit diesem Fehler abgelehnt, bis die letzte Anwendung die Verwendung der API heruntergefahren hat (mithilfe von lineShutdown); zu diesem Zeitpunkt wird die neue Konfiguration wirksam, und Anwendungen dürfen erneut lineInitializeEx aufrufen.

Das Öffnen einer Zeile berechtigt die Anwendung immer dazu, Anrufe an einer beliebigen Adresse zu tätigen, die in der Zeile verfügbar ist. Die Fähigkeit der Anwendung, eingehende Aufrufe zu verarbeiten oder das Ziel von Anrufübergaben in der Zeile zu sein, wird durch den dwMediaModes-Parameter bestimmt. Die lineOpen-Funktion registriert die Anwendung als interesse an der Überwachung von Aufrufen oder empfangen des Besitzes von Aufrufen, die den angegebenen Medientypen entsprechen. Wenn die Anwendung nur Aufrufe überwachen möchte, kann sie LINECALLPRIVILEGE_MONITOR angeben. Wenn die Anwendung nur ausgehende Aufrufe tätigen möchte, kann sie LINECALLPRIVILEGE_NONE angeben. Wenn die Anwendung bereit ist, nicht klassifizierte Aufrufe (Aufrufe unbekannter Medientypen) zu steuern, kann sie LINECALLPRIVILEGE_OWNER und LINEMEDIAMODE_UNKNOWN angeben. Andernfalls sollte die Anwendung den Medientyp angeben, den sie behandeln möchte. Die Anwendung kann die funktion lineSetCallPrivilege aufrufen, um die vom LINECALLPRIVILEGES_Constants angegebenen Aufrufberechtigungen zu ändern.

Die mit lineOpen angegebenen Medientypen fügen dem Standardwert für die Medientypüberwachung des Anbieters für die anfängliche Ermittlung eingehender Anruftypen hinzu. Die lineMonitorMedia-Funktion ändert die Maske, die LINE_MONITORMEDIA Nachrichten steuert. Wenn ein Zeilengerät mit Besitzerberechtigungen geöffnet und ein Erweiterungsmedientyp nicht registriert ist, wird der Fehler LINEERR_INVALMEDIAMODE zurückgegeben.

Eine Anwendung, die ein Leitungsgerät erfolgreich geöffnet hat, kann Anrufe immer mit lineMakeCall, lineUnpark, linePickupConference und lineSetupConference ( mit nullhCall) initiieren und lineForward verwenden (vorausgesetzt, dass dies durch die Gerätefunktionen, den Zeilenstatus usw. zulässig ist).

Eine einzelne Anwendung kann mehrere Flags gleichzeitig angeben, um mehrere Medientypen zu verarbeiten. Konflikte können auftreten, wenn mehrere Anwendungen dasselbe Leitungsgerät für denselben Medientyp öffnen. Diese Konflikte werden durch ein Prioritätsschema behoben, in dem der Benutzer den Anwendungen relative Prioritäten zuweist. Benutzer können Anwendungsprioritäten festlegen, indem sie die funktion lineSetAppPriority aufrufen. Nur die Anwendung mit der höchsten Priorität für einen bestimmten Medientyp erhält den Besitz (unaufgefragt) eines Aufrufs dieses Medientyps. Der Besitz kann empfangen werden, wenn ein eingehender Anruf zum ersten Mal eingeht oder wenn ein Anruf übergeben wird. Die lineHandoff-Funktion wird aufgerufen, um den Besitz eines Aufrufs einer anderen Anwendung zu übergeben. Wenn der Benutzer der Anwendung keine Prioritäten zuweist und mehrere Anwendungen dasselbe Leitungsgerät öffnen, hat die Anwendung, die zuerst lineOpen aufgerufen hat, standardmäßig die höchste Priorität.

Jede Anwendung (einschließlich jeder Anwendung mit niedrigerer Priorität) kann immer den Besitz mit lineGetNewCalls oder lineGetConfRelatedCalls erwerben. Wenn eine Anwendung eine Zeile zur Überwachung zu einem Zeitpunkt öffnet, zu dem Aufrufe in der Zeile vorhanden sind, werden LINE_CALLSTATE Nachrichten für diese vorhandenen Aufrufe nicht automatisch für die neue Überwachungsanwendung generiert. Die Anwendung kann die Anzahl der aktuellen Aufrufe in der Zeile abfragen, um zu bestimmen, wie viele Aufrufe vorhanden sind. Bei Bedarf kann sie lineGetNewCalls aufrufen, um Handles für diese Aufrufe abzurufen.

Eine Anwendung, die automatisierte Sprache verarbeitet, sollte auch den interaktiven Sprachmodus auswählen und die niedrigste Priorität für interaktive Stimme erhalten. Der Grund dafür ist, dass Dienstanbieter alle Sprachmedientypen als interaktive Stimme melden. Wenn die Ermittlung des Medientyps von der Anwendung für den UNKNOWN-Medientyp nicht durchgeführt wird und keine interaktive Sprachanwendung das Leitungsgerät geöffnet hat, können Sprachanrufe die automatisierte Sprachanwendung nicht erreichen und würden gelöscht.

Dieselbe Anwendung oder unterschiedliche Instanziierungen derselben Anwendung können dieselbe Zeile mehrmals mit denselben oder unterschiedlichen Parametern öffnen.

Wenn eine Anwendung ein Zeilengerät öffnet, muss sie die ausgehandelte API-Version angeben. Wenn sie die Erweiterungen der Zeile verwenden möchte, sollte sie die gerätespezifische Erweiterungsversion der Zeile angeben. Diese Versionsnummern sollten mit lineNegotiateAPIVersion und lineNegotiateExtVersion abgerufen werden. Die Versionsnummerierung ermöglicht das Mischen und Abgleichen verschiedener Anwendungsversionen mit unterschiedlichen API-Versionen und Dienstanbieterversionen.

LINEMAPPER ermöglicht es einer Anwendung, eine Zeile indirekt auszuwählen – mithilfe der Dienste, die sie von ihr erhalten möchte. Beim Öffnen eines Zeilengeräts mit LINEMAPPER gilt Folgendes: Alle Member vom Anfang der LINECALLPARAMS-Datenstruktur bis zum dwAddressMode sind relevant. Wenn dwAddressMode LINEADDRESSMODE_ADDRESSID bedeutet dies, dass jede Adresse in der Zeile akzeptabel ist. Andernfalls ist dwAddressMode LINEADDRESSMODE_DIALABLEADDR, was angibt, dass nach einer bestimmten Ursprungsadresse (Telefonnummer) gesucht wird, oder wenn es sich um eine anbieterspezifische Erweiterung handelt, sind dwOrigAddressSize/Offset und der Teil des Variablenteils, auf den sie verweisen, ebenfalls relevant. Wenn dwAddressMode eine anbieterspezifische Erweiterung ist, können zusätzliche Informationen im element dwDeviceSpecific mit variabeler Größe enthalten sein.