функция TSPI_lineGetDevConfig (tspi.h)

Статья
08/26/2023

Функция TSPI_lineGetDevConfig возвращает объект структуры данных, содержимое которого относится к строке (поставщик услуг) и классу устройства, предоставляя текущую конфигурацию устройства, связанного "один к одному" с линейным устройством.

Синтаксис

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

Параметры

dwDeviceID

Настраиваемого линейного устройства.

lpDeviceConfig

Указатель на структуру данных типа VARSTRING , в которой возвращается структура конфигурации связанного устройства. После успешного выполнения запроса поставщик услуг заполняет эту структуру данных конфигурацией устройства. Член dwStringFormat в структуре VARSTRING должен иметь значение STRINGFORMAT_BINARY. Если элемент dwTotalSize структуры VARSTRING , на который указывает параметр lpDeviceConfig , больше или равен размеру фиксированной части структуры, поставщик услуг присваивает члену dwNeededSize необходимый размер и возвращает ноль.

lpszDeviceClass

Указатель на строку Юникода, завершающуюся значением NULL, которая указывает класс устройства, конфигурация которого запрашивается. Допустимые строки класса устройства совпадают с строками, указанными для функции 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 в рамках этой функции. Он будет извлекать параметры, имеющие область строки, например список адресов в этой строке, список физических аппаратных устройств, таких как порты COMM, соответствующие адресам, максимальное количество одновременных вызовов (если это возможно) и т. д.

Как правило, эта функция не разрешает классы устройств, связанных с мультимедиа, такие как классы устройств mci waveaudio, low level wave или datamodem, так как они обычно применяются к определенному вызову или определенному адресу. Так как на каждое линейное устройство может быть несколько из них, идентификация конкретного вызова или адреса по параметру идентификатора устройства линии в этой функции будет неоднозначной. Исключение можно сделать для классов устройств, относящихся к вызову или адресу, в случаях, когда есть сведения о конфигурации класса, которые применяются ко всему область линейного устройства, например начальные значения по умолчанию и т. д.

Существует несколько причин, по которым исключительная поддержка классов устройств для конкретных вызовов и адресов имеет только ограниченное значение в рамках этой функции. Во-первых, поскольку эти классы могут быть неоднозначными для поставщиков услуг с несколькими адресами или несколькими вызовами, их поддерживает только подмножество поставщиков услуг. Приложения вряд ли добавят зависимость от конкретного устройства от включения этих классов в эту функцию. Во-вторых, по мере появления "классов" носителей более высокого уровня, реализующих высокоуровневые протоколы, такие как доступ к файловой системе с телефонным подключением, с точки зрения низкоуровневых API транспорта, конфигурация для этих классов имеет тенденцию к "экземпляру" область вместо "класса" область. Высокоуровневый API мультимедиа должен предоставлять собственные функции для настройки экземпляров для конкретных вызовов или адресов.

Независимо от типа устройств и классов устройств, поддерживаемых этой функцией, они могут повлиять на два типа сведений о конфигурации: постоянные и временные. Постоянная информация сохраняется в разных "открытиях" линии и даже в разных "инициализациях" самого поставщика услуг. Временная информация сохраняется только в пределах уникальной "открытой" линии. При закрытии строки любые временные сведения, полученные или заданные с помощью TSPI_lineSetDevConfig, могут отменить изменения значениями по умолчанию или неопределенными. Вызывающий объект может надежно получить любую временную конфигурацию только с помощью такой последовательности, как TSPI_lineOpen, TSPI_lineConfigDialogTSPI_lineGetDevConfig. Вызывающий объект может надежно задать временные сведения о конфигурации, полученные такой последовательностью, через последовательность, например TSPI_lineOpen, TSPI_lineSetDevConfig. Временная часть конфигурации остается стабильной только до следующего TSPI_lineConfigDialog, TSPI_lineSetDevConfig или TSPI_lineClose. Поставщик услуг должен позаботиться о сохранении любой постоянной части конфигурации, как правило, в .ini файле, и ее перезагрузке при инициализации поставщика услуг.

Точный формат данных, содержащихся в структуре, возвращаемой этой функцией, специфичен для API класса строки и устройства, не является документированием и не определен. Структура, возвращаемая этой функцией, не может напрямую обращаться к приложению или управляться ими, но может быть сохранена без изменений, а затем использоваться в TSPI_lineSetDevConfig для восстановления параметров. Структура также не может быть обязательно передана другим устройствам, даже тому же классу устройств (хотя в некоторых случаях это может работать, это не гарантируется). Поставщик услуг должен поместить элементы в структуру данных, чтобы обеспечить ее проверку на согласованность, чтобы защититься от сбоев из-за передачи несовместимой информации клиентским приложением.