TUISPI_lineConfigDialogEdit 函数 (tspi.h)

项目
08/26/2023

TUISPI_lineConfigDialogEdit函数使指定线路设备的提供程序将模式对话框显示为 hwndOwner 的子窗口，以允许用户配置与线路设备相关的参数。此函数使版本 2.0 及更高版本中的 TSPI_lineConfigDialogEdit 函数已过时， (版本 1.4 及更早版本中) 。

实现是可选的。

语法

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

参数

lpfnUIDLLCallback

指向 UI DLL 可以调用的函数的指针，以便与服务提供商 DLL 通信，以获取显示对话框所需的信息。

dwDeviceID

要配置的线路设备。

hwndOwner

对话框要附加到的窗口的句柄。

lpszDeviceClass

指向标识设备类名称的 以 null 结尾的 Unicode 字符串的指针。此设备类允许调用方选择适用于该设备类的配置信息的特定子屏幕。如果此参数为 NULL 或指向空字符串，则选择最高级别配置。允许的字符串与 TSPI_lineGetID相同。

lpDeviceConfigIn

指向TSPI_lineGetDevConfig (返回的不透明配置数据结构的指针，或先前调用 VARSTRING 结构的变量部分中TUISPI_lineConfigDialogEdit) 。

dwSize

lpDeviceConfigIn 指向的结构中的字节数。此值在 varSTRING 结构中的 dwStringSize 成员中返回，该成员由 TSPI_lineGetDevConfig 或先前调用的 TUISPI_lineConfigDialogEdit 返回。

注意如果结构中的大小参数不正确，则有可能覆盖数据。有关设置结构大小的详细信息，请参阅内存分配主题。

lpDeviceConfigOut

指向 VARSTRING 类型的内存位置的指针，其中返回设备配置结构。成功完成请求后，此位置将填充设备配置。 VARSTRING 结构中的 dwStringFormat 成员设置为 STRINGFORMAT_BINARY。在调用 lineGetDevConfig (或将来调用 lineConfigDialogEdit) 之前，应用程序应设置此结构的 dwTotalSize 成员，以指示 TAPI 可用于返回信息的内存量。

返回值

如果请求成功，则返回零;如果发生错误，则返回错误编号。可能的返回值为：

LINEERR_INVALDEVICECLASS、LINEERR_OPERATIONFAILED、LINEERR_INVALPARAM、LINEERR_RESOURCEUNAVAIL、LINEERR_NODRIVER、LINEERR_OPERATIONUNAVAIL、LINEERR_NOMEM。

注解

lpszDeviceClass 参数选择适用于用户感兴趣的设备类的配置信息的特定子屏幕;允许的字符串与 TSPI_lineGetID 相同。例如，如果行支持 Comm API，则传递 comm/datamodem 作为 lpszDeviceClass 会导致提供程序显示专门与 Comm (相关的参数，或者至少从多级配置对话框链中的相应点开始，因此用户无需“挖掘”即可) 查找感兴趣的参数。

lpszDeviceClass 参数为“tapi/line”、“”或 NULL，这会导致提供程序显示行的最高级别配置。

此函数与 TUISPI_lineConfigDialog 之间的区别在于要编辑的参数的源和编辑的结果。在 TUISPI_lineConfigDialog中，编辑的参数是设备上当前正在使用的参数 (或设置为在下一次调用) 上使用的参数，所做的任何更改都 (到最大可能) 立即影响任何活动连接;此外，应用程序必须使用 lineGetDevConfig 从 TUISPI_lineConfigDialog提取参数更改的结果。使用 TUISPI_lineConfigDialogEdit，从应用程序传入要编辑的参数，并将结果返回到应用程序，对活动连接没有影响;编辑结果使用此函数返回，应用程序无需调用 lineGetDevConfig。因此， TUISPI_lineConfigDialogEdit 允许应用程序为用户提供为将来的调用设置参数的功能，而不会影响任何活动调用。但是，此函数的输出可以传递给 TSPI_lineSetDevConfig ，以影响当前调用或下一次调用。

为了向后兼容，旧服务提供商不会导出此函数。如果应用程序尝试在较旧的提供程序上调用此函数，TAPI 会检测此情况并报告LINEERR_OPERATIONUNAVAIL。