Función lineOpen (tapi.h)

Artículo
03/08/2023

La función lineOpen abre el dispositivo de línea especificado por su identificador de dispositivo y devuelve un identificador de línea para el dispositivo de línea abierto correspondiente. Este identificador de línea se usa en operaciones posteriores en el dispositivo de línea.

Sintaxis

LONG lineOpen(
  HLINEAPP               hLineApp,
  DWORD                  dwDeviceID,
  LPHLINE                lphLine,
  DWORD                  dwAPIVersion,
  DWORD                  dwExtVersion,
  DWORD_PTR              dwCallbackInstance,
  DWORD                  dwPrivileges,
  DWORD                  dwMediaModes,
  LPLINECALLPARAMS const lpCallParams
);

Parámetros

hLineApp

Controle el registro de la aplicación con TAPI.

dwDeviceID

Identifica el dispositivo de línea que se va a abrir. Puede ser un identificador de dispositivo válido o el valor.

Valor	Significado
LINEMAPPER	Este valor se usa para abrir un dispositivo de línea en el sistema que admite las propiedades especificadas en lpCallParams. La aplicación puede usar lineGetID para determinar el identificador del dispositivo de línea que se abrió.

lphLine

Puntero a un controlador HLINE que luego se carga con el identificador que representa el dispositivo de línea abierto. Use este identificador para identificar el dispositivo al invocar otras funciones en el dispositivo de línea abierta.

dwAPIVersion

Número de versión de la API en el que la aplicación y la API de telefonía han acordado operar. Este número se obtiene con lineNegotiateAPIVersion.

dwExtVersion

Número de versión de la extensión en el que la aplicación y el proveedor de servicios aceptan operar. Este número es cero si la aplicación no usa ninguna extensión. Este número se obtiene con lineNegotiateExtVersion.

dwCallbackInstance

Los datos de instancia de usuario que se devuelven a la aplicación con cada mensaje asociado a esta línea o con direcciones o llamadas en esta línea. La API de telefonía no interpreta este parámetro.

dwPrivileges

Privilegio que la aplicación quiere cuando se le notifique de una llamada Este parámetro contiene una o varias de las constantes de LINECALLPRIVILEGE_. En el caso de las aplicaciones que usan TAPI versión 2.0 o posterior, los valores de este parámetro también se pueden combinar con una o varias de las constantes de LINEOPENOPTION_.

Si se especifica la opción LINEOPENOPTION_SINGLEADDRESS, la aplicación solo está interesada en las nuevas llamadas que aparecen en la dirección especificada por el miembro dwAddressID en la estructura LINECALLPARAMS a la que apunta el parámetro lpCallParams (que debe especificarse).

Si se especifica LINEOPENOPTION_SINGLEADDRESS pero lpCallParams no es válido o dwAddressID incluido no existe en la línea, se produce un error en la apertura con LINERR_INVALADDRESSID.

Además de establecer el miembro dwAddressID de la estructura LINECALLPARAMS en la dirección deseada, la aplicación también debe establecer dwAddressMode en LINECALLPARAMS en LINEADDRESSMODE_ADDRESSID.

La opción LINEOPENOPTION_SINGLEADDRESS afecta solo a la asignación de tapi de la propiedad inicial de las llamadas creadas por el proveedor de servicios mediante un mensaje de LINE_NEWCALL . Una aplicación que abre la línea con LINECALLPRIVILEGE_MONITOR sigue recibiendo identificadores de supervisión a todas las llamadas creadas en la línea. Además, la aplicación no está restringida de ninguna manera de realizar llamadas o realizar otras operaciones que afecten a otras direcciones en la línea abierta.

Cuando se especifica la opción LINEOPENOPTION_PROXY (solo TAPI 2.0 o superior), la aplicación también debe indicar qué solicitudes de proxy específicas está preparada para controlar. Para ello, pasa, en el parámetro lpCallParams , un puntero a una estructura LINECALLPARAMS en la que los miembros dwDevSpecificSize y dwDevSpecificOffset se han establecido para delimitar una matriz de DWORDs. Cada elemento de esta matriz contendrá una de las LINEPROXYREQUEST_ Constantes. Por ejemplo, una aplicación de controlador de proxy que admita las cinco funciones relacionadas con el Agente pasaría una matriz de cinco DWORDs (dwDevSpecificSize sería 20 decimal) que contiene los cinco valores definidos LINEPROXYREQUEST_.

