TSPI_lineSetDevConfig 函数 (tspi.h)

项目
08/26/2023

TSPI_lineSetDevConfig 函数从以前使用 TSPI_lineGetDevConfig 获取的数据结构中还原与线路设备关联的设备一对一的配置。此数据结构的内容特定于行 [服务提供商] 和设备类。

语法

LONG TSPIAPI TSPI_lineSetDevConfig(
  DWORD        dwDeviceID,
  LPVOID const lpDeviceConfig,
  DWORD        dwSize,
  LPCWSTR      lpszDeviceClass
);

参数

dwDeviceID

要配置的线路设备。

lpDeviceConfig

指向在 VARSTRING 结构的变量部分TSPI_lineGetDevConfig返回的配置数据结构的指针。

dwSize

lpDeviceConfig 指向的结构中的字节数。此值在 TSPI_lineGetDevConfig 返回的 VARSTRING 结构中的 dwStringSize 成员中返回。

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

lpszDeviceClass

指向以 null 结尾的 Unicode 字符串的指针，该字符串指定要还原其配置的设备的设备类。当有效设备类字符串应用于“line”设备 (时，有效设备类字符串与为 TSPI_lineGetID 函数指定的字符串相同，即当 dwSelect 具有值LINECALLSELECT_LINE) 时。

返回值

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

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

注解

呼叫状态特定于设备。

如果 lpDeviceConfig 指向的结构中包含的信息对此设备无效，则服务提供商将返回LINEERR_INVALPARAM。

如果无法在当前行状态下更改设备配置，则服务提供商将返回LINEERR_INVALLINESTATE。另一个应用程序可能正在使用该行。

此函数可用于从以前使用 TSPI_lineGetDevConfig 函数从服务提供商检索的数据结构中还原与线路设备一对一关联的设备的配置。 lpszDeviceClass 参数选择在多个不同设备类别中还原其配置的设备。支持的类集仅限于其设备与线路设备一对一对应的类。有关常见设备类的详细信息，请参阅 TSPI 设备类。

服务提供商通常允许在此函数下使用 tapi/line 设备类。它还原具有“line”范围的参数，例如此行中的地址列表和物理硬件设备列表（如与地址相对应的 COMM 端口），或最大并发调用数 (（如果可配置) ）。

通常，此函数不允许媒体相关的设备类（如 mci waveaudio、低级别波形或 datamodem 设备类），因为这些类通常适用于特定调用或特定地址。由于每个线路设备可以有多个此类设备，因此仅通过此函数中的线路设备标识符参数来标识特定呼叫或地址并不明确。如果存在适用于整个线路设备范围的类配置信息（例如初始默认值），则可以对特定于呼叫的设备类或特定于地址的设备类发出异常。

有几个原因导致对特定于呼叫和地址特定的设备类的例外支持在此函数下的价值有限。首先，由于这些类在多地址、多调用服务提供商上可能不明确，因此只有一部分服务提供商支持它们。应用程序不太可能添加特定于设备的依赖项，包括此函数中的这些类。其次，随着更高级别的媒体类的出现，这些类在低级别传输 API 方面实现了高级协议（如文件系统的拨入访问），这些类的配置倾向于实例范围而不是类范围。高级媒体 API 必须提供自己的函数来配置特定于调用或特定于地址的实例。

无论此函数支持哪种类型的设备和设备类，它都可能影响两种类型的配置信息：永久和临时。永久信息在线路的不同“打开”中生存，甚至跨服务提供商本身的不同“初始化”。临时信息仅在行的唯一“打开”内保留。关闭行后，通过TSPI_lineGetDevConfig设置或检索的任何此类临时信息都可以还原为默认值或未定义值。调用方只能按 TSPI_lineOpen、 TSPI_lineConfigDialog、 TSPI_lineGetDevConfig等顺序可靠地检索任何临时配置。调用方可以通过 TSPI_lineOpen、TSPI_lineSetDevConfig等序列可靠地设置此类序列检索的临时配置信息。配置的临时部分仅在下一 个TSPI_lineConfigDialog、 TSPI_lineSetDevConfig或 TSPI_lineClose之前保持稳定。服务提供商必须负责存储配置的任何永久部分（通常存储在 .ini 文件中），并在服务提供程序初始化时重新加载它。

传递给此函数的结构中包含的数据的确切格式特定于行和设备类 API，未记录且未定义。传递给此函数的结构不能由应用程序直接访问或操作，但只能保持不变地存储，然后从以前的 TSPI_lineGetDevConfig 使用以获取设置。结构也不一定可以传递给其他设备，即使是同一个设备类 (尽管在某些情况下可能正常工作，但不能保证) 。服务提供商应检查此数据结构以确保一致性，以防止由于客户端应用程序传递不兼容信息而导致的故障。

注意某些服务提供商可能允许在设备使用时设置配置，而其他服务提供商可能不允许。