TSPI_lineSetupConference-Funktion (tspi.h)

Artikel
03/06/2024

Die funktion TSPI_lineSetupConference richtet eine Telefonkonferenz zum Hinzufügen des Drittanbieters ein.

Syntax

LONG TSPIAPI TSPI_lineSetupConference(
  DRV_REQUESTID          dwRequestID,
  HDRVCALL               hdCall,
  HDRVLINE               hdLine,
  HTAPICALL              htConfCall,
  LPHDRVCALL             lphdConfCall,
  HTAPICALL              htConsultCall,
  LPHDRVCALL             lphdConsultCall,
  DWORD                  dwNumParties,
  LPLINECALLPARAMS const lpCallParams
);

Parameter

dwRequestID

Der Bezeichner der asynchronen Anforderung.

hdCall

Das Handle für den ersten Anruf, der den Erstanbieter einer Telefonkonferenz identifiziert. In einigen Umgebungen muss ein Anruf vorhanden sein, um eine Telefonkonferenz starten zu können. In anderen Telefonieumgebungen ist zunächst kein Anruf vorhanden, und hdCall bleibt NULL. Der Anrufstatus von hdCall kann verbunden werden.

hdLine

Das Handle für das Leitungsgerät, auf dem die Telefonkonferenz entstehen soll, wenn hdCallNULL ist. Der hdLine-Parameter wird ignoriert, wenn hdCall ungleich NULL ist. Der Dienstanbieter meldet über das setupConfNull-Flag der LINEADDRESSCAPS-Datenstruktur , welches Modell unterstützt wird.

htConfCall

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

lphdConfCall

Ein Zeiger auf einen HDRVCALL,der den Bezeichner des Dienstanbieters für die neu erstellte Telefonkonferenz darstellt. Der Dienstanbieter muss diesen Speicherort mit seinem Handle für den neuen Aufruf füllen, bevor diese Prozedur zurückgegeben wird. Dieses Handle wird von TAPI ignoriert, wenn die Funktion zu einem Fehler führt. Der Aufrufstatus von hdConfCall ist nicht zutreffend.

htConsultCall

Die TAPI übernimmt den Konsultationsaufruf. Bei der Einrichtung eines Anrufs für die Hinzufügung einer neuen Partei wird automatisch ein neuer temporärer Anruf (Konsultationsgespräch) zugewiesen. Der Dienstanbieter muss den htConsultCall speichern und in allen nachfolgenden Aufrufen der LINEEVENT-Prozedur verwenden, die Ereignisse über den neuen Beratungsaufruf meldet.

lphdConsultCall

Ein Zeiger auf eine HDRVCALL-Instanz , die den Bezeichner des Dienstanbieters für einen Anruf darstellt. Bei der Einrichtung eines Anrufs für die Hinzufügung einer neuen Partei wird automatisch ein neuer temporärer Anruf (Konsultationsgespräch) zugewiesen. Der Dienstanbieter muss diesen Standort mit seinem Handle für den neuen Konsultationsaufruf ausfüllen, bevor dieses Verfahren zurückgegeben wird. Dieses Handle wird von TAPI ignoriert, wenn die Funktion zu einem Fehler führt. Der Aufrufstatus von hdConsultCall ist nicht zutreffend.

dwNumParties

Die erwartete Anzahl von Parteien in der Telefonkonferenz. Dem Dienstanbieter steht es frei, diese Nummer nach Bedarf zu verwenden. Der Dienstanbieter kann sie beispielsweise ignorieren oder als Hinweis verwenden, um die konferenzbrückende Größe innerhalb des Switches zuzuweisen. TAPI überprüft diesen Parameter nicht, wenn diese Funktion aufgerufen wird.

lpCallParams

