TSPI_lineGetDevConfig función (tspi.h)

Artículo
08/26/2023

La función TSPI_lineGetDevConfig devuelve un objeto de estructura de datos, cuyo contenido es específico de la línea (proveedor de servicios) y la clase de dispositivo, lo que proporciona la configuración actual de un dispositivo asociado uno a uno con el dispositivo de línea.

Sintaxis

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

Parámetros

dwDeviceID

Dispositivo de línea que se va a configurar.

lpDeviceConfig

Puntero a una estructura de datos de tipo VARSTRING donde se devuelve la estructura de configuración del dispositivo asociado. Una vez completada correctamente la solicitud, el proveedor de servicios rellena esta estructura de datos con la configuración del dispositivo. El miembro dwStringFormat de la estructura VARSTRING debe establecerse en STRINGFORMAT_BINARY. Si el miembro dwTotalSize de la estructura VARSTRING a la que apunta el parámetro lpDeviceConfig es mayor o igual que el tamaño de la parte fija de la estructura, el proveedor de servicios establece el miembro dwNeededSize en el tamaño necesario y devuelve cero.

lpszDeviceClass

Puntero a una cadena Unicode terminada en null que especifica la clase de dispositivo del dispositivo cuya configuración se solicita. Las cadenas de clase de dispositivo válidas son las mismas que las especificadas para la función TSPI_lineGetID cuando se aplica a un dispositivo de línea (dwSelect tiene el valor LINECALLSELECT_LINE).

Valor devuelto

Devuelve cero si la función se realiza correctamente o un número de error si se produce un error. Los valores devueltos posibles son los siguientes:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_STRUCTURETOOSMALL, LINEERR_OPERATIONFAILED, LINEERR_NODRIVER, LINEERR_RESOURCEUNAVAIL.

Comentarios

El estado de llamada es específico del dispositivo.

Esta función se puede usar para recuperar una estructura de datos del proveedor de servicios que especifica la configuración de un dispositivo asociado uno a uno con el dispositivo de línea. El parámetro lpszDeviceClass selecciona cuál de entre las distintas clases de dispositivos es recuperar su configuración. El conjunto de clases admitidas está restringido a aquellos cuyos dispositivos corresponden uno a uno con el dispositivo de línea. Para obtener más información sobre las clases de dispositivo comunes, consulte Clases de dispositivo TSPI.

Normalmente, un proveedor de servicios debe permitir la clase de dispositivo tapi/line en esta función. Recuperaría parámetros que tienen ámbito de "línea", como la lista de direcciones de esta línea, la lista de dispositivos de hardware físicos, como puertos COMM correspondientes a las direcciones, el número máximo de llamadas simultáneas (si se puede configurar), etc.

En general, esta función no permite clases de dispositivo relacionadas con medios, como mci waveaudio, onda de bajo nivel o clases de dispositivo datamodem, ya que normalmente se aplican a una llamada determinada o a una dirección determinada. Dado que puede haber más de uno de estos por dispositivo de línea, la identificación de la llamada o dirección determinada simplemente por el parámetro de identificador de dispositivo de línea en esta función sería ambigua. Se puede realizar una excepción para las clases de dispositivo específicas de llamadas o específicas de la dirección en los casos en los que hay información de configuración de clase que se aplica a todo el ámbito del dispositivo de línea, como los valores predeterminados iniciales, etc.

Hay varias razones por las que la compatibilidad excepcional con las clases de dispositivo específicas de llamadas y específicas de direcciones es de solo un valor limitado en esta función. En primer lugar, dado que estas clases pueden ser ambiguas en proveedores de servicios de varias direcciones o varias llamadas, solo un subconjunto de proveedores de servicios los admite. Es probable que las aplicaciones agreguen una dependencia específica del dispositivo en la inclusión de estas clases en esta función. En segundo lugar, a medida que surgen "clases" de medios de nivel superior que implementan protocolos de alto nivel como el acceso al sistema de archivos de acceso telefónico local en términos de API de transporte de bajo nivel, la configuración de estas clases tiende hacia el ámbito de "instancia" en lugar del ámbito de "clase". La API multimedia de alto nivel debe proporcionar sus propias funciones para configurar instancias específicas de llamadas o específicas de direcciones.

Cualquier tipo de dispositivos y clases de dispositivo que admita esta función, puede afectar potencialmente a dos tipos de información de configuración: permanente y temporal. La información permanente sobrevive a través de diferentes "aperturas" de la línea, e incluso en diferentes "inicializaciones" del propio proveedor de servicios. La información temporal solo sobrevive dentro de una "apertura" única de la línea. Cuando se cierra la línea, cualquier información temporal que se haya recuperado o establecido a través de TSPI_lineSetDevConfig puede revertir a valores predeterminados o no definidos. El autor de la llamada puede recuperar de forma confiable cualquier configuración temporal solo mediante una secuencia como TSPI_lineOpen, TSPI_lineConfigDialog, TSPI_lineGetDevConfig. El autor de la llamada puede establecer de forma confiable información de configuración temporal recuperada por una secuencia como TSPI_lineOpen, TSPI_lineSetDevConfig. La parte temporal de la configuración permanece estable solo hasta el siguiente TSPI_lineConfigDialog, TSPI_lineSetDevConfig o TSPI_lineClose. El proveedor de servicios debe encargarse de almacenar cualquier parte permanente de la configuración, normalmente en un archivo de .ini y volver a cargarla siempre que se inicialice el proveedor de servicios.

El formato exacto de los datos contenidos en la estructura devuelta por esta función es específico de la API de clase de dispositivo y línea, no está documentado y no está definido. La aplicación no puede acceder directamente a la estructura devuelta por esta función ni manipularla, pero solo se puede almacenar intacta y después usarse en TSPI_lineSetDevConfig para restaurar la configuración. La estructura tampoco se puede pasar necesariamente a otros dispositivos, incluso de la misma clase de dispositivo (aunque esto puede funcionar en algunos casos, no está garantizado). Un proveedor de servicios debe colocar elementos en la estructura de datos para permitir que se compruebe la coherencia para protegerse frente a errores debido a que una aplicación cliente pasa información incompatible.