TSPI_lineGetDevConfig 函数 (tspi.h)

项目
08/26/2023

TSPI_lineGetDevConfig 函数返回一个数据结构对象，其内容特定于行 (服务提供商) 和设备类，为与线路设备关联的设备提供一对一的当前配置。

语法

LONG TSPIAPI TSPI_lineGetDevConfig(
  DWORD       dwDeviceID,
  LPVARSTRING lpDeviceConfig,
  LPCWSTR     lpszDeviceClass
);

参数

dwDeviceID

要配置的线路设备。

lpDeviceConfig

指向 VARSTRING 类型的数据结构的指针，其中返回关联设备的设备配置结构。成功完成请求后，服务提供商会用设备配置填充此数据结构。 VARSTRING 结构中的 dwStringFormat 成员必须设置为 STRINGFORMAT_BINARY。如果 lpDeviceConfig 参数指向的 VARSTRING 结构的 dwTotalSize 成员大于或等于结构的固定部分的大小，则服务提供程序会将 dwNeededSize 成员设置为所需大小并返回零。

lpszDeviceClass

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

返回值

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

LINEERR_INVALDEVICECLASS、LINEERR_NOMEM、LINEERR_INVALPOINTER、LINEERR_OPERATIONUNAVAIL、LINEERR_STRUCTURETOOSMALL、LINEERR_OPERATIONFAILED、LINEERR_NODRIVER、LINEERR_RESOURCEUNAVAIL。

注解

呼叫状态特定于设备。

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

服务提供商通常应在此功能下允许 tapi/line 设备类。它将检索具有“line”范围的参数，例如此行中的地址列表、物理硬件设备列表（如对应于地址的 COMM 端口）， (最大并发调用数（如果可配置) ，等等）。

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

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

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

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