función TSPI_lineMakeCall (tspi.h)

Artículo
08/26/2023

La función TSPI_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 solicita algo, pero se solicitan parámetros de configuración de llamadas predeterminados.

Sintaxis

LONG TSPIAPI TSPI_lineMakeCall(
  DRV_REQUESTID          dwRequestID,
  HDRVLINE               hdLine,
  HTAPICALL              htCall,
  LPHDRVCALL             lphdCall,
  LPCWSTR                lpszDestAddress,
  DWORD                  dwCountryCode,
  LPLINECALLPARAMS const lpCallParams
);

Parámetros

dwRequestID

Identificador de la solicitud asincrónica.

hdLine

Identificador de la línea en la que se va a originar la nueva llamada.

htCall

El identificador TAPI de la nueva llamada. El proveedor de servicios debe guardarlo y usarlo en todas las llamadas posteriores al procedimiento LINEEVENT que notifica eventos en la llamada.

lphdCall

Puntero a un identificador de llamada. El proveedor de servicios debe rellenar esta ubicación con su identificador para la llamada antes de que se devuelva este procedimiento. TAPI omite este identificador si la función produce un error.

lpszDestAddress

Puntero a una cadena Unicode terminada en null que especifica la dirección de destino. Esto sigue el formato de número de marcado estándar. Este puntero se puede especificar como NULL para las direcciones sin marcado (como con un teléfono frecuente, que siempre se conecta automáticamente a un número predefinido) o cuando se realiza todo el marcado mediante TSPI_lineDial. En este último caso, TSPI_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 TAPI 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 selecciona elementos como el modo de portador de la llamada, la velocidad de datos, el tipo de medio 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 dwRequestID o un número de error si se produce un error. El parámetro real lResult del ASYNC_COMPLETION correspondiente es cero si la función se realiza correctamente o si se produce un error. Los valores devueltos posibles son los siguientes:

LINEERR_ADDRESSBLOCKED, LINEERR_INVALLINESTATE, LINEERR_BEARERMODEUNAVAIL, LINEERR_INVALRATE, LINEERR_CALLUNAVAIL, LINEERR_INVALLINEHANDLE, LINEERR_DIALBILLING, LINEERR_INVALADDRESS, LINEERR_DIALQUIET, LINEERR_INVALADDRESSID, LINEERR_DIALDIALTONE, LINEERR_INVALCALLPARAMS, LINEERR_DIALPROMPT, LINEERR_NOMEM, LINEERR_INUSE, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALADDRESSMODE, LINEERR_OPERATIONFAILED, LINEERR_INVALBEARERMODE, LINEERR_RESOURCEUNAVAIL, LINEERR_ INVALCOUNTRYCODE, LINEERR_RATEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_USERUSERINFOTOOBIG.

Comentarios

El proveedor de servicios devuelve LINEERR_INVALLINESTATE si la línea no está 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 . (Al llamar a TSPI_lineGetLineDevStatus se actualiza la información en LINEDEVSTATUS).

Si el proveedor de servicios devuelve LINEERR_DIALBILLING, LINEERR_DIALQUIET, LINEERR_DIALDIALTONE o LINEERR_DIALPROMPT, no debe realizar ninguna de las acciones realizadas por TSPI_lineMakeCall. Por ejemplo, sin marcado parcial y sin offhook. Esto se debe a que el proveedor de servicios debe examinar previamente el número de caracteres no admitidos primero.

Después de TSPI_lineMakeCall devuelve un mensaje de devolución de llamada de respuesta SUCCESS a la aplicación, el proveedor de servicios debe enviar LINE_CALLSTATE mensajes al lpfnEventProc pasado en TSPI_lineOpen para notificar a TAPI sobre el progreso de la llamada. Una secuencia notificada típica puede ser tono de marcado, marcado, continuar, anillo invertido y conectado; El primer estado notificado no es necesariamente LINECALLSTATE_DIALTONE. El proveedor de servicios elige cuántos de estos estados se notifican. Se recomienda que se envíen tantos como sea posible para que las aplicaciones puedan realizar las acciones adecuadas.

El proveedor de servicios realiza inicialmente la supervisión multimedia en la nueva llamada para al menos el conjunto de tipos de medios supervisados para en la línea.

Si la cadena de marcado es NULL, el proveedor de servicios toma la línea al estado de marcación (para un proveedor de servicios basado en Comm, esto implicaría ATD) y envía un mensaje de estado de llamada que indica LINECALLSTATE_DIALTONE.

Si la cadena de marcado termina en ';' (punto y coma), el proveedor de servicios marca el número parcial y envía el mensaje LINECALLSTATE_DIALING. Esta llamada se completa mediante llamadas a TSPI_lineDial.

Si la cadena de marcado contiene caracteres (W, @, $, ?) que no son compatibles con el proveedor de servicios, el proveedor de servicios debe examinar la cadena de marcado y devolver (sincrónicamente) un error correspondiente al primer carácter no válido.

Si se establece la marca de LINECALLPARAMFLAGS_IDLE, el proveedor de servicios debe comprobar el estado de la línea actual (equivalente a salir del enlace y el tono de marcado de detección). Si se establece esta marca IDLE y no hay ningún tono de marcado, se produce un error en la función con el error LINEERR_CALLUNAVAIL. Si no se establece la marca IDLE o hay un tono de marcado, el marcado puede continuar.

Esta función difiere de la función TAPI correspondiente en que sigue el modelo de TSPI para comenzar la duración de una llamada. TAPI y el proveedor de servicios intercambian identificadores opacos que representan la llamada entre sí. Además, el proveedor de servicios puede realizar devoluciones de llamada para la nueva llamada antes de que vuelva de este procedimiento. En cualquier caso, el proveedor de servicios también debe tratar el identificador que devolvió como "todavía no válido" hasta después de que el mensaje de ASYNC_COMPLETION coincidente notifique que se ha realizado correctamente. No debe emitir ningún mensaje LINEEVENT para la nueva llamada ni incluirlo en recuentos de llamadas en mensajes o estructuras de datos de estado para la línea.