Función lineConfigDialogEdit (tapi.h)

Artículo
03/08/2023

La función lineConfigDialogEdit hace que el proveedor del dispositivo de línea especificado muestre un cuadro de diálogo (adjunto a hwndOwner de la aplicación) para permitir al usuario configurar parámetros relacionados con el dispositivo de línea.

Sintaxis

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

Parámetros

dwDeviceID

Identificador del 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. Puede ser NULL para indicar que cualquier ventana creada durante la función no debe tener ninguna ventana de propietario.

lpszDeviceClass

Puntero a una cadena terminada en null que identifica un nombre de clase de dispositivo. Esta clase de dispositivo permite a la aplicación seleccionar una subscreen específica de la información de configuración aplicable a esa clase de dispositivo. Este parámetro es opcional y se puede dejar NULL o vacío, en cuyo caso se selecciona la configuración de nivel más alto.

lpDeviceConfigIn

Puntero a la estructura de datos de configuración opaca devuelta por lineGetDevConfig (o una invocación anterior de 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 lineGetDevConfig o una invocación anterior de lineConfigDialogEdit.

lpDeviceConfigOut

Puntero a la ubicación de memoria del tipo VARSTRING donde se devuelve la estructura de configuración del dispositivo. Tras completar 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 un número de error negativo si se produce un error. Los valores devueltos posibles son:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

Comentarios

Si se devuelve LINEERR_STRUCTURETOOSMALL, el miembro dwTotalSize de la estructura VARSTRING a la que apunta lpDeviceConfigOut no especifica suficiente memoria para contener toda la estructura de configuración. El miembro dwNeededSize se ha establecido en la cantidad necesaria. En la medida en que las entradas del usuario se reflejaron en la información que no se pudo devolver debido a un espacio insuficiente, esas modificaciones se pierden; Por lo tanto, las aplicaciones deben asignar la cantidad máxima de espacio que puede necesitar la clase de dispositivo para devolver su estructura de configuración (para obtener más información, consulte Clases de dispositivo TAPI).

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

El parámetro lpszDeviceClass permite a la aplicación seleccionar 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 lineGetID. Por ejemplo, si la línea admite comm API, pasar "COMM" 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 encontrar los parámetros de interés).

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

La diferencia entre esta función y lineConfigDialog es el origen de los parámetros que se van a editar y el resultado de la edición. En lineConfigDialog, los parámetros editados son los que están actualmente en uso 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 lineConfigDialog. Con 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 que ello afecte 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, lineConfigDialogEdit permite a una aplicación proporcionar la capacidad de que el usuario configure parámetros para futuras llamadas sin tener un impacto en ninguna llamada activa. Sin embargo, la salida de esta función se puede pasar a lineSetDevConfig para afectar a la llamada actual o a la siguiente llamada.