funzione TSPI_lineGatherDigits (tspi.h)

Articolo
03/13/2024

La funzione TSPI_lineGatherDigits avvia la raccolta con buffer di cifre nella chiamata specificata. TAPI specifica un buffer in cui inserire le cifre e il numero massimo di cifre da raccogliere.

Sintassi

LONG TSPIAPI TSPI_lineGatherDigits(
  HDRVCALL hdCall,
  DWORD    dwEndToEndID,
  DWORD    dwDigitModes,
  LPWSTR   lpsDigits,
  DWORD    dwNumDigits,
  LPCWSTR  lpszTerminationDigits,
  DWORD    dwFirstDigitTimeout,
  DWORD    dwInterDigitTimeout
);

Parametri

hdCall

Handle del provider di servizi per la chiamata in cui deve essere eseguita la raccolta di cifre. Lo stato della chiamata di hdCall può essere qualsiasi stato, ad eccezione dell'inattività.

dwEndToEndID

Identificatore univoco non interpretato della richiesta per l'intera durata, ovvero fino all'invio del messaggio di LINE_GATHERDIGITS corrispondente. Il provider di servizi include questo identificatore come uno dei parametri del messaggio.

dwDigitModes

Modalità cifre da monitorare. Questo parametro usa una o più costanti di LINEDIGITMODE_ seguenti.

Valore	Significato
LINEDIGITMODE_PULSE	Rilevare le cifre come clic udibili che sono il risultato dell'uso di sequenze di impulsi rotanti. Le cifre valide per la modalità di impulso sono '0' fino a '9'.
LINEDIGITMODE_DTMF	Rilevare le cifre come toni DTMF. Le cifre valide per la modalità DTMF sono '0' a '9', 'A', 'B', 'C', 'D', '*', '#'.

lpsDigits

Puntatore al buffer in cui le cifre rilevate devono essere archiviate come caratteri di testo. Il provider di servizi può, ma non è necessario, inserire cifre nel buffer uno alla volta durante la raccolta. Quando viene inviato il messaggio LINE_GATHERDIGITS , è necessario completare il contenuto del buffer. Se lpsDigits viene specificato come NULL la raccolta di cifre attualmente in corso nella chiamata viene annullata e il parametro dwNumDigits viene ignorato. In caso contrario, si presuppone che lpsDigits abbia spazio per le cifre dwNumDigits .

dwNumDigits

Numero di cifre da raccogliere prima che venga inviato un messaggio di LINE_GATHERDIGITS a TAPI. Il parametro dwNumDigits viene ignorato quando lpsDigits è NULL. Questa funzione deve restituire un LINEERR_INVALPARAM se dwNumDigits è zero.

lpszTerminationDigits

Puntatore a una stringa Unicode con terminazione null di cifre di terminazione come caratteri di testo. Se viene rilevata una delle cifre nella stringa, tale cifra di terminazione viene aggiunta al buffer, la raccolta di cifre viene terminata e il messaggio di LINE_GATHERDIGITS viene inviato a TAPI.

I caratteri validi per la modalità di impulso sono '0' fino a '9'. I caratteri validi per la modalità DTMF sono '0' a '9', 'A', 'B', 'C', 'D', '*', '#'. Se questo puntatore è NULL o se punta a una stringa vuota, la funzione si comporta come se non siano state fornite cifre di terminazione.

dwFirstDigitTimeout

Durata del tempo in millisecondi in cui è prevista la prima cifra. Se la prima cifra non viene ricevuta in questo intervallo di tempo, la raccolta cifre viene terminata e viene inviato un messaggio di LINE_GATHERDIGITS a TAPI. Un singolo carattere NULL viene scritto nel buffer, che indica che non sono state ricevute cifre e la prima raccolta di cifre di timeout terminato. Le funzionalità del dispositivo della linea della chiamata specifica l'intervallo valido per questo parametro o indica che i timeout non sono supportati. Questo parametro non viene convalidato da TAPI quando questa funzione viene chiamata.

dwInterDigitTimeout

