funzione TSPI_lineSetTerminal (tspi.h)

Articolo
03/08/2023

La funzione TSPI_lineSetTerminal consente a TAPI di specificare a quali informazioni sul terminale correlate alla riga, all'indirizzo o alla chiamata specificati deve essere instradata. Questa operazione può essere usata mentre le chiamate sono in corso sulla riga, per consentire l'instradare gli eventi a dispositivi diversi in base alle esigenze.

Sintassi

LONG TSPIAPI TSPI_lineSetTerminal(
  DRV_REQUESTID dwRequestID,
  HDRVLINE      hdLine,
  DWORD         dwAddressID,
  HDRVCALL      hdCall,
  DWORD         dwSelect,
  DWORD         dwTerminalModes,
  DWORD         dwTerminalID,
  DWORD         bEnable
);

Parametri

dwRequestID

Identificatore della richiesta asincrona.

hdLine

Handle di una riga.

dwAddressID

Indirizzo nel dispositivo open line specificato. Un identificatore di indirizzo è associato in modo permanente a un indirizzo; l'identificatore rimane costante tra gli aggiornamenti del sistema operativo. TAPI non convalida questo parametro quando viene chiamata questa funzione.

hdCall

Handle di una chiamata. Lo stato della chiamata può essere qualsiasi stato (se dwSelect è LINECALLSELECT_CALL).

dwSelect

Specifica se l'impostazione del terminale viene richiesta per la riga, l'indirizzo o solo la chiamata specificata. Se si specifica la riga o l'indirizzo, gli eventi si applicano alla riga o all'indirizzo stesso oppure fungono da impostazione iniziale predefinita per tutte le nuove chiamate nella riga o nell'indirizzo. Questo parametro usa una delle costanti LINECALLSELECT_.

dwTerminalModes

Classe(es) di eventi di basso livello da instradare al terminale specificato. Utilizzare una delle costanti LINETERMMODE_ per questo parametro.

dwTerminalID

Identificatore del dispositivo terminale in cui devono essere indirizzati gli eventi specificati. Gli identificatori del terminale sono numeri interi di piccole dimensioni nell'intervallo compreso tra 0 e dwNumTerminals meno uno, dove dwNumTerminals e le modalità del terminale ogni terminale è in grado di gestire sono indicati dal provider di servizi in LINEDEVCAPS.

Nota Questi identificatori del terminale non hanno alcuna relazione con altri identificatori di dispositivo e sono definiti dal provider di servizi tramite le funzionalità del dispositivo. TAPI non convalida questo parametro quando viene chiamata questa funzione.

bEnable

Se TRUE, dwTerminalID è valido e le classi di evento specificate vengono instradate a o da tale terminale. Se FALSE, questi eventi non vengono indirizzati a o da dwTerminalID. TAPI non convalida questo parametro quando viene chiamata questa funzione.

Valore restituito

Restituisce dwRequestID o un numero di errore se si verifica un errore. Il parametro effettivo lResult del ASYNC_COMPLETION corrispondente è 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_INVALLINEHANDLE, LINEERR_INVALTERMINALID, LINEERR_INVALADDRESSID, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSELECT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALTERMINALMODE, LINEERR_OPERATIONFAILED.

Commenti

Il provider di servizi restituisce LINEERR_RESOURCEUNAVAIL se l'operazione non può essere completata a causa dell'overcommit delle risorse o se sono impostati troppi terminali, a causa di limitazioni hardware o di provider di servizi/driver di dispositivo.

TAPI può usare questa operazione per instradare determinate classi di eventi di riga di basso livello al dispositivo terminale specificato o per eliminare completamente il routing di questi eventi. Ad esempio, la voce può essere instradata a un dispositivo di I/O audio separato (visore VR), le lampade e gli eventi di visualizzazione possono essere indirizzati al dispositivo telefonico locale e gli eventi del pulsante e gli eventi del ringer possono essere eliminati del tutto.

I toni di avanzamento delle chiamate e/o i messaggi vengono indirizzati alla stessa posizione dei supporti. Ad esempio, se i segnali audio vengono inviati al telefono, quindi sono segnali occupati (analogici) o Q.931 che indicano occupato (digitale).

Il provider di servizi deve determinare se le combinazioni di dwSelect e dwTerminalModes sono legali.

Questa operazione può essere chiamata in qualsiasi momento, anche quando una chiamata è attiva nel dispositivo di riga specificato. Questo, ad esempio, consente a un utente di passare dall'uso del telefono locale impostato su un altro dispositivo di I/O audio.

Questa funzione può essere chiamata più volte per instradare gli stessi eventi a più terminali contemporaneamente. Per reindirizzare gli eventi a un terminale diverso, TAPI consiglia di disabilitare prima il routing al terminale esistente e instradare gli eventi al nuovo terminale. Tuttavia, il provider di servizi deve impegnarsi al meglio per soddisfare le richieste dell'applicazione in qualsiasi sequenza.

Le assegnazioni degli identificatori del terminale vengono effettuate dal provider di servizi e LINEDEVCAPS indica quali identificatori del terminale sono disponibili per il provider di servizi. I provider di servizi che non supportano questo tipo di routing eventi indicano che non hanno dispositivi terminal (dwNumTerminals in LINEDEVCAPS è impostato su zero).

LineSetTerminal su una riga o un indirizzo influisce su tutte le chiamate esistenti su tale riga o indirizzo, ma non influisce sulle chiamate su altri indirizzi. Imposta anche l'impostazione predefinita per le chiamate future su tale riga o indirizzo. Una riga o un indirizzo con più chiamate connesse attive in qualsiasi momento può avere un routing diverso per ogni chiamata.

La disabilitazione del routing di eventi di basso livello a un terminale quando questi eventi non vengono attualmente indirizzati a o da tale terminale non è necessario generare un errore finché la funzione ha esito positivo, gli eventi specificati non vengono instradati a o da tale terminale.