Funzione lineHandoff (tapi.h)

Articolo
03/05/2024

La funzione lineHandoff fornisce la proprietà della chiamata specificata a un'altra applicazione. L'applicazione può essere specificata direttamente dal nome del file o indirettamente come applicazione con priorità più alta che gestisce le chiamate della modalità multimediale specificata.

Sintassi

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

Parametri

hCall

Gestire la chiamata da consegnare. L'applicazione deve essere un proprietario della chiamata. Lo stato della chiamata di hCall può essere qualsiasi stato.

lpszFileName

Puntatore a una stringa con terminazione Null. Se questo parametro del puntatore non è NULL, contiene il nome file dell'applicazione che rappresenta la destinazione dell'handoff. Se NULL, la destinazione di handoff è l'applicazione con priorità più alta che ha aperto la riga per il privilegio di proprietario per la modalità multimediale specificata. Un nome di file valido non include il percorso del file.

dwMediaMode

Modalità multimediale usata per identificare la destinazione per l'handoff indiretto. Il parametro dwMediaMode identifica indirettamente l'applicazione di destinazione che deve ricevere la proprietà della chiamata. Questo parametro viene ignorato se lpszFileName non è NULL. Questo parametro usa uno e solo uno dei costanti LINEMEDIAMODE_.

Valore restituito

Restituisce zero se la richiesta ha esito positivo o negativo se si verifica un errore. I valori restituiti possibili sono:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_TARGETNOTFOUND, LINEERR_INVALPOINTER, LINEERR_TARGETSELF, LINEERR_NOMEM, LINEERR_UNINITIALIZED LINEERR_NOTOWNER.

Commenti

La funzione lineHandoff restituisce LINEERR_TARGETSELF se l'applicazione chiamante ha tentato un handoff indiretto(ovvero, impostare il parametro lpszFileName su NULL) e TAPI ha determinato che l'applicazione è la stessa applicazione con priorità più alta per la modalità multimediale specificata. Se viene restituito LINEERR_TARGETNOTFOUND, non è stata trovata una destinazione per il call handoff. Ciò può verificarsi se l'applicazione denominata non ha aperto la stessa riga con il bit LINECALLPRIVILEGE_OWNER nel parametro dwPrivileges di lineOpen. In alternativa, nel caso dell'handoff in modalità media, nessuna applicazione ha aperto la stessa riga con il bit LINECALLPRIVILEGE_OWNER nel parametro dwPrivileges di lineOpen e con la modalità multimediale specificata nel parametro dwMediaModes di lineOpen.

Call handoff consente di passare la proprietà di una chiamata tra le applicazioni. Esistono due tipi di handoff. Nel primo tipo, se l'applicazione conosce il nome file dell'applicazione di destinazione, può semplicemente specificare tale nome file. Se un'istanza dell'applicazione di destinazione ha aperto il dispositivo linea, la proprietà della chiamata viene passata all'altra applicazione; in caso contrario, l'handoff ha esito negativo e viene restituito un errore. Questa forma di handoff riesce se l'handle di chiamata viene passato allo stesso nome di file dell'applicazione che richiede l'handoff.

Il secondo tipo di handoff è basato sulla modalità multimediale. In questo caso, l'applicazione specifica indirettamente l'applicazione di destinazione tramite una modalità multimediale. L'applicazione con priorità più alta che ha aperto il dispositivo linea per tale modalità multimediale è la destinazione per l'handoff. Se non esiste un'applicazione di questo tipo, l'handoff ha esito negativo e viene restituito un errore.

La funzione lineHandoff non modifica la modalità multimediale di una chiamata. Per modificare la modalità multimediale di una chiamata, l'applicazione deve usare lineSetMediaMode nella chiamata, specificando la nuova modalità multimediale. In questo modo la modalità multimediale della chiamata viene modificata come archiviata nella struttura LINECALLINFO della chiamata.

Se l'handoff ha esito positivo, l'applicazione ricevente riceve un messaggio LINE_CALLSTATE per la chiamata. Questo messaggio indica che l'applicazione ricevente ha il privilegio di proprietario per la chiamata (dwParam3). Inoltre, il numero di proprietari e/o monitoraggi per la chiamata potrebbe essere cambiato. Viene segnalato dal messaggio LINE_CALLINFO e l'applicazione ricevente può quindi richiamare lineGetCallStatus e lineGetCallInfo per recuperare altre informazioni sulla chiamata ricevuta.

L'applicazione ricevente deve prima controllare la modalità multimediale in LINECALLINFO. Se viene impostato solo un singolo flag di modalità multimediale, la chiamata è ufficialmente di tale modalità multimediale e l'applicazione può agire di conseguenza. Se vengono impostati flag di modalità multimediale UNKNOWN e altri supporti, la modalità multimediale della chiamata è ufficialmente UNKNOWN, ma si presuppone che sia una delle modalità multimediali per cui viene impostato un flag in LINECALLINFO. L'applicazione deve presupporre che debba eseguire il probe per la modalità multimediale con priorità più alta.

Se il probe ha esito positivo (per tale modalità multimediale o per un altro), l'applicazione deve impostare il membro della modalità multimediale in LINECALLINFO sulla modalità supporto singola riconosciuta. Se il flag della modalità multimediale corrisponde alla modalità multimediale LINECALLINFO , l'applicazione può agire di conseguenza. Se determina un'altra modalità multimediale, deve prima passare la chiamata a tale modalità multimediale.

Se il probe ha esito negativo, l'applicazione deve cancellare il flag della modalità multimediale corrispondente in LINECALLINFO e consegnare la chiamata, specificando dwMediaMode come LINEMEDIAMODE_UNKNOWN. Deve anche deallocare il relativo handle di chiamata (o ripristinare il monitoraggio).

Se nessuna delle modalità multimediali ha avuto esito positivo nell'effettuare una determinazione, solo il flag UNKNOWN rimane impostato nel campo modalità multimediale di LINECALLINFO al momento in cui l'applicazione multimediale tenta di consegnare la chiamata a UNKNOWN. Il valore lineHandoff finale ha esito negativo se l'applicazione è l'unico proprietario rimanente della chiamata. In questo modo l'applicazione deve eliminare la chiamata e deallocare il relativo handle, nel qual caso la chiamata viene abbandonata. I privilegi dell'applicazione che richiama la chiamata alla chiamata sono invariati da questa operazione, ma l'applicazione può modificare i propri privilegi in una chiamata con lineSetCallPrivilege.