lineConfigDialogEdit 函数 (tapi.h)

项目
08/26/2023

lineConfigDialogEdit 函数使指定线路设备的提供程序显示一个对话框， (附加到应用程序的 hwndOwner) ，以允许用户配置与线路设备相关的参数。

语法

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

参数

dwDeviceID

要配置的线路设备的标识符。

hwndOwner

对话框要附加到的窗口的句柄。可以为 NULL ，表示在函数期间创建的任何窗口都应没有所有者窗口。

lpszDeviceClass

指向以 null 结尾的字符串的指针，该字符串标识设备类名称。此设备类允许应用程序选择适用于该设备类的配置信息的特定子屏幕。此参数是可选的，可以保留 NULL 或空，在这种情况下，会选择最高级别的配置。

lpDeviceConfigIn

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

dwSize

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

lpDeviceConfigOut

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

返回值

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

LINEERR_BADDEVICEID、LINEERR_OPERATIONFAILED、LINEERR_INVALDEVICECLASS、LINEERR_RESOURCEUNAVAIL、LINEERR_INVALPARAM、LINEERR_STRUCTURETOOSMALL、LINEERR_INVALPOINTER、LINEERR_UNINITIALIZED、LINEERR_NODRIVER、LINEERR_OPERATIONUNAVAIL、LINEERR_NOMEM、LINEERR_NODEVICE。

注解

如果返回LINEERR_STRUCTURETOOSMALL，则 lpDeviceConfigOut 指向的 VARSTRING 结构的 dwTotalSize 成员未指定足够的内存来包含整个配置结构。 dwNeededSize 成员已设置为所需的量。如果用户条目反映在由于空间不足而无法返回的信息中，则这些编辑将丢失;因此，应用程序应分配设备类返回其配置结构所需的最大空间量， (有关详细信息，请参阅 TAPI 设备类) 。

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

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

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

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