TSPI_lineConfigDialogEdit 函数 (tspi.h)

项目
08/26/2023

TSPI_lineConfigDialogEdit函数已过时。 TAPI 版本 1.4 或更早版本的服务提供商可以实现此 TSPI 函数。 TAPI 版本 2.0 或更高版本的 TSP 实现 TUISPI_lineConfigDialogEdit。

TSPI_lineConfigDialogEdit 函数使指定线路设备的提供程序将模式对话框显示为 hwndOwner 的子窗口，以允许用户配置与线路设备相关的参数。

语法

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

参数

dwDeviceID

要配置的线路设备。

hwndOwner

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

lpszDeviceClass

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

lpDeviceConfigIn

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

dwSize

lpDeviceConfigIn 指向的结构中的字节数。此值在 varSTRING 结构中的 dwStringSize 成员中返回，该成员由 TSPI_lineGetDevConfig 或先前调用的 TSPI_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。

注解

此函数使服务提供程序显示附加到 hwndOwner) (模式对话框，以允许用户配置与 dwDeviceID 指定的行相关的参数。

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

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

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

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