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

Статья
03/08/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. Это значение возвращается в члене dwStringSize в структуре VARSTRING , возвращаемой TSPI_lineGetDevConfig.

Примечание Если параметры размера в структуре неверны, существует вероятность того, что данные могут быть перезаписаны. Дополнительные сведения о настройке размеров структуры см. в разделе о выделении памяти .

lpszDeviceClass

Указатель на строку Юникода, завершающуюся значением NULL, которая указывает класс устройства, конфигурация которого требуется восстановить. Допустимые строки класса устройства совпадают с строками, указанными для функции TSPI_lineGetID при ее применении к устройству line (т. е. если dwSelect имеет значение LINECALLSELECT_LINE).

Возвращаемое значение

Возвращает ноль, если функция выполнена успешно, или номер ошибки при возникновении ошибки. Возможные возвращаемые значения:

LINEERR_INVALDEVICECLASS, LINEERR_NOMEM, LINEERR_INVALPOINTER, LINEERR_OPERATIONUNAVAIL, LINEERR_INVALPARAM, LINEERR_OPERATIONFAILED, LINEERR_INVALLINESTATE, LINEERR_RESOURCEUNAVAIL LINEERR_NODRIVER.

Поставщик услуг возвращает LINEERR_INVALLINESTATE, если конфигурация устройства не может быть изменена в текущем состоянии строки. Строка может использоваться другим приложением.

Эту функцию можно использовать для восстановления конфигурации устройства, связанного "один к одному" с линейным устройством из структуры данных, ранее полученной от поставщика услуг, с помощью функции TSPI_lineGetDevConfig . Параметр lpszDeviceClass определяет, какой из возможных классов устройств должен восстановить конфигурацию. Набор поддерживаемых классов ограничен теми классами, устройства которых соответствуют одному с линейным устройством. Дополнительные сведения об общих классах устройств см. в разделе Классы устройств TSPI.

Поставщик услуг обычно разрешает класс устройства tapi/line в рамках этой функции. Он восстанавливает параметры, имеющие область "line", например список адресов в этой строке и список физических аппаратных устройств, таких как порты COMM, соответствующие адресам или максимальному количеству одновременных вызовов (если это возможно).

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

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

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

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

Примечание Некоторые поставщики услуг могут разрешить настройку конфигурации во время использования устройства, а другие — нет.