Funzione lineGatherDigits (tapi.h)

Articolo
08/26/2023

La funzione lineGatherDigits avvia la raccolta memorizzata nel buffer delle cifre nella chiamata specificata. L'applicazione specifica un buffer in cui inserire le cifre e il numero massimo di cifre da raccogliere.

Sintassi

LONG lineGatherDigits(
  HCALL  hCall,
  DWORD  dwDigitModes,
  LPSTR  lpsDigits,
  DWORD  dwNumDigits,
  LPCSTR lpszTerminationDigits,
  DWORD  dwFirstDigitTimeout,
  DWORD  dwInterDigitTimeout
);

Parametri

hCall

Gestire la chiamata su cui raccogliere le cifre. L'applicazione deve essere un proprietario della chiamata. Lo stato della chiamata di hCall può essere qualsiasi stato.

dwDigitModes

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

lpsDigits

Puntatore al buffer in cui le cifre rilevate devono essere archiviate come caratteri di testo. Le cifre potrebbero non essere visualizzate nel buffer uno alla volta durante la raccolta. Solo dopo la ricezione di un messaggio di LINE_GATHERDIGITS deve essere valido il contenuto del buffer. Se lpsDigits è NULL, la raccolta di cifre attualmente in corso sulla chiamata viene terminata e dwNumDigits viene ignorata. In caso contrario, si presuppone che lpsDigits abbia spazio per le cifre dwNumDigits .

dwNumDigits

Numero di cifre da raccogliere prima dell'invio di un messaggio LINE_GATHERDIGITS all'applicazione. Il parametro dwNumDigits viene ignorato quando lpsDigits è NULL. Questa funzione ha esito negativo se dwNumDigits è zero.

lpszTerminationDigits

Stringa con terminazione Null delle 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 LINE_GATHERDIGITS viene inviato all'applicazione.

L'elenco di caratteri validi dipende dalla costante fornita in dwDigitModes. Per un elenco dei caratteri validi per ogni modalità possibile, vedere LINEDIGITMODE_ Costanti.

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 in millisecondi in cui è prevista la prima cifra. Se la prima cifra non viene ricevuta in questo intervallo di tempo, la raccolta di cifre viene interrotta e all'applicazione viene inviato un messaggio di LINE_GATHERDIGITS . Il buffer contiene solo il carattere NULL , a indicare che non sono state ricevute cifre e che il primo timeout di timeout termina la raccolta di cifre. Le funzionalità line-device della chiamata specificano l'intervallo valido per questo parametro o indicano che i timeout non sono supportati.

dwInterDigitTimeout

Durata massima in millisecondi tra cifre consecutive. Se non viene ricevuta alcuna cifra in questo intervallo di tempo, la raccolta di cifre viene interrotta e viene inviato un messaggio LINE_GATHERDIGITS all'applicazione. Il buffer contiene solo le cifre raccolte fino a questo punto seguito da un carattere NULL , che indica che una raccolta di cifre con terminazione di timeout interdigit. Le funzionalità line-device della chiamata specificano l'intervallo valido per questo parametro o indicano che i timeout non sono supportati.

Valore restituito

Restituisce zero se la richiesta ha esito positivo o negativo se si verifica un errore. I valori restituiti possibili sono:

LINEERR_INVALCALLHANDLE, LINEERR_NOMEM, LINEERR_INVALCALLSTATE, LINEERR_NOTOWNER, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITS, LINEERR_OPERATIONFAILED, LINEERR_INVALPARAM, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED.

Commenti

La raccolta di cifre viene terminata quando è stato raccolto il numero di cifre richiesto. Viene inoltre terminato quando una delle cifre rilevate corrisponde a una cifra in szTerminationDigits prima che sia stato raccolto il numero specificato di cifre. La cifra di terminazione rilevata viene inserita anche nel buffer e viene restituito il buffer parziale.

Un altro modo per annullare la raccolta di cifre si verifica alla scadenza di uno dei timeout. DwFirstDigitTimeout scade se la prima cifra non viene ricevuta in questo periodo di tempo. Il valore dwInterDigitTimout scade se la seconda, la terza e così via non viene ricevuta entro tale periodo di tempo dalla cifra rilevata in precedenza e viene restituito un buffer parziale.

Un quarto metodo per terminare la raccolta di cifre consiste nel chiamare di nuovo questa funzione mentre la raccolta è in corso. La sessione di raccolta precedente viene terminata, tutte le cifre raccolte fino a quel punto vengono copiate nel buffer fornito dalla chiamata precedente a questa funzione e il buffer viene recapitato quando il messaggio LINE_GATHERDIGITS viene inviato all'applicazione. Il meccanismo di terminazione della raccolta di cifre senza avviare un'altra raccolta delle cifre consiste nel richiamare questa funzione con lpsDigits uguale a NULL.

Questa funzione viene considerata corretta se la raccolta di cifre è stata avviata correttamente, non se la raccolta di 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 .

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

Il messaggio LINE_GATHERDIGITS viene inviato solo all'applicazione che ha avviato la richiesta. Viene inviato anche quando vengono restituiti buffer parziali a causa di timeout o cifre di terminazione corrispondenti oppure quando la richiesta viene annullata da un'altra richiesta lineGatherDigits sulla chiamata. Una sola richiesta di raccolta cifre può essere attiva in una chiamata in qualsiasi momento in tutte le applicazioni proprietari della chiamata. Dato il comportamento asincrono dell'operazione, un'applicazione che emette più richieste lineGatherDigits in rapida successione può essere in grado di farlo e ricevere più messaggi LINE_GATHERDIGITS in un secondo momento. Anche se si tratta di un comportamento insolito dell'applicazione, l'applicazione è in grado di contare il numero di questi messaggi per consentire la corrispondenza dei messaggi di annullamento con le richieste precedenti. In ogni caso, si presuppone che solo la richiesta più recente sia valida.

Nota Quando un'applicazione richiama qualsiasi operazione asincrona che scrive di nuovo i dati nella memoria dell'applicazione, l'applicazione deve mantenere tale memoria disponibile per la scrittura fino a quando non viene ricevuto un messaggio di LINE_REPLY o LINE_GATHERDIGITS .

Un'applicazione può usare lineMonitorDigits per abilitare o disabilitare il rilevamento delle cifre non memorizzate nel buffer. Ogni volta che viene rilevata una cifra in questo modo, all'applicazione viene inviato un messaggio LINE_MONITORDIGITS . Il rilevamento delle cifre memorizzate nel buffer e senza buffer può essere abilitato contemporaneamente per la stessa chiamata.

La raccolta di cifre in una conferenza telefonica si applica solo alla chiamata hConfCall, non alle singole chiamate partecipanti.

Se la funzione lineGatherDigits viene usata per annullare una richiesta precedente per raccogliere cifre, la funzione copia tutte le cifre raccolte fino al buffer specificato nella chiamata di funzione originale. La funzione invia quindi un messaggio LINE_GATHERDIGITS all'applicazione, indipendentemente dal fatto che il parametro lpszDigits nella seconda chiamata specifichi un indirizzo NULL o diverso.