função TSPI_lineGatherDigits (tspi.h)

Artigo
08/26/2023

A função TSPI_lineGatherDigits inicia a coleta em buffer de dígitos na chamada especificada. TAPI especifica um buffer no qual colocar os dígitos e o número máximo de dígitos a serem coletados.

Sintaxe

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

Parâmetros

hdCall

O identificador do provedor de serviços para a chamada na qual a coleta de dígitos deve ser executada. O estado de chamada de hdCall pode ser qualquer estado, exceto ocioso.

dwEndToEndID

Um identificador exclusivo e não interpretado da solicitação durante todo o tempo de vida, ou seja, até que a mensagem de LINE_GATHERDIGITS correspondente seja enviada. O provedor de serviços inclui esse identificador como um dos parâmetros na mensagem.

dwDigitModes

Os modos de dígito que devem ser monitorados. Esse parâmetro usa uma ou mais das seguintes constantes LINEDIGITMODE_.

Valor	Significado
LINEDIGITMODE_PULSE	Detecte dígitos como cliques audíveis que são o resultado do uso de sequências de pulso rotativo. Os dígitos válidos para o modo de pulso são '0' a '9'.
LINEDIGITMODE_DTMF	Detecte dígitos como tons DTMF. Os dígitos válidos para o modo DTMF são '0' a '9', 'A', 'B', 'C', 'D', '*', '#'.

lpsDigits

Um ponteiro para o buffer em que os dígitos detectados devem ser armazenados como caracteres de texto. O provedor de serviços pode, mas não é necessário, colocar dígitos no buffer um de cada vez à medida que eles são coletados. Quando a mensagem LINE_GATHERDIGITS é enviada, o conteúdo do buffer deve ser concluído. Se lpsDigits for especificado como NULL , a coleta de dígitos atualmente em andamento na chamada será cancelada e o parâmetro dwNumDigits será ignorado. Caso contrário, lpsDigits terá espaço para dígitos dwNumDigits .

dwNumDigits

O número de dígitos a serem coletados antes que uma mensagem de LINE_GATHERDIGITS seja enviada ao TAPI. O parâmetro dwNumDigits é ignorado quando lpsDigits é NULL. Essa função deverá retornar um LINEERR_INVALPARAM se dwNumDigits for zero.

lpszTerminationDigits

Ponteiro para uma cadeia de caracteres Unicode terminada em nulo de dígitos de terminação como caracteres de texto. Se um dos dígitos na cadeia de caracteres for detectado, esse dígito de terminação será acrescentado ao buffer, a coleção de dígitos será encerrada e a mensagem LINE_GATHERDIGITS será enviada ao TAPI.

Os caracteres válidos para o modo de pulso são '0' a '9'. Os caracteres válidos para o modo DTMF são '0' a '9', 'A', 'B', 'C', 'D', '*', '#'. Se esse ponteiro for NULL ou se apontar para uma cadeia de caracteres vazia, a função se comportará como se nenhum dígito de terminação tivesse sido fornecido.

dwFirstDigitTimeout

A duração do tempo em milissegundos em que o primeiro dígito é esperado. Se o primeiro dígito não for recebido nesse período, a coleção de dígitos será encerrada e uma mensagem de LINE_GATHERDIGITS será enviada ao TAPI. Um único caractere NULL é gravado no buffer, indicando que nenhum dígito foi recebido e a coleta de dígitos com o tempo limite do primeiro dígito encerrado. Os recursos do dispositivo de linha da chamada especificam o intervalo válido para esse parâmetro ou indica que não há suporte para tempos limite. Esse parâmetro não é validado pelo TAPI quando essa função é chamada.

dwInterDigitTimeout

