Funzione lineHandoffA (tapi.h)

La funzione lineHandoff assegna 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 lineHandoffA(
  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 un nullstringa con terminazione. Se questo parametro del puntatore non èNULL, contiene il nome file dell'applicazione che è la destinazione dell'handoff. Se NULL, la destinazione di handoff è l'applicazione con priorità più alta che ha aperto la riga per i privilegi 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 il handoff indiretto. Il parametro dwMediaMode identifica indirettamente l'applicazione di destinazione che riceve la proprietà della chiamata. Questo parametro viene ignorato se lpszFileName non è NULL. Questo parametro usa una sola costante LINEMEDIAMODE_.

Valore restituito

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

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

Osservazioni

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 è l'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 di LINECALLPRIVILEGE_OWNER nel parametro dwPrivileges di lineOpen. In alternativa, nel caso di handoff in modalità multimediale, 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 line, 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 ha esito positivo se l'handle di chiamata viene passato allo stesso nome 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 attualmente 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 di 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. Questo viene segnalato dal messaggio di 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 unknown e altri flag di modalità multimediale, 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 fa una determinazione per 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 passare la chiamata a UNKNOWN. Il finale lineHandoff ha esito negativo se l'applicazione è l'unico proprietario rimanente della chiamata. In questo modo l'applicazione informa che deve eliminare la chiamata e deallocare il relativo handle, nel qual caso la chiamata viene abbandonata. I privilegi dell'applicazione chiamante alla chiamata sono invariati da questa operazione, ma l'applicazione può modificare i privilegi di una chiamata con lineSetCallPrivilege.

Nota

L'intestazione tapi.h definisce lineHandoff come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Finestre
intestazione	tapi.h
libreria	Tapi32.lib
dll	Tapi32.dll

Vedere anche

di riferimento dei servizi di telefonia di base

Panoramica handoffs

LINECALLINFO

panoramica dei riferimenti TAPI 2.2

lineGetCallStatus

lineOpen

lineSetCallPrivilege

lineSetMediaMode