funzione TSPI_lineMonitorMedia (tspi.h)

Articolo
03/09/2024

La funzione TSPI_lineMonitorMedia abilita e disabilita il rilevamento dei tipi di supporti nella chiamata specificata. Quando viene rilevato un tipo di supporto, un messaggio di LINE_MONITORMEDIA viene inviato a TAPI.

Sintassi

LONG TSPIAPI TSPI_lineMonitorMedia(
  HDRVCALL hdCall,
  DWORD    dwMediaModes
);

Parametri

hdCall

Handle per la chiamata per la quale deve essere impostato il monitoraggio multimediale. Lo stato della chiamata di hdCall può essere qualsiasi stato, ad eccezione dell'inattività.

dwMediaModes

Tipi di supporti da monitorare. Il parametro dwMediaModes può avere una delle costanti LINEMEDIAMODE_.

Il valore 0 annulla il monitoraggio di tutti i tipi di supporto.

Valore restituito

Restituisce zero se la funzione ha esito positivo o un numero di errore se si verifica un errore. I valori restituiti possibili sono i seguenti:

LINEERR_INVALCALLHANDLE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_OPERATIONFAILED, LINEERR_INVALMEDIAMODE, LINEERR_RESOURCEUNAVAIL LINEERR_NOMEM.

Commenti

Il provider di servizi restituisce LINEERR_INVALMEDIAMODE se l'elenco dei tipi di supporti da monitorare contiene informazioni non valide.

Questa funzione restituisce zero (esito positivo) quando il monitoraggio del tipo di supporto è stato avviato correttamente, non quando il monitoraggio del tipo di supporto è terminato. Il monitoraggio multimediale per un determinato tipo di supporto rimane attivo fino a quando non viene disabilitato in modo esplicito chiamando TSPI_lineMonitorMedia con un parametro dwMediaModes con il tipo di supporto impostato su zero o fino a quando la chiamata non passa a inattiva.

TSPI_lineMonitorMedia è principalmente un meccanismo di segnalazione degli eventi. Il tipo di supporto di una chiamata, come indicato in LINECALLINFO, non è interessato dal rilevamento del tipo di supporto del provider di servizi. Solo TAPI o un'applicazione client possono modificare il tipo di supporto indicato di una chiamata usando TSPI_lineSetMediaMode. L'uso effettivo di un particolare tipo di supporto avviene tramite API di flusso multimediale separate, ad esempio Comm o WAVE.

Il monitoraggio multimediale predefinito eseguito dal provider di servizi per un nuovo aspetto di chiamata corrisponde all'unione di tutti i tipi di supporti specificati da TSPI_lineSetDefaultMediaDetection. Poco dopo la creazione di una nuova chiamata, TAPI chiama in genere TSPI_lineMonitorMedia per ridurre il set di tipi multimediali rilevati e segnalati per questa chiamata all'unione di tutti i tipi di supporti desiderati dalle applicazioni client della chiamata.

Il provider di servizi deve annullare il monitoraggio multimediale quando una chiamata passa inattiva. TAPI deve calcolare l'unione dei tipi di supporti desiderati da tutti i client e passare il risultato a questa funzione. Il provider di servizi usa il set passato a questa funzione da TAPI.

Anche se questa funzione può essere richiamata in qualsiasi stato di chiamata, il tipo di supporto di una chiamata può in genere essere rilevato solo mentre la chiamata è in determinati stati di chiamata. Questi stati possono essere specifici del dispositivo. Ad esempio, in ISDN un messaggio può indicare il tipo di supporto del flusso multimediale prima che il flusso multimediale esista. Analogamente, è possibile usare informazioni distintive sull'anello o sull'ID chiamato per identificare il tipo di supporto di una chiamata. In caso contrario, potrebbe essere necessario rispondere alla chiamata (chiamata nello stato connesso ) per consentire a un provider di servizi di determinare il tipo di supporto della chiamata filtrando il flusso multimediale. Poiché il filtro del flusso multimediale di una chiamata implica un sovraccarico di calcolo, TAPI usa in genere questa procedura per disabilitare il monitoraggio multimediale quando non è necessario.

Poiché il rilevamento in modalità multimediale abilitato da TSPI_lineMonitorMedia viene implementato come operazione di sola lettura del flusso multimediale della chiamata, non comporta interruzioni. Nessun segnale viene inviato sulla riga in seguito all'impostazione TSPI_lineMonitorMedia.

Per quanto riguarda il tipo di supporto passato, TAPI garantisce che non ci siano bit riservati impostati. Il provider di servizi deve eseguire ulteriori controlli di validità sui tipi di supporti, ad esempio per verificare se i tipi di supporti sono effettivamente supportati dal provider di servizi.