Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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 lineGatherDigitsA(
HCALL hCall,
DWORD dwDigitModes,
LPSTR lpsDigits,
DWORD dwNumDigits,
LPCSTR lpszTerminationDigits,
DWORD dwFirstDigitTimeout,
DWORD dwInterDigitTimeout
);
Parâmetros
hCall
Manipule 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 em andamento na chamada será encerrada e dwNumDigits será ignorado. Caso contrário, lpsDigits terá espaço para dwNumDigits dígitos.
dwNumDigits
Número de dígitos a serem coletados antes que uma mensagem de LINE_GATHERDIGITS seja enviada ao aplicativo. O parâmetro dwNumDigits
lpszTerminationDigits
cadeia de caracteres nuloterminada 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 LINEDIGITMODE_ Constantes.
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 neste 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
dwInterDigitTimeout
Duração máxima de tempo em milissegundos entre dígitos consecutivos. Se nenhum dígito for recebido neste 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
Valor de retorno
Retornará zero se a solicitação for bem-sucedida ou um número de erro negativo se ocorrer um erro. Os possíveis valores retornados 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.
Observações
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 expira se o primeiro dígito não for recebido nesse período de tempo. O dwInterDigitTimout expirar se o segundo, o terceiro, (e assim por diante) não for recebido nesse período de tempo 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 sido encerrada. 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 estiver no estado conectado.
A mensagem LINE_GATHERDIGITS é enviada apenas 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 terminação correspondentes ou quando a solicitação é cancelada por outro lineGatherDigits solicitação na chamada. Apenas uma solicitação de coleta de dígitos pode estar ativa em uma chamada a qualquer momento em todos os aplicativos que são proprietários da chamada. Considerando o comportamento assíncrono da operação, um aplicativo que emite vários lineGatherDigits solicitações em rápida sucessão pode ser capaz de fazer isso e receber várias mensagens LINE_GATHERDIGITS mais tarde. 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.
Observação 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.
A coleta de dígitos em uma chamada em conferência aplica-se apenas ao hConfCall, não às chamadas participantes individuais.
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 especifica um NULL ou endereço diferente.
Nota
O cabeçalho tapi.h define lineGatherDigits como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| da Plataforma de Destino |
Windows |
| cabeçalho | tapi.h |
| biblioteca | Tapi32.lib |
| de DLL |
Tapi32.dll |
Consulte também
Funções de serviço de linha suplementar