función TUISPI_lineConfigDialogEdit (tspi.h)

Artículo
03/08/2023

La función TUISPI_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. Esta función hace que la función TSPI_lineConfigDialogEdit está obsoleta en la versión 2.0 y posteriores (compatible con la versión 1.4 y anteriores).

La implementación es opcional.

Sintaxis

LONG TSPIAPI TUISPI_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass,
  LPVOID const      lpDeviceConfigIn,
  DWORD             dwSize,
  LPVARSTRING       lpDeviceConfigOut
);

Parámetros

lpfnUIDLLCallback

Puntero a una función a la que el archivo DLL de la interfaz de usuario puede llamar para comunicarse con el archivo DLL del proveedor de servicios para obtener la información necesaria para mostrar el cuadro de diálogo.

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 TUISPI_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 TUISPI_lineConfigDialogEdit.

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 .

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

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 TUISPI_lineConfigDialog es el origen de los parámetros que se van a editar y el resultado de la edición. En TUISPI_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 TUISPI_lineConfigDialog. Con TUISPI_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, TUISPI_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.