TSPI_lineMakeCall-Funktion (tspi.h)

Artikel
03/06/2024

Die TSPI_lineMakeCall-Funktion platziert einen Aufruf für die angegebene Zeile an die angegebene Zieladresse. Optional können Aufrufparameter angegeben werden, wenn etwas anderes als Standardparameter für die Einrichtung von Aufrufen angefordert werden.

Syntax

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parameter

dwRequestID

Der Bezeichner der asynchronen Anforderung.

hdLine

Das Handle für die Zeile, in der der neue Aufruf erfolgen soll.

htCall

Das TAPI-Handle für den neuen Aufruf. Der Dienstanbieter muss dies speichern und in allen nachfolgenden Aufrufen der LINEEVENT-Prozedur verwenden, die Ereignisse für den Aufruf meldet.

lphdCall

Ein Zeiger auf ein Aufrufhandle. Der Dienstanbieter muss diesen Speicherort mit seinem Handle für den Aufruf füllen, bevor diese Prozedur zurückgegeben wird. Dieses Handle wird von TAPI ignoriert, wenn die Funktion zu einem Fehler führt.

lpszDestAddress

Zeiger auf eine Unicode-Zeichenfolge mit NULL-Termin, die die Zieladresse angibt. Dies entspricht dem standardmäßigen wählbaren Nummernformat. Dieser Zeiger kann als NULL für nicht wählbare Adressen angegeben werden (wie bei einem Hot Phone, das immer automatisch eine Verbindung mit einer vordefinierten Nummer herstellt) oder wenn alle Wählvorgänge über TSPI_lineDial durchgeführt werden. Im letzteren Fall ordnet TSPI_lineMakeCall eine verfügbare Anrufdarstellung zu, die in der Regel im Wählzustand verbleibt, bis die Wählverbindung beginnt. Dienstanbieter, die über inverse Multiplexingfunktionen verfügen, können es einer Anwendung ermöglichen, mehrere Adressen gleichzeitig anzugeben.

dwCountryCode

Der Länder- oder Regionscode der aufgerufenen Partei. Wenn der Wert 0 angegeben wird, wird von der Implementierung ein Standardwert verwendet.

lpCallParams

Ein Zeiger auf eine LINECALLPARAMS-Struktur . Mit dieser Struktur kann TAPI angeben, wie der Aufruf eingerichtet werden soll. Wenn NULL angegeben ist, wird ein standardmäßiger 3,1-kHz-Sprachanruf eingerichtet, und eine beliebige Ursprungsadresse in der Zeile wird ausgewählt. Diese Struktur wählt Elemente aus, z. B. Bearermodus, Datenrate, erwarteten Medientyp, Ursprungsadresse, Blockierung von Anrufer-ID-Informationen und Wählparameter.

Rückgabewert

Gibt dwRequestID oder eine Fehlernummer zurück, wenn ein Fehler auftritt. Der tatsächliche lResult-Parameter der entsprechenden ASYNC_COMPLETION ist null, wenn die Funktion erfolgreich ist, oder eine Fehlernummer, wenn ein Fehler auftritt. Mögliche Rückgabewerte sind:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_ INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG.

Hinweise

Der Dienstanbieter gibt LINEERR_INVALLINESTATE zurück, wenn sich die Zeile derzeit nicht in einem Zustand befindet, in dem dieser Vorgang ausgeführt werden kann. Eine Liste der derzeit gültigen Vorgänge finden Sie im DwLineFeatures-Element (vom Typ LINEFEATURE) in der LINEDEVSTATUS-Struktur . (Durch aufrufen TSPI_lineGetLineDevStatus werden die Informationen in LINEDEVSTATUS aktualisiert.)

Wenn der Dienstanbieter LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE oder LINEERR_DIALPROMPT zurückgibt, sollte er keine der Aktionen ausführen, die anderweitig von TSPI_lineMakeCall ausgeführt werden. Beispiel: Keine teilwählende Wählfunktion und kein Ausrufen. Dies liegt daran, dass der Dienstanbieter die Nummer vorab auf nicht unterstützte Zeichen überprüfen sollte.

Nachdem TSPI_lineMakeCall eine SUCCESS-Antwortrückrufnachricht an die Anwendung zurückgegeben hat, muss der Dienstanbieter LINE_CALLSTATE Nachrichten an die lpfnEventProc senden, die in TSPI_lineOpen übergeben wurde, um TAPI über den Fortschritt des Anrufs zu informieren. Eine typische gemeldete Sequenz kann Wählton, Wählzeichen, Weiter, Ringback und verbunden sein. Der erste gemeldete Zustand ist nicht notwendigerweise LINECALLSTATE_DIALTONE. Der Dienstanbieter wählt aus, wie viele dieser Zustände gemeldet werden. Es wird empfohlen, so viele wie möglich zu senden, damit Anwendungen geeignete Maßnahmen ergreifen können.

Der Dienstanbieter führt zunächst die Medienüberwachung für den neuen Aufruf für mindestens den Satz von Medientypen durch, die auf der Leitung überwacht wurden.

Wenn die Wählzeichenfolge NULL ist, leitet der Dienstanbieter die Zeile in den Wählzustand (bei einem Comm-basierten Dienstanbieter würde dies ATD umfassen) und sendet eine Anrufstatusmeldung, die LINECALLSTATE_DIALTONE angibt.

Wenn die Wählzeichenfolge auf ";" endet (ein Semikolon) wählt der Dienstanbieter die Teilnummer und sendet die LINECALLSTATE_DIALING Nachricht. Dieser Aufruf wird durch Aufrufe von TSPI_lineDial abgeschlossen.

Wenn die Wählzeichenfolge Zeichen (W, @, $, ?) enthält, die vom Dienstanbieter nicht unterstützt werden, muss der Dienstanbieter die Wählzeichenfolge überprüfen und (synchron) einen Fehler zurückgeben, der dem ersten ungültigen Zeichen entspricht.

Wenn das LINECALLPARAMFLAGS_IDLE-Flag festgelegt ist, muss der Dienstanbieter die aktuelle Zeile status überprüfen (dies entspricht dem Off-Hook-Signal und dem Erkennen des Wähltons). Wenn dieses IDLE-Flag festgelegt ist und kein Wählton vorhanden ist, schlägt die Funktion mit dem Fehler LINEERR_CALLUNAVAIL fehl. Wenn das IDLE-Flag nicht festgelegt ist oder ein Wählton vorhanden ist, kann die Wählfunktion fortgesetzt werden.

Diese Funktion unterscheidet sich von der entsprechenden TAPI-Funktion darin, dass sie dem TSPI-Modell folgt, um die Lebensdauer eines Aufrufs zu beginnen. TAPI und der Dienstanbieter tauschen undurchsichtige Handles aus, die den Aufruf miteinander darstellen. Darüber hinaus ist der Dienstanbieter berechtigt, Rückrufe für den neuen Aufruf durchzuführen, bevor er von dieser Prozedur zurückgegeben wird. In jedem Fall muss der Dienstanbieter auch das zurückgegebene Handle als "noch nicht gültig" behandeln, bis die übereinstimmende ASYNC_COMPLETION Nachricht erfolgreich gemeldet wurde. Es darf keine LINEEVENT-Nachrichten für den neuen Aufruf ausgeben oder in die Aufrufanzahl in Nachrichten einschließen oder datenstrukturen für die Zeile status.