Durata massima in millisecondi tra cifre consecutive. Se non viene ricevuta alcuna cifra in questo intervallo di tempo, la raccolta cifre viene terminata e viene inviato un messaggio LINE_GATHERDIGITS a TAPI. Un singolo carattere NULL viene scritto nel buffer, che indica che una raccolta di cifre terminate interdigit timeout. La struttura LINEDEVCAPS deve specificare l'intervallo valido per questo parametro o indicare che i timeout non sono supportati. Questo parametro non viene convalidato da TAPI quando questa funzione viene chiamata.

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_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.

Commenti

Il provider di servizi restituisce LINEERR_INVALPARAM se il parametro dwNumDigits non è valido.

Questa funzione restituisce zero (esito positivo) se la raccolta di cifre viene avviata correttamente; non se la raccolta cifre è stata terminata. In tutti i casi in cui viene restituito un buffer parziale, le cifre valide (se presenti) sono seguite da un carattere NULL Unicode.

La raccolta cifre può essere terminata nei modi seguenti:

Il numero richiesto di cifre può essere stato raccolto.
Una delle cifre rilevate corrisponde a una cifra in szTerminationDigits prima della raccolta del numero specificato di cifre. La cifra di terminazione rilevata viene inserita anche nel buffer e viene restituito il buffer parziale.
Uno dei timeout scade. Il dwFirstDigitTimeout scade se la prima cifra non viene ricevuta in questo periodo di tempo. Il dwInterDigitTimout scade se la seconda, terza e così via non viene ricevuta entro quel periodo di tempo dalla cifra rilevata in precedenza e viene restituito un buffer parziale.
Chiamare di nuovo questa operazione mentre la raccolta è in corso. La sessione di raccolta precedente viene terminata e il contenuto del buffer precedente non è definito. Per annullare la raccolta cifre senza avviare un'altra operazione, questa operazione viene richiamata con lpsDigits uguale a NULL.

Anche se questa funzione può essere richiamata in qualsiasi stato di chiamata, ad eccezione dell'inattività, le cifre possono in genere essere raccolte solo mentre la chiamata si trova nello stato connesso .

Il messaggio LINE_GATHERDIGITS viene normalmente inviato quando il buffer di cifre viene riempito. Viene inoltre inviato quando vengono restituiti buffer parziali a causa di timeout o cifre di terminazione corrispondenti oppure quando la richiesta viene annullata tramite un'altra richiesta TSPI_lineGatherDigits richiesta nella chiamata. Una sola richiesta di raccolta cifre può essere attiva alla volta. Il provider di servizi deve terminare qualsiasi operazione di raccolta in sospeso con un messaggio di LINE_GATHERDIGITS quando viene chiamato TSPI_lineGatherDigits .

Quando l'operazione associata a una chiamata alla funzione TSPI_lineGatherDigits viene annullata (da una chiamata successiva alla funzione), il provider di servizi copia tutte le cifre raccolte fino a quel punto del buffer specificato nella chiamata originale.

TAPI può usare TSPI_lineMonitorDigits per abilitare o disabilitare il rilevamento delle cifre non memorizzate. Ogni volta che viene rilevata una cifra in questo modo, viene inviato un messaggio LINE_MONITORDIGITS a TAPI. Entrambi i dati memorizzati nel buffer (raccogliere cifre) e il rilevamento delle cifre non memorizzate possono essere abilitati contemporaneamente per la stessa chiamata.

Il provider di servizi è consentito alcune variazioni nella qualità dei tempi che usa per questa funzione, tra cui non esegue i tempi. La qualità dei tempi viene segnalata in LINEDEVCAPS nei membri dwGatherDigitsMinTimeout e dwGatherDigitsMaxTimeout.

La funzione corrispondente a livello TAPI non include il parametro formale dwEndToEndID. A questo livello non esiste alcun contrassegno end-to-end. TAPI usa il contrassegno end-to-end a livello TSPI per distinguere una richiesta TSPI_lineGatherDigits da un'altra.