La aplicación de controlador de solicitudes de proxy se puede ejecutar en cualquier máquina que tenga autorización para controlar el dispositivo de línea. Sin embargo, las solicitudes siempre se enrutan a través del servidor en el que se ejecuta el proveedor de servicios que controla realmente el dispositivo de línea. Por lo tanto, es más eficaz si la aplicación que controla las solicitudes de proxy (como el control del agente de ACD) se ejecuta directamente en el servidor junto con el proveedor de servicios.

Los intentos posteriores, por la misma aplicación u otras aplicaciones, para abrir el dispositivo de línea y registrarse para controlar las mismas solicitudes de proxy que una aplicación que ya está registrada produce un error en LINEERR_NOTREGISTERED.

Para detener el control de solicitudes en la línea, la aplicación simplemente llama a lineClose.

Otras combinaciones de marcas devuelven el error LINEERR_INVALPRIVSELECT.

dwMediaModes

Tipo de medio o modos de interés para la aplicación. Este parámetro se usa para registrar la aplicación como destino potencial para la llamada entrante y la entrega de llamadas para el tipo de medio especificado. Este parámetro solo es significativo si el bit LINECALLPRIVILEGE_OWNER en dwPrivileges está establecido (y se omite en caso contrario). Este parámetro usa una o varias de las constantes de LINEMEDIAMODE_.

lpCallParams

Puntero a una estructura de tipo LINECALLPARAMS. Este puntero solo se usa si se usa LINEMAPPER o LINEOPENOPTION_PROXY; de lo contrario , lpCallParams se omite. Describe el parámetro de llamada que el dispositivo de línea debe poder proporcionar.

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_ALLOCATED, LINEERR_LINEMAPPERFAILED, LINEERR_BADDEVICEID, LINEERR_NODRIVER, LINEERR_INCOMPATIBLEAPIVERSION, LINEERR_NOMEM, LINEERR_INCOMPATIBLEEXTVERSION, LINEERR_OPERATIONFAILED, LINEERR_INVALAPPHANDLE, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALMEDIAMODE, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_INVALPRIVSELECT, LINEERR_REINIT, LINEERR_NODEVICE, LINEERR_OPERATIONUNAVAIL.

Comentarios

Si se devuelve LINEERR_ALLOCATED, no se puede abrir la línea debido a una condición "persistente", como la de un puerto serie abierto exclusivamente por otro proceso. Si se devuelve LINEERR_RESOURCEUNAVAIL, la línea no se puede abrir debido a una sobrecarga de recursos dinámicos, como en ciclos de procesador DSP o memoria. Esta sobrecarga puede ser transitoria, causada por la supervisión del tipo de medio o los tonos, y los cambios en estas actividades por parte de otras aplicaciones pueden hacer posible volver a abrir la línea en un breve período de tiempo. Si se devuelve LINEERR_REINIT y se ha solicitado reinicialización de TAPI (por ejemplo, como resultado de agregar o quitar un proveedor de servicios de telefonía), las solicitudes lineOpen se rechazan con este error hasta que la última aplicación cierra su uso de la API (mediante lineShutdown); en ese momento, la nueva configuración se hace efectiva y las aplicaciones se vuelven a permitir que las aplicaciones llamen a lineInitializeEx.

Abrir una línea siempre permite a la aplicación realizar llamadas en cualquier dirección disponible en la línea. La capacidad de la aplicación para tratar las llamadas entrantes o ser el destino de las entregas de llamadas en la línea viene determinada por el parámetro dwMediaModes . La función lineOpen registra la aplicación como si tuviera interés en supervisar llamadas o recibir la propiedad de las llamadas que son de los tipos de medios especificados. Si la aplicación solo quiere supervisar las llamadas, puede especificar LINECALLPRIVILEGE_MONITOR. Si la aplicación solo quiere realizar llamadas salientes, puede especificar LINECALLPRIVILEGE_NONE. Si la aplicación está dispuesta a controlar llamadas sin clasificar (llamadas de tipo multimedia desconocido), puede especificar LINECALLPRIVILEGE_OWNER y LINEMEDIAMODE_UNKNOWN. De lo contrario, la aplicación debe especificar el tipo de medio que le interesa controlar. La aplicación puede llamar a la función lineSetCallPrivilege para cambiar los privilegios de llamada especificados por el LINECALLPRIVILEGES_Constants.