A duração máxima do tempo em milissegundos entre dígitos consecutivos. Se nenhum dígito for recebido nesse período, a coleção de dígitos será encerrada e uma mensagem de LINE_GATHERDIGITS será enviada ao TAPI. Um único caractere NULL é gravado no buffer, indicando que um tempo limite de interdigit encerrou a coleta de dígitos. A estrutura LINEDEVCAPS deve especificar o intervalo válido para esse parâmetro ou indicar que não há suporte para tempos limite. Esse parâmetro não é validado pelo TAPI quando essa função é chamada.

Retornar valor

Retornará zero se a função for bem-sucedida ou um número de erro se ocorrer um erro. Os valores retornados possíveis são os seguintes:

LINEERR_INVALCALLHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALCALLSTATE, LINEERR_NOMEM, LINEERR_INVALTIMEOUT, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALDIGITMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALDIGITS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM.

Comentários

O provedor de serviços retornará LINEERR_INVALPARAM se o parâmetro dwNumDigits for inválido.

Essa função retornará zero (êxito) se a coleção de dígitos for iniciada corretamente; não se a coleção de dígitos tiver terminado. Em todos os casos em que um buffer parcial é retornado, dígitos válidos (se houver) são seguidos por um caractere NULL Unicode.

A coleção de dígitos pode ser encerrada das seguintes maneiras:

O número solicitado de dígitos pode ter sido coletado.
Um dos dígitos detectados corresponde a um dígito em szTerminationDigits antes que o número especificado de dígitos seja coletado. O dígito de terminação detectado também é colocado no buffer e o buffer parcial é retornado.
Um dos tempos limite expira. O dwFirstDigitTimeout expirará se o primeiro dígito não for recebido nesse período de tempo. O dwInterDigitTimout expirará se o segundo, terceiro, (e assim por diante) não for recebido dentro desse período do dígito detectado anteriormente e um buffer parcial for retornado.
Chamar essa operação novamente enquanto a coleção está em andamento. A sessão de coleção antiga é encerrada e o conteúdo do buffer antigo é indefinido. Para cancelar a coleta de dígitos sem iniciar outra operação, essa operação é invocada com lpsDigits iguais a NULL.

Embora essa função possa ser invocada em qualquer estado de chamada, exceto ocioso, os dígitos normalmente só podem ser coletados enquanto a chamada está no estado conectado .

A mensagem de LINE_GATHERDIGITS normalmente é enviada quando o buffer de dígitos é preenchido. Ele também é enviado quando buffers parciais são retornados devido a tempos limite ou dígitos de terminação correspondentes ou quando a solicitação é cancelada por meio de outro TSPI_lineGatherDigits solicitação na chamada. Somente uma solicitação de coleta de dígitos pode estar ativa por vez. O provedor de serviços deve encerrar qualquer operação de coleta pendente com uma mensagem LINE_GATHERDIGITS quando TSPI_lineGatherDigits é chamado.

Quando a operação associada a uma chamada para a função TSPI_lineGatherDigits é cancelada (por uma chamada subsequente para a função), o provedor de serviços copia todos os dígitos coletados até esse ponto para o buffer especificado na chamada original.

O TAPI pode usar TSPI_lineMonitorDigits para habilitar ou desabilitar a detecção de dígitos não permitidos. Sempre que um dígito é detectado dessa forma, uma mensagem LINE_MONITORDIGITS é enviada para TAPI. A detecção de dígitos armazenados em buffer (coletar dígitos) e não armazenados em buffer pode ser habilitada para a mesma chamada simultaneamente.

O provedor de serviços tem alguma variação na qualidade do tempo que usa para essa função, incluindo não fazer intervalos. A qualidade do tempo é relatada em LINEDEVCAPS, nos membros dwGatherDigitsMinTimeout e dwGatherDigitsMaxTimeout.

A função correspondente no nível TAPI não inclui o parâmetro formal dwEndToEndID. Nesse nível, não há marcação de ponta a ponta. O TAPI usa a marcação de ponta a ponta no nível do TSPI para distinguir uma TSPI_lineGatherDigits solicitação de outra.