funzione TSPI_lineForward (tspi.h)
La funzione TSPI_lineForward inoltra le chiamate destinate all'indirizzo specificato nella riga specificata, in base alle istruzioni di inoltro specificate. Quando viene inoltrato un indirizzo di origine (dwAddressID), le chiamate in ingresso specificate per tale indirizzo vengono deflesse all'altro numero dal commutatore. Questa funzione fornisce una combinazione di funzionalità forward e non disturbo. Questa funzione può anche annullare l'inoltro specifico attualmente in vigore.
Sintassi
LONG TSPIAPI TSPI_lineForward(
DRV_REQUESTID dwRequestID,
HDRVLINE hdLine,
DWORD bAllAddresses,
DWORD dwAddressID,
LPLINEFORWARDLIST const lpForwardList,
DWORD dwNumRingsNoAnswer,
HTAPICALL htConsultCall,
LPHDRVCALL lphdConsultCall,
LPLINECALLPARAMS const lpCallParams
);
Parametri
dwRequestID
Identificatore della richiesta asincrona.
hdLine
Handle del provider di servizi alla riga da inoltrare.
bAllAddresses
Specifica se tutti gli indirizzi di origine nella riga o solo uno specificato deve essere inoltrato. Se TRUE, tutti gli indirizzi nella riga vengono inoltrati e dwAddressID viene ignorato ; se FALSE, viene inoltrato solo l'indirizzo specificato come dwAddressID . Questo parametro non viene convalidato da TAPI quando questa funzione viene chiamata.
dwAddressID
Indirizzo nella riga specificata le cui chiamate in ingresso devono essere inoltrate. Questo parametro viene ignorato se bAllAddresses è TRUE. Questo parametro non viene convalidato da TAPI quando questa funzione viene chiamata.
Un identificatore di indirizzo è associato definitivamente a un indirizzo; l'identificatore rimane costante tra gli aggiornamenti del sistema operativo.
lpForwardList
Puntatore a una struttura di dati di dimensioni variabile di tipo LINEFORWARDLIST che descrive le istruzioni di inoltro specifiche.
dwNumRingsNoAnswer
Specifica il numero di anelli prima che una chiamata in ingresso venga considerata una "nessuna risposta". Se dwNumRingsNoAnswer non è compreso nell'intervallo, il valore effettivo viene impostato sul valore più vicino nell'intervallo consentito. Questo parametro non viene convalidato da TAPI quando questa funzione viene chiamata.
htConsultCall
L'handle TAPI a una nuova chiamata, se tale chiamata deve essere creata dal provider di servizi. In alcuni ambienti di telefonia, l'inoltro di una chiamata ha effetto collaterale della creazione di una chiamata di consultazione usata per consultare la parte a cui viene inoltrato. In tale ambiente, il provider di servizi crea la nuova chiamata di consultazione e deve salvare questo valore e usarlo in tutte le chiamate successive agli eventi di segnalazione delle procedure LINEEVENT sulla chiamata. Se non viene creata alcuna chiamata di consulenza, questo valore può essere ignorato dal provider di servizi.
lphdConsultCall
Puntatore a un HDRVCALL che rappresenta l'identificatore del provider di servizi per la chiamata. Negli ambienti di telefonia in cui l'inoltro di una chiamata ha effetto collaterale della creazione di una chiamata di consultazione usata per consultare la parte a cui viene inoltrato, il provider di servizi deve riempire questa posizione con il relativo handle per la chiamata prima che questa procedura venga restituita. Il provider di servizi è autorizzato a eseguire callback relativi alla nuova chiamata prima che venga restituita da questa procedura. Se non viene creata alcuna chiamata di consulenza, l'HDRVCALL deve essere lasciato NULL.
lpCallParams
Puntatore a una struttura di tipo LINECALLPARAMS. Questo puntatore viene ignorato dal provider di servizi, a meno che lineForward non richieda la creazione di una chiamata alla destinazione di inoltro (e viene restituito lphdConsultCall , nel qual caso lpCallParams è facoltativo). Se NULL, vengono usati i parametri di chiamata predefiniti. In caso contrario, i parametri di chiamata specificati vengono usati per stabilire htConsultCall.
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_NOMEM, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL.
Commenti
Il provider di servizi restituisce LINEERR_INVALPARAM se il parametro dell'elenco di inoltro specificato contiene informazioni non valide.
Il provider di servizi non esegue alcuna chiamata se restituisce LINEERR_INVALADDRESS.
Il provider di servizi restituisce l'esito positivo di questa funzione per indicare solo che la richiesta viene accettata dal provider di servizi, non che l'inoltro viene configurato all'opzione. Viene inviato un messaggio di LINE_ADDRESSSTATE (inoltro) per fornire che l'inoltro sia configurato all'opzione.
L'inoltro dell'indirizzo o degli indirizzi rimane effettivo fino a quando questa funzione non viene chiamata di nuovo. L'elenco di inoltro più recente sostituisce uno precedente in effetti. Se questa funzione viene chiamata, specificando un puntatore NULL come lpForwardList, il provider di servizi deve annullare qualsiasi inoltro eseguito in quel momento. Se viene specificato un indirizzo di destinazione NULL per una voce nell'elenco di inoltro, l'operazione funge da "do-not-disturb".
Lo stato di inoltro di un indirizzo può anche essere interessato esternamente, ad esempio tramite azioni amministrative all'opzione o da un utente da un'altra stazione. Potrebbe non essere possibile che il provider di servizi sia consapevole di questa modifica dello stato e potrebbe non essere in grado di mantenere sincronizzato lo stato di inoltro noto al commutatore. Il provider deve sempre indicare ciò che sa essere true e indicare che lo stato di inoltro è sconosciuto in caso contrario.
Poiché un provider di servizi potrebbe non conoscere lo stato di inoltro dell'indirizzo senza dubbio (ovvero, potrebbe essere stato inoltrato o non assegnato in modo sconosciuto), TSPI_lineForward ha esito positivo a meno che non riesca a impostare le nuove istruzioni di inoltro. In altre parole, una richiesta che tutto l'inoltro venga annullato alla volta in cui non è possibile inoltrare in effetti. Questo è dovuto al fatto che non c'è nulla di insoddisabile; è possibile richiamare solo un nuovo set di istruzioni di inoltro.
L'esito positivo o negativo di questa operazione non dipende dal set precedente di istruzioni di inoltro e lo stesso vale quando si impostano istruzioni di inoltro diverse. Se necessario, il provider deve "annullare tutto" prima di impostare le nuove istruzioni di inoltro. Poiché questo può richiedere tempo negli ambienti di telefonia analogica, un provider può anche voler confrontare l'inoltro corrente con quello nuovo e inviare solo istruzioni per l'opzione per passare allo stato finale (lasciando invariato l'inoltro non interessato).
Richiamare TSPI_lineForward quando LINEFORWARDLIST ha dwNumEntries impostato su zero ha lo stesso effetto di fornire un parametro NULLlpForwardList ; annulla tutto l'inoltro attualmente in vigore.
Poiché il valore NULL restituito in lphdConsultCall è l'unico modo per TAPI di determinare se il provider di servizi ha creato una chiamata di consulenza, il provider di servizi non può usare NULL come handle di chiamata.
Questa funzione differisce dalla funzione TAPI corrispondente in cui segue il modello TSPI per iniziare la durata di una chiamata. TAPI e gli handle opachi del provider di servizi che rappresentano la chiamata tra loro. Inoltre, il provider di servizi è autorizzato a eseguire callback per la nuova chiamata prima di restituire da questa procedura. In qualsiasi caso, il provider di servizi deve anche considerare l'handle restituito come "non ancora valido" fino a quando la corrispondenza ASYNC_COMPLETION segnala l'esito positivo. In altre parole, non deve inviare messaggi per la nuova chiamata o includerlo nei conteggi delle chiamate in messaggi o strutture di dati di stato per la riga.
Requisiti
| Requisito | Valore |
|---|---|
| Piattaforma di destinazione | Windows |
| Intestazione | tspi.h |