Los tipos de medios especificados con lineOpen agregan al valor predeterminado para la supervisión del tipo de medio del proveedor para la determinación inicial del tipo de llamada entrante. La función lineMonitorMedia modifica la máscara que controla LINE_MONITORMEDIA mensajes. Si se abre un dispositivo de línea con privilegios de propietario y no se registra un tipo de medio de extensión, se devuelve el error LINEERR_INVALMEDIAMODE.

Una aplicación que ha abierto correctamente un dispositivo de línea siempre puede iniciar llamadas mediante lineMakeCall, lineUnpark, linePickup y lineSetupConference (con un hCallNULL), así como usar lineForward (suponiendo que esto lo permita las funcionalidades del dispositivo, el estado de línea, etc.).

Una sola aplicación puede especificar varias marcas simultáneamente para controlar varios tipos de medios. Pueden surgir conflictos si varias aplicaciones abren el mismo dispositivo de línea para el mismo tipo de medio. Estos conflictos se resuelven mediante un esquema de prioridad en el que el usuario asigna prioridades relativas a las aplicaciones. Los usuarios pueden establecer prioridades de aplicación llamando a la función lineSetAppPriority . Solo la aplicación de prioridad más alta para un tipo de medio determinado recibirá la propiedad (no solicitada) de una llamada de ese tipo de medio. La propiedad se puede recibir cuando llega por primera vez una llamada entrante o cuando se entrega una llamada. Se llama a la función lineHandoff para entregar la propiedad de una llamada a otra aplicación. Si el usuario no asigna prioridades a la aplicación y varias aplicaciones abren el mismo dispositivo de línea de forma predeterminada, la aplicación que llamó a lineOpen primero tendrá la prioridad más alta.

Cualquier aplicación (incluida cualquier aplicación de prioridad inferior) siempre puede adquirir la propiedad con lineGetNewCalls o lineGetConfRelatedCalls. Si una aplicación abre una línea para la supervisión en un momento en que las llamadas existen en la línea, LINE_CALLSTATE mensajes de esas llamadas existentes no se generan automáticamente en la nueva aplicación de supervisión. La aplicación puede consultar el número de llamadas actuales en la línea para determinar cuántas llamadas existen y, si lo desea, puede llamar a lineGetNewCalls para obtener identificadores de estas llamadas.

Una aplicación que controla la voz automatizada también debe seleccionar el modo de apertura de voz interactiva y asignar la prioridad más baja para la voz interactiva. El motivo es que los proveedores de servicios notifican todos los tipos de medios de voz como voz interactiva. Si la aplicación no realiza la determinación de tipos de medios para el tipo de medio UNKNOWN y ninguna aplicación de voz interactiva ha abierto el dispositivo de línea, las llamadas de voz no podrán acceder a la aplicación de voz automatizada y se quitarán.

La misma aplicación, o instancias diferentes de la misma aplicación, puede abrir la misma línea varias veces con los mismos parámetros o diferentes.

Cuando una aplicación abre un dispositivo de línea, debe especificar la versión de API negociada y, si quiere usar las extensiones de la línea, debe especificar la versión de extensión específica del dispositivo de la línea. Estos números de versión deben haberse obtenido con lineNegotiateAPIVersion y lineNegotiateExtVersion. La numeración de versiones permite mezclar y hacer coincidir diferentes versiones de aplicación con diferentes versiones de API y versiones del proveedor de servicios.

LINEMAPPER permite a una aplicación seleccionar una línea indirectamente, por medio de los servicios que quiere de ella. Al abrir un dispositivo de línea mediante LINEMAPPER, se cumple lo siguiente: Todos los miembros desde el principio de la estructura de datos LINECALLPARAMS a través de dwAddressMode son relevantes. Si dwAddressMode es LINEADDRESSMODE_ADDRESSID significa que cualquier dirección de la línea es aceptable; de lo contrario, si dwAddressMode es LINEADDRESSMODE_DIALABLEADDR, lo que indica que se busca una dirección de origen específica (número de teléfono), o si es una extensión específica del proveedor, dwOrigAddressSize/Offset y la parte de la parte de la variable a la que hacen referencia también son pertinentes. Si dwAddressMode es una extensión específica del proveedor, se puede contener información adicional en el miembro dwDeviceSpecific de tamaño variable.