Función lineMakeCall (tapi.h)

Artículo
03/08/2023

La función lineMakeCall realiza una llamada en la línea especificada a la dirección de destino especificada. Opcionalmente, se pueden especificar parámetros de llamada si se solicitan parámetros de configuración de llamadas predeterminados, pero no.

Sintaxis

LONG lineMakeCall(
  HLINE                  hLine,
  LPHCALL                lphCall,
  LPCSTR                 lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parámetros

hLine

Identificador del dispositivo de línea abierta en el que se va a originar una llamada.

lphCall

Puntero a un controlador HCALL. El identificador solo es válido después de que la aplicación reciba el mensaje de LINE_REPLY que indica que la función lineMakeCall se completó correctamente. Use este identificador para identificar la llamada al invocar otras operaciones de telefonía en la llamada. La aplicación es inicialmente el único propietario de esta llamada. Este identificador es void si la función devuelve un error (sincrónica o asincrónicamente por el mensaje de respuesta).

lpszDestAddress

Puntero a la dirección de destino. Esto sigue el formato de número de marcado estándar. Este puntero puede ser NULL para las direcciones sin marcado (como con un teléfono activo) o cuando se realiza toda la marcación mediante lineDial. En este último caso, lineMakeCall asigna una apariencia de llamada disponible que normalmente permanecería en el estado dialtone hasta que comienza la marcación. Los proveedores de servicios que tienen funcionalidades de multiplexación inversa pueden permitir que una aplicación especifique varias direcciones a la vez.

dwCountryCode

Código de país o región de la entidad llamada. Si se especifica un valor de 0, la implementación usa un valor predeterminado.

lpCallParams

Puntero a una estructura LINECALLPARAMS . Esta estructura permite a la aplicación especificar cómo quiere que se configure la llamada. Si se especifica NULL , se establece una llamada de voz de 3,1 kHz predeterminada y se selecciona una dirección de origen arbitraria en la línea. Esta estructura permite a la aplicación seleccionar elementos como el modo de portador de la llamada, la velocidad de datos, el modo multimedia esperado, la dirección de origen, el bloqueo de la información del identificador de llamada y los parámetros de marcado.

Valor devuelto

Devuelve un identificador de solicitud positivo si la función se completa de forma asincrónica o un número de error negativo si se produce un error. El parámetro dwParam2 del mensaje de LINE_REPLY correspondiente es cero si la función se ejecuta correctamente o es un número de error negativo si se produce un error. Los valores devueltos posibles son:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINEHANDLE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALLINESTATE, LINEERR_CALLUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_DIALBILLING, LINEERR_INVALPARAM, LINEERR_DIALDIALTONE, LINEERR_INVALPOINTER, LINEERR_DIALPROMPT, LINEERR_INVALRATE, LINEERR_DIALQUIET, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONFAILED, LINEERR_INVALADDRESS, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSID, LINEERR_RATEUNAVAIL, LINEERR_INVALADDRESSMODE LINEERR_ RESOURCEUNAVAIL, LINEERR_INVALBEARERMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALCALLPARAMS, LINEERR_UNINITIALIZED, LINEERR_INVALCOUNTRYCODE, LINEERR_USERUSERINFOTOOBIG.

Comentarios

Si se devuelve LINEERR_INVALLINESTATE, la línea no se encuentra actualmente en un estado en el que se puede realizar esta operación. Puede encontrar una lista de operaciones válidas actualmente en el miembro dwLineFeatures (del tipo LINEFEATURE_) en la estructura LINEDEVSTATUS . La llamada a lineGetLineDevStatus actualiza la información de LINEDEVSTATUS. Si se devuelve LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE o LINEERR_DIALPROMPT, no se ha producido ninguna de las acciones realizadas por lineMakeCall ; por ejemplo, no se ha marcado ninguna de las direcciones que se pueden marcar antes del carácter infractor, no ha cambiado ningún estado de hookswitch, etc.

Una vez completada la marcación, normalmente se envían varios mensajes LINE_CALLSTATE a la aplicación para notificarle el progreso de la llamada. No se especifica ninguna secuencia generalmente válida de transiciones de estado de llamada, ya que no se puede garantizar ninguna secuencia fija única de transiciones en la práctica. Una secuencia típica puede provocar que una llamada pase de dialtone, dialing, continuar, ringback, a connected. Con líneas sin marcado, la llamada normalmente puede pasar directamente al estado conectado .

Una aplicación tiene la opción de especificar una dirección de origen en el dispositivo de línea especificado. Un proveedor de servicios que modela todas las estaciones de un conmutador como direcciones en un único dispositivo de línea permite que la aplicación origine llamadas desde cualquiera de estas estaciones mediante lineMakeCall.

Los parámetros de llamada permiten a la aplicación realizar llamadas que no son de voz o solicitar opciones de configuración de llamadas especiales que no están disponibles de forma predeterminada.

Una aplicación puede marcar parcialmente mediante lineMakeCall y continuar marcando mediante lineDial. Para obtener más información sobre la marcación parcial, vea lineDial y TSPI_lineMakeCall. Para abandonar un intento de llamada, use lineDrop.

Una vez que lineMakeCall devuelve un mensaje de respuesta correcta a la aplicación, se envía un mensaje de LINE_CALLSTATE a la aplicación para indicar el estado actual de la llamada. Este estado no es necesariamente LINECALLSTATE_DIALTONE.

Esta función puede enviar datos a través de la conexión en forma sin cifrar; por lo tanto, es posible que alguien intercepte en la red pueda leer los datos. El riesgo de seguridad de enviar los datos en texto no cifrado debe tenerse en cuenta antes de usar este método.

Precaución TAPI escribirá los datos devueltos en el búfer al que hace referencia lphCall cuando se devuelva el mensaje LINE_REPLY. Esto significa que el búfer debe permanecer válido hasta que se devuelva el mensaje LINE_REPLY; de lo contrario, pueden producirse daños en los datos y excepciones.