funzione TSPI_lineForward (tspi.h)

Articolo
03/13/2024

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.