lineHandoff-Funktion (tapi.h)

Artikel
08/26/2023

Die lineHandoff-Funktion verleiht dem Besitzer des angegebenen Aufrufs einer anderen Anwendung. Die Anwendung kann entweder direkt durch ihren Dateinamen oder indirekt als Anwendung mit der höchsten Priorität angegeben werden, die Aufrufe des angegebenen Medienmodus verarbeitet.

Syntax

LONG lineHandoff(
  HCALL  hCall,
  LPCSTR lpszFileName,
  DWORD  dwMediaMode
);

Parameter

hCall

Behandeln Sie den Anruf, der übergeben werden soll. Die Anwendung muss besitzer des Aufrufs sein. Der Anrufstatus von hCall kann ein beliebiger Zustand sein.

lpszFileName

Zeiger auf eine NULL-beendete Zeichenfolge. Wenn dieser Zeigerparameter nicht NULL ist, enthält er den Dateinamen der Anwendung, die das Ziel der Übergabe ist. Bei NULL ist das Übergabeziel die Anwendung mit der höchsten Priorität, die die Zeile für die Besitzerberechtigung für den angegebenen Medienmodus geöffnet hat. Ein gültiger Dateiname enthält nicht den Pfad der Datei.

dwMediaMode

Medienmodus, der verwendet wird, um das Ziel für die indirekte Übergabe zu identifizieren. Der dwMediaMode-Parameter identifiziert indirekt die Zielanwendung, die den Besitz des Aufrufs erhalten soll. Dieser Parameter wird ignoriert, wenn lpszFileName nicht NULL ist. Dieser Parameter verwendet nur eine der LINEMEDIAMODE_ Konstanten.

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_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED, LINEERR_NOTOWNER.

Hinweise

Die lineHandoff-Funktion gibt LINEERR_TARGETSELF zurück, wenn die aufrufende Anwendung versucht hat, eine indirekte Übergabe durchzuführen (d. h. legen Sie den lpszFileName-Parameter auf NULL fest) und TAPI festgestellt hat, dass die Anwendung selbst die Anwendung mit der höchsten Priorität für den angegebenen Medienmodus ist. Wenn LINEERR_TARGETNOTFOUND zurückgegeben wird, wurde kein Ziel für die Anrufübergabe gefunden. Dies kann auftreten, wenn die benannte Anwendung nicht dieselbe Zeile mit dem LINECALLPRIVILEGE_OWNER Bit im dwPrivileges-Parameter von lineOpen geöffnet hat. Im Fall der Medienmodusübergabe hat keine Anwendung dieselbe Zeile mit dem LINECALLPRIVILEGE_OWNER Bit im dwPrivileges-Parameter von lineOpen und mit dem Medienmodus geöffnet, der im dwMediaModes-Parameter von lineOpen angegeben ist.

Die Anrufübergabe ermöglicht es, den Besitz eines Anrufs zwischen Anwendungen zu übergeben. Es gibt zwei Arten von Übergabe. Wenn die Anwendung beim ersten Typ den Dateinamen der Zielanwendung kennt, kann sie einfach diesen Dateinamen angeben. Wenn ein instance der Zielanwendung das Leitungsgerät geöffnet hat, wird der Besitz des Aufrufs an die andere Anwendung übergeben. Andernfalls schlägt die Übergabe fehl, und es wird ein Fehler zurückgegeben. Diese Form der Übergabe ist erfolgreich, wenn der Aufrufhandle an denselben Dateinamen wie die Anwendung übergeben wird, die die Übergabe anfordert.

Die zweite Art der Übergabe basiert auf dem Medienmodus. In diesem Fall gibt die Anwendung indirekt die Zielanwendung mithilfe eines Medienmodus an. Die Anwendung mit der höchsten Priorität, die derzeit das Leitungsgerät für diesen Medienmodus geöffnet hat, ist das Ziel für die Übergabe. Wenn keine solche Anwendung vorhanden ist, schlägt die Übergabe fehl, und ein Fehler wird zurückgegeben.

Die lineHandoff-Funktion ändert den Medienmodus eines Aufrufs nicht. Um den Medienmodus eines Aufrufs zu ändern, sollte die Anwendung lineSetMediaMode für den Aufruf verwenden und den neuen Medienmodus angeben. Dadurch wird der Medienmodus des Aufrufs in der LINECALLINFO-Struktur des Aufrufs geändert.

Wenn die Übergabe erfolgreich ist, erhält die empfangende Anwendung eine LINE_CALLSTATE Nachricht für den Anruf. Diese Meldung gibt an, dass die empfangende Anwendung über Besitzerberechtigungen für den Aufruf verfügt (dwParam3). Darüber hinaus kann sich die Anzahl der Besitzer und/oder Monitore für den Anruf geändert haben. Dies wird von der LINE_CALLINFO-Nachricht gemeldet, und die empfangende Anwendung kann dann lineGetCallStatus und lineGetCallInfo aufrufen, um weitere Informationen zum empfangenen Aufruf abzurufen.

Die empfangende Anwendung sollte zuerst den Medienmodus in LINECALLINFO überprüfen. Wenn nur ein einzelnes Medienmodusflag festgelegt ist, ist der Aufruf dieses Medienmodus offiziell, und die Anwendung kann entsprechend handeln. Wenn UNKNOWN- und andere Medienmodusflags festgelegt sind, ist der Medienmodus des Anrufs offiziell UNKNOWN, wird jedoch als einer der Medienmodi angenommen, für die in LINECALLINFO ein Flag festgelegt ist. Die Anwendung sollte davon ausgehen, dass sie den Medienmodus mit der höchsten Priorität testen sollte.

Wenn der Test erfolgreich verläuft (entweder für diesen Medienmodus oder für einen anderen), sollte die Anwendung den Medienmoduselement in LINECALLINFO auf den erkannten Einzelmedienmodus festlegen. Wenn das Medienmodusflag mit dem LINECALLINFO-Medienmodus übereinstimmt, kann die Anwendung entsprechend handeln. Wenn es eine Bestimmung für einen anderen Medienmodus trifft, muss er zuerst den Aufruf an diesen Medienmodus übergeben.

Wenn der Test fehlschlägt, sollte die Anwendung das entsprechende Medienmodusflag in LINECALLINFO löschen und den Aufruf aushändigen, wobei dwMediaMode als LINEMEDIAMODE_UNKNOWN angegeben wird. Außerdem sollte der Anrufhandle zugeordnet werden (oder rückgängig machen zurück zur Überwachung).

Wenn keiner der Medienmodi eine Bestimmung treffen konnte, bleibt nur das UNKNOWN-Flag im Medienmodusfeld von LINECALLINFO festgelegt, wenn die Medienanwendung versucht, den Aufruf an UNKNOWN zu übergeben. Die letzte ZeileHandoff schlägt fehl, wenn die Anwendung der einzige verbleibende Besitzer des Aufrufs ist. Dadurch wird die Anwendung darüber informiert, dass sie den Anruf löschen und die Zuordnung des Handles abwickeln soll. In diesem Fall wird der Aufruf abgebrochen. Die Berechtigungen der aufrufenden Anwendung für den Aufruf bleiben durch diesen Vorgang unverändert, aber die Anwendung kann ihre Berechtigungen in einen Aufruf mit lineSetCallPrivilege ändern.