Funzione lineForward (tapi.h)

Articolo
03/13/2024

La funzione 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 deflezioni all'altro numero dall'opzione. Questa funzione fornisce una combinazione di funzionalità forward e do-not-disturb. Questa funzione può anche annullare l'inoltro attualmente attivo.

Sintassi

LONG lineForward(
  HLINE                   hLine,
  DWORD                   bAllAddresses,
  DWORD                   dwAddressID,
  LPLINEFORWARDLIST const lpForwardList,
  DWORD                   dwNumRingsNoAnswer,
  LPHCALL                 lphConsultCall,
  LPLINECALLPARAMS const  lpCallParams
);

Parametri

hLine

Handle per il dispositivo line.

bAllAddresses

Specifica se tutti gli indirizzi di origine nella riga o solo quello specificato devono essere inoltrati. Se TRUE, tutti gli indirizzi nella riga vengono inoltrati e dwAddressID viene ignorato; se FALSE, viene inoltrato solo l'indirizzo specificato come dwAddressID .

dwAddressID

Indirizzo sulla riga specificata le cui chiamate in ingresso devono essere inoltrate. Questo parametro viene ignorato se bAllAddresses è TRUE.

Un identificatore di indirizzo è associato in modo permanente a un indirizzo; l'identificatore rimane costante tra gli aggiornamenti del sistema operativo.

lpForwardList

Puntatore a una struttura di dati con dimensioni variabili che descrive le istruzioni di inoltro specifiche, di tipo LINEFORWARDLIST.

dwNumRingsNoAnswer

Numero di anelli prima che una chiamata venga considerata "nessuna risposta". Se dwNumRingsNoAnswer non è compreso nell'intervallo, il valore effettivo viene impostato sul valore più vicino nell'intervallo consentito.

lphConsultCall

Puntatore a una posizione HCALL. In alcuni ambienti di telefonia, questa posizione viene caricata con un handle per una chiamata di consultazione usata per consultare la parte a cui viene inoltrato e l'applicazione diventa l'unico proprietario iniziale di questa chiamata. Questo puntatore deve essere valido anche in ambienti in cui l'inoltro delle chiamate non richiede una chiamata di consultazione. Questo handle è impostato su NULL se non viene creata alcuna chiamata di consultazione.

lpCallParams

Puntatore a una struttura di tipo LINECALLPARAMS. Questo puntatore viene ignorato a meno che lineForward non richieda la creazione di una chiamata alla destinazione di inoltro (e viene restituito lphConsultCall , 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 hConsultCall.

Valore restituito

Restituisce un identificatore di richiesta positivo se la funzione viene completata in modo asincrono o un numero di errore negativo se si verifica un errore. Il parametro dwParam2 del messaggio di LINE_REPLY corrispondente è zero se la funzione ha esito positivo o è un numero di errore negativo se si verifica un errore. I valori restituiti possibili sono:

LINEERR_INVALLINEHANDLE, LINEERR_NOMEM, LINEERR_INVALADDRESSID, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESS, LINEERR_OPERATIONFAILED, LINEERR_INVALCOUNTRYCODE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPARAM, LINEERR_UNINITIALIZED.

Commenti

Un inoltro riuscito indica solo che la richiesta è stata accettata dal provider di servizi, non che l'inoltro viene configurato all'opzione. Un messaggio di LINE_ADDRESSSTATE (inoltro) fornisce conferma per l'inoltro configurato all'opzione.

L'inoltro dell'indirizzo (es) rimane attivo fino a quando questa funzione non viene chiamata di nuovo. L'elenco di inoltro più recente sostituisce quello precedente. L'inoltro può essere annullato specificando un puntatore NULL come lpForwardList. Se viene specificato un indirizzo di destinazione NULL per una voce nell'elenco di inoltro, l'operazione funge da non disturbo.

Lo stato di inoltro di un indirizzo può anche essere influenzato esternamente; ad esempio da azioni amministrative all'interruttore o da un utente da un'altra stazione. Potrebbe non essere possibile che il provider di servizi sia a conoscenza di questa modifica dello stato e potrebbe non essere in grado di mantenere la sincronizzazione con lo stato di inoltro noto all'opzione.

Poiché un provider di servizi potrebbe non conoscere lo stato di inoltro dell'indirizzo "sicuro", ovvero potrebbe essere stato inoltrato o non assegnato in modo sconosciuto, lineForward riesce 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 è attivo l'inoltro ha esito positivo. Ciò è dovuto al fatto che non esiste alcun "non responsabile": è possibile modificare solo il set precedente 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. Il provider deve "annullare tutto" prima di impostare le nuove istruzioni di inoltro. Poiché questo può richiedere tempo in ambienti di telefonia analogica, un provider può anche voler confrontare l'inoltro corrente con quello nuovo e rilasciare solo istruzioni per il passaggio per ottenere lo stato finale (lasciando invariato l'inoltro non interessato).

Richiamare lineForward quando LINEFORWARDLIST ha dwNumEntries impostato su zero ha lo stesso effetto di fornire un parametro nulllpForwardList . Annulla tutto l'inoltro attualmente in vigore.