Ein Zeiger auf eine LINECALLPARAMS-Struktur , die Aufrufparameter enthält, die beim Einrichten des Konsultationsaufrufs verwendet werden sollen. Dieser Parameter wird auf NULL festgelegt, wenn keine speziellen Aufrufsetupparameter gewünscht sind und der Dienstanbieter Standardparameter verwendet.

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_INVALCALLHANDLE, LINEERR_INVALADDRESSMODE, LINEERR_INVALLINEHANDLE, LINEERR_INVALBEARERMODE, LINEERR_INVALCALLSTATE, LINEERR_INVALCALLPARAMS, LINEERR_CALLUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CONFERENCEFULL, LINEERR_INVALMEDIAMODE, LINEERR_NOMEM, LINEERR_INVALRATE, LINEERR_OPERATIONUNAVAIL, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_RATEUNAVAIL, LINEERR_RESOURCEUNAVAIL, LINEERR_USERUSERINFOTOOBIG, LINEERR_BEARERMODEUNAVAIL.

Hinweise

Der Dienstanbieter gibt LINEERR_INVALLINEHANDLE zurück, wenn das angegebene Zeilenhandle für die Zeile, die die Telefonkonferenz enthält, ungültig ist. Dieser Fehler kann auch darauf hindeuten, dass die Telefonieumgebung eine erste Leitung zum Einrichten einer Konferenz erfordert, aber stattdessen ein Anrufhandle ohne NULL bereitgestellt wurde.

Der Dienstanbieter gibt LINEERR_INVALCALLHANDLE zurück, wenn die Telefonieumgebung einen ersten Anruf zum Einrichten einer Konferenz erfordert, aber stattdessen ein NULL-Anrufhandle bereitgestellt wurde.

TSPI_lineSetupConference bietet zwei Möglichkeiten, eine neue Telefonkonferenz einzurichten, je nachdem, ob ein normaler Anruf mit zwei Parteien bereits vorhanden ist oder nicht. Beim Einrichten einer Telefonkonferenz aus einem vorhandenen Zwei-Parteien-Anruf ist der hdCall-Parameter ein gültiges Anrufhandle, das der Telefonkonferenz anfänglich von der TSPI_lineSetupConference-Anforderung hinzugefügt und hdLine ignoriert wird. Bei Switches, bei denen die Einrichtung der Telefonkonferenz nicht mit einem vorhandenen Anruf beginnt, muss hdCallNULL sein, und hdLine muss angegeben werden, um das Leitungsgerät zu identifizieren, auf dem die Telefonkonferenz initiiert werden soll. In beiden Fällen wird ein Konsultationsaufruf für die Verbindung mit der Partei zugewiesen, die dem Anruf hinzugefügt werden soll. TAPI kann TSPI_lineDial verwenden, um die Adresse der anderen Partei zu wählen.

Die Telefonkonferenz wechselt in der Regel in den OnHoldPendingConference-Zustand , den Anrufwähltonzustand der Konsultation und den ersten Anruf (falls vorhanden) in den Konferenzzustand.

Eine Telefonkonferenz kann auch mithilfe einer TSPI_lineCompleteTransfer-Funktion eingerichtet werden, die in eine Drei-Wege-Konferenz aufgelöst wird.

TAPI kann möglicherweise zwischen der Konsultation und der Telefonkonferenz mit TSPI_lineSwapHold umschalten.

Die TSPI_lineUnhold-Funktion kann Aufrufe wiederherstellen, die den Aufrufstatus onHoldPendingConference aufweisen. Wenn dies erfolgt, wird jeder Konsultationsaufruf in der Regel in den Leerlaufzustand versetzt .

Ein Beratungsgespräch kann abgebrochen werden, indem TSPI_lineDrop darauf aufgerufen wird. Beim Ablegen eines Beratungsgesprächs wechselt die vorhandene Telefonkonferenz in der Regel wieder in den Zustand "Verbunden" . TAPI und seine Clientanwendungen sollten die LINE_CALLSTATE Nachrichten beobachten, um genau zu bestimmen, was mit den Aufrufen geschieht. Wenn die Telefonkonferenz beispielsweise wieder zu einem regulären Zwei-Parteien-Anruf zurückgesetzt wird, wird die Telefonkonferenz im Leerlauf, und der ursprüngliche Teilnehmeranruf kann mit verbunden rückgängig machen.

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. Anders ausgedrückt: Es darf keine LINEEVENT-Nachrichten für den neuen Aufruf ausgeben oder in die Aufrufanzahl in Nachrichten oder status Datenstrukturen für die Zeile einschließen.