Função lineGatherDigits (tapi.h)

Artigo
03/08/2023

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

Sintaxe

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

Parâmetros

hCall

Identificador para a chamada na qual os dígitos devem ser coletados. O aplicativo deve ser um proprietário da chamada. O estado de chamada de hCall pode ser qualquer estado.

dwDigitModes

Modos de dígito a serem monitorados. Esse parâmetro usa uma ou mais das constantes LINEDIGITMODE_.

lpsDigits

Ponteiro para o buffer em que os dígitos detectados devem ser armazenados como caracteres de texto. Os dígitos podem não aparecer no buffer um de cada vez à medida que são coletados. Somente depois que uma mensagem de LINE_GATHERDIGITS for recebida, o conteúdo do buffer será considerado válido. Se lpsDigits for NULL, a coleta de dígitos atualmente em andamento na chamada será encerrada e dwNumDigits será ignorado. Caso contrário, lpsDigits terá espaço para dígitos dwNumDigits .

dwNumDigits

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

lpszTerminationDigits

Cadeia de caracteres 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 aplicativo.

A lista de caracteres válidos depende da constante fornecida em dwDigitModes. Para obter uma lista dos caracteres válidos para cada modo possível, consulte Constantes LINEDIGITMODE_.

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

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á anulada e uma mensagem de LINE_GATHERDIGITS será enviada ao aplicativo. O buffer contém apenas o caractere NULL , indicando que nenhum dígito foi recebido e a coleta de dígitos com o tempo limite do primeiro dígito encerrado. Os recursos de dispositivo de linha da chamada especificam o intervalo válido para esse parâmetro ou indicam que não há suporte para tempos limite.

dwInterDigitTimeout

Duração máxima em milissegundos entre dígitos consecutivos. Se nenhum dígito for recebido nesse período, a coleção de dígitos será anulada e uma mensagem de LINE_GATHERDIGITS será enviada ao aplicativo. O buffer contém apenas os dígitos coletados até esse ponto seguidos por um caractere NULL , indicando que um tempo limite de interdigit encerrou a coleta de dígitos. Os recursos de dispositivo de linha da chamada especificam o intervalo válido para esse parâmetro ou indicam que não há suporte para tempos limite.

Valor retornado

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

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

Comentários

A coleção de dígitos é encerrada quando o número solicitado de dígitos é coletado. Ele também é encerrado quando 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.

Outra maneira de cancelar a coleta de dígitos ocorre quando 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.

Um quarto método para encerrar a coleção de dígitos é chamar essa função novamente enquanto a coleção está em andamento. A sessão de coleção antiga é encerrada, todos os dígitos coletados até esse ponto são copiados para o buffer fornecido da chamada anterior para essa função e o buffer é entregue quando a mensagem LINE_GATHERDIGITS é enviada ao aplicativo. O mecanismo para encerrar a coleta de dígitos sem iniciar outra coleta de dígitos é invocar essa função com lpsDigits igual a NULL.

Essa função será considerada bem-sucedida se a coleção de dígitos tiver sido 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 .

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

A mensagem LINE_GATHERDIGITS é enviada somente para o aplicativo que iniciou a solicitação. Ele também é enviado quando buffers parciais são retornados devido a tempos limite ou dígitos de término correspondentes ou quando a solicitação é cancelada por outra solicitação lineGatherDigits na chamada. Somente uma solicitação de gather-digits pode estar ativa em uma chamada a qualquer momento em todos os aplicativos que são proprietários da chamada. Dado o comportamento assíncrono da operação, um aplicativo que emite várias solicitações lineGatherDigits em sucessão rápida pode ser capaz de fazer isso e receber várias mensagens LINE_GATHERDIGITS posteriormente. Embora isso seja um comportamento incomum do aplicativo, o aplicativo é capaz de contar o número dessas mensagens para permitir que as mensagens de cancelamento sejam correspondidas às solicitações anteriores. De qualquer forma, somente a solicitação mais recente deve ser considerada válida.

Nota Quando um aplicativo invoca qualquer operação assíncrona que grava dados de volta na memória do aplicativo, o aplicativo deve manter essa memória disponível para gravação até que uma mensagem LINE_REPLY ou LINE_GATHERDIGITS seja recebida.

Um aplicativo pode usar 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 ao aplicativo. A detecção de dígitos armazenados em buffer e não armazenados em buffer pode ser habilitada simultaneamente para a mesma chamada.

A coleta de dígitos em uma chamada em conferência aplica-se somente ao hConfCall, não às chamadas individuais participantes.

Se a função lineGatherDigits for usada para cancelar uma solicitação anterior para coletar dígitos, a função copiará todos os dígitos coletados até esse ponto para o buffer especificado na chamada de função original. Em seguida, a função envia uma mensagem LINE_GATHERDIGITS para o aplicativo, independentemente de o parâmetro lpszDigits na segunda chamada especificar um endereço NULL ou diferente.