TSPI_lineConfigDialogEdit función (tspi.h)

Artículo
08/26/2023

La función TSPI_lineConfigDialogEdit está obsoleta. Los proveedores de servicios tapi versión 1.4 o anteriores pueden implementar esta función TSPI. TapI versión 2.0 o posterior implementa TUISPI_lineConfigDialogEdit.

La función TSPI_lineConfigDialogEdit hace que el proveedor del dispositivo de línea especificado muestre un cuadro de diálogo modal como una ventana secundaria de hwndOwner para permitir al usuario configurar parámetros relacionados con el dispositivo de línea.

Sintaxis

LONG TSPIAPI TSPI_lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

Parámetros

dwDeviceID

Dispositivo de línea que se va a configurar.

hwndOwner

Identificador de una ventana a la que se va a adjuntar el cuadro de diálogo.

lpszDeviceClass

Puntero a una cadena Unicode terminada en null que identifica un nombre de clase de dispositivo. Esta clase de dispositivo permite al autor de la llamada seleccionar una subpantalla específica de la información de configuración aplicable a esa clase de dispositivo. Si este parámetro es NULL o apunta a una cadena vacía, se selecciona la configuración de nivel más alto. Las cadenas permitidas son las mismas que para TSPI_lineGetID.

lpDeviceConfigIn

Puntero a la estructura de datos de configuración opaca que devolvió TSPI_lineGetDevConfig (o una invocación anterior de TSPI_lineConfigDialogEdit) en la parte variable de la estructura VARSTRING .

dwSize

Número de bytes de la estructura a la que apunta lpDeviceConfigIn. Este valor se devuelve en el miembro dwStringSize de la estructura VARSTRING devuelta por TSPI_lineGetDevConfig o una invocación anterior de TSPI_lineConfigDialogEdit.

lpDeviceConfigOut

Puntero a la ubicación de memoria del tipo VARSTRING donde se devuelve la estructura de configuración del dispositivo. Una vez completada correctamente la solicitud, esta ubicación se rellena con la configuración del dispositivo. El miembro dwStringFormat de la estructura VARSTRING se establece en STRINGFORMAT_BINARY. Antes de llamar a lineGetDevConfig (o una futura invocación de lineConfigDialogEdit), la aplicación debe establecer el miembro dwTotalSize de esta estructura para indicar la cantidad de memoria disponible para TAPI para devolver información.

Valor devuelto

Devuelve cero si la solicitud se realiza correctamente o si se produce un error. Los valores devueltos posibles son:

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

Comentarios

Esta función hace que el proveedor de servicios muestre un cuadro de diálogo modal (asociado a hwndOwner) para permitir al usuario configurar parámetros relacionados con la línea especificada por dwDeviceID.

El parámetro lpszDeviceClass selecciona una subpantalla específica de información de configuración aplicable a la clase de dispositivo en la que está interesado el usuario; las cadenas permitidas son las mismas que para TSPI_lineGetID. Por ejemplo, si la línea admite comm API, pasar comm/datamodem como lpszDeviceClass hace que el proveedor muestre los parámetros relacionados específicamente con Comm (o, al menos, comience en el punto correspondiente en una cadena de cuadros de diálogo de configuración de varios niveles, por lo que el usuario no tiene que "cavar" para buscar los parámetros de interés).

El parámetro lpszDeviceClass es "tapi/line", "" o NULL para hacer que el proveedor muestre la configuración de nivel más alto para la línea.

La diferencia entre esta función y TSPI_lineConfigDialog es el origen de los parámetros que se van a editar y el resultado de la edición. En TSPI_lineConfigDialog, los parámetros editados son los que se usan actualmente en el dispositivo (o se establecen para su uso en la siguiente llamada) y los cambios realizados tienen (en la medida máxima posible) un impacto inmediato en cualquier conexión activa; además, la aplicación debe usar lineGetDevConfig para capturar el resultado de los cambios de parámetro de TSPI_lineConfigDialog. Con TSPI_lineConfigDialogEdit, los parámetros que se van a editar se pasan desde la aplicación y los resultados se devuelven a la aplicación, sin afectar a las conexiones activas; Los resultados de la edición se devuelven con esta función y la aplicación no necesita llamar a lineGetDevConfig. Por lo tanto, TSPI_lineConfigDialogEdit permite a una aplicación proporcionar la capacidad de que el usuario configure parámetros para llamadas futuras sin tener un impacto en ninguna llamada activa. Sin embargo, la salida de esta función se puede pasar a TSPI_lineSetDevConfig para afectar a la llamada actual o a la siguiente llamada.

Por motivos de compatibilidad con versiones anteriores, los proveedores de servicios antiguos no exportan esta función. TAPI detecta esta condición e informa LINEERR_OPERATIONUNAVAIL si una aplicación intenta llamar a esta función en un proveedor anterior.