función TSPI_lineSetDevConfig (tspi.h)

Artículo
03/13/2024

La función TSPI_lineSetDevConfig restaura la configuración de un dispositivo asociado uno a uno con el dispositivo de línea de una estructura de datos obtenida anteriormente mediante TSPI_lineGetDevConfig. El contenido de esta estructura de datos es específico de la línea [proveedor de servicios] y la clase de dispositivo.

Sintaxis

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

Parámetros

dwDeviceID

Dispositivo de línea que se va a configurar.

lpDeviceConfig

Puntero a la estructura de datos de configuración que se devuelve en la parte variable de la estructura VARSTRING mediante TSPI_lineGetDevConfig.

dwSize

Número de bytes de la estructura a la que apunta lpDeviceConfig. Este valor se devuelve en el miembro dwStringSize de la estructura VARSTRING devuelta por TSPI_lineGetDevConfig.

Nota Si los parámetros de tamaño de la estructura no son correctos, existe la posibilidad de que se sobrescriban los datos. Para obtener más información sobre cómo establecer tamaños de estructura, consulte el tema de asignación de memoria .

lpszDeviceClass

Puntero a una cadena Unicode terminada en null que especifica la clase de dispositivo del dispositivo cuya configuración se va a restaurar. 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" (es decir, cuando dwSelect tiene el valor LINECALLSELECT_LINE).

Valor devuelto

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

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL, LINEERR_NODRIVER.

Comentarios

El estado de llamada es específico del dispositivo.

El proveedor de servicios devuelve LINEERR_INVALPARAM si la información contenida en la estructura a la que apunta lpDeviceConfig no es válida para este dispositivo.

El proveedor de servicios devuelve LINEERR_INVALLINESTATE si no se puede cambiar la configuración del dispositivo en el estado de línea actual. Otra aplicación puede usar la línea.

Esta función se puede usar para restaurar la configuración de un dispositivo asociado uno a uno con el dispositivo de línea de una estructura de datos recuperada anteriormente del proveedor de servicios mediante la función TSPI_lineGetDevConfig . El parámetro lpszDeviceClass selecciona cuál de entre posiblemente varias clases diferentes de dispositivos es restaurar 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 permite la clase de dispositivo tapi/line en esta función. Restaura parámetros que tienen ámbito de "línea", como la lista de direcciones de esta línea y la lista de dispositivos de hardware físicos, como los puertos COMM correspondientes a las direcciones o el número máximo de llamadas simultáneas (si se pueden configurar).

En general, esta función NO permite clases de dispositivo relacionadas con medios, como mci waveaudio, onda de bajo nivel o clases de dispositivo de modo de datos, 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 dispositivos por 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 es ambigua. Se puede realizar una excepción para las clases de dispositivo específicas de llamadas o específicas de direcciones 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.

Hay varias razones por las que la compatibilidad excepcional con 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, de varias llamadas, solo un subconjunto de proveedores de servicios los admite. Es probable que los programas de aplicación 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 multimedia 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 tiene que 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 "abres" 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 establecido o recuperado a través de TSPI_lineGetDevConfig puede revertir a valores predeterminados o no definidos. El autor de la llamada solo puede recuperar cualquier configuración temporal de forma confiable 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 dicha secuencia a través de 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 .ini y volver a cargarla cada vez que se inicialice el proveedor de servicios.

El formato exacto de los datos contenidos en la estructura pasada a esta función es específico de la API de clase de dispositivo y de línea, no está documentado y no está definido. La estructura que se pasa a esta función no puede ser accesible directamente o manipulada por la aplicación, pero solo se puede almacenar intacta y posteriormente se puede usar desde un TSPI_lineGetDevConfig anterior para obtener 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 comprobar esta estructura de datos para comprobar la coherencia de los errores debido a que una aplicación cliente pasa información incompatible.

Nota Algunos proveedores de servicios pueden permitir que la configuración se establezca mientras un dispositivo está en uso y otros pueden no hacerlo.