Función lineGatherDigits (tapi.h)

Artículo
08/26/2023

La función lineGatherDigits inicia la recopilación almacenada en búfer de dígitos en la llamada especificada. La aplicación especifica un búfer en el que se van a colocar los dígitos y el número máximo de dígitos que se van a recopilar.

Sintaxis

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

Parámetros

hCall

Controle la llamada en la que se van a recopilar los dígitos. La aplicación debe ser propietario de la llamada. El estado de llamada de hCall puede ser cualquier estado.

dwDigitModes

Modos de dígito que se van a supervisar. Este parámetro usa una o varias de las LINEDIGITMODE_ Constantes.

lpsDigits

Puntero al búfer donde se almacenarán los dígitos detectados como caracteres de texto. Es posible que los dígitos no aparezcan en el búfer de uno en uno cuando se recopilan. Solo después de recibir un mensaje de LINE_GATHERDIGITS debe asumirse que el contenido del búfer es válido. Si lpsDigits es NULL, se termina la recopilación de dígitos actualmente en curso en la llamada y se omite dwNumDigits . De lo contrario, se supone que lpsDigits tiene espacio para los dígitos dwNumDigits .

dwNumDigits

Número de dígitos que se van a recopilar antes de enviar un mensaje de LINE_GATHERDIGITS a la aplicación. El parámetro dwNumDigits se omite cuando lpsDigits es NULL. Esta función produce un error si dwNumDigits es cero.

lpszTerminationDigits

Cadena terminada en null de dígitos de terminación como caracteres de texto. Si se detecta uno de los dígitos de la cadena, ese dígito de terminación se anexa al búfer, se termina la colección de dígitos y el mensaje LINE_GATHERDIGITS se envía a la aplicación.

La lista de caracteres válidos depende de la constante proporcionada en dwDigitModes. Para obtener una lista de los caracteres válidos para cada modo posible, consulte LINEDIGITMODE_ Constantes.

Si este puntero es NULL o si apunta a una cadena vacía, la función se comporta como si no se proporcionaran dígitos de terminación.

dwFirstDigitTimeout

Duración del tiempo en milisegundos en los que se espera el primer dígito. Si el primer dígito no se recibe en este período de tiempo, se anula la recopilación de dígitos y se envía un mensaje LINE_GATHERDIGITS a la aplicación. El búfer solo contiene el carácter NULL , lo que indica que no se han recibido dígitos y que la primera recopilación de dígitos ha finalizado el tiempo de espera. Las funcionalidades de dispositivo de línea de la llamada especifican el intervalo válido para este parámetro o indican que no se admiten tiempos de espera.

dwInterDigitTimeout

Duración máxima de tiempo en milisegundos entre dígitos consecutivos. Si no se recibe ningún dígito en este período de tiempo, se anula la recopilación de dígitos y se envía un mensaje LINE_GATHERDIGITS a la aplicación. El búfer solo contiene los dígitos recopilados hasta este punto seguido de un carácter NULL , lo que indica que una recopilación de dígitos terminada en un tiempo de espera interdigit. Las funcionalidades de dispositivo de línea de la llamada especifican el intervalo válido para este parámetro o indican que no se admiten tiempos de espera.

Valor devuelto

Devuelve cero si la solicitud se realiza correctamente o un número de error negativo si se produce un error. Los valores devueltos posibles son:

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

Comentarios

La colección de dígitos finaliza cuando se ha recopilado el número solicitado de dígitos. También se termina cuando uno de los dígitos detectados coincide con un dígito en szTerminationDigits antes de recopilar el número especificado de dígitos. El dígito de terminación detectado también se coloca en el búfer y se devuelve el búfer parcial.

Otra forma de cancelar la recopilación de dígitos se produce cuando expira uno de los tiempos de espera. DwFirstDigitTimeout expira si el primer dígito no se recibe en este período de tiempo. DwInterDigitTimout expira si el segundo, tercero, (etc.) no se recibe dentro de ese período de tiempo del dígito detectado anteriormente y se devuelve un búfer parcial.

Un cuarto método para terminar la colección de dígitos es llamar a esta función de nuevo mientras la colección está en curso. Finaliza la sesión de recopilación anterior, los dígitos recopilados hasta ese punto se copian en el búfer proporcionado desde la llamada anterior a esta función y el búfer se entrega cuando se envía el mensaje de LINE_GATHERDIGITS a la aplicación. El mecanismo para terminar la recopilación de dígitos sin iniciar otra recopilación de los dígitos es invocar esta función con lpsDigits igual a NULL.

Esta función se considera correcta si la colección de dígitos se ha iniciado correctamente, no si la colección de dígitos ha finalizado. En todos los casos en los que se devuelve un búfer parcial, los dígitos válidos (si los hay) van seguidos de un carácter NULL .

Aunque esta función se puede invocar en cualquier estado de llamada, los dígitos normalmente solo se pueden recopilar mientras la llamada está en estado conectado .

El mensaje LINE_GATHERDIGITS se envía solo a la aplicación que inició la solicitud. También se envía cuando se devuelven búferes parciales debido a tiempos de espera o dígitos de finalización coincidentes, o cuando otra solicitud lineGatherDigits cancela la solicitud en la llamada. Solo una solicitud de recopilación de dígitos puede estar activa en una llamada en cualquier momento dado en todas las aplicaciones que sean propietarios de la llamada. Dado el comportamiento asincrónico de la operación, una aplicación que emite varias solicitudes lineGatherDigits en sucesión rápida puede hacerlo y recibir varios mensajes de LINE_GATHERDIGITS más adelante. Aunque esto sería un comportamiento inusual de la aplicación, la aplicación puede contar el número de estos mensajes para permitir que los mensajes de cancelación coincidan con las solicitudes anteriores. En cualquier caso, solo se debe suponer que la solicitud más reciente es válida.

Nota Cuando una aplicación invoca cualquier operación asincrónica que vuelva a escribir datos en la memoria de la aplicación, la aplicación debe mantener esa memoria disponible para escribir hasta que se reciba un mensaje de LINE_REPLY o LINE_GATHERDIGITS .

Una aplicación puede usar lineMonitorDigits para habilitar o deshabilitar la detección de dígitos sin búfer. Cada vez que se detecta un dígito de este modo, se envía un mensaje LINE_MONITORDIGITS a la aplicación. La detección de dígitos almacenados en búfer y sin búfer se puede habilitar simultáneamente para la misma llamada.

La recopilación de dígitos en una llamada de conferencia solo se aplica a hConfCall, no a las llamadas individuales participantes.

Si la función lineGatherDigits se usa para cancelar una solicitud anterior para recopilar dígitos, la función copia todos los dígitos recopilados hasta ese punto en el búfer especificado en la llamada de función original. A continuación, la función envía un mensaje LINE_GATHERDIGITS a la aplicación, independientemente de si el parámetro lpszDigits de la segunda llamada especifica un valor NULL o una dirección diferente.