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

Статья
08/26/2023

Функция TSPI_lineConfigDialogEdit устарела. Поставщики служб TAPI версии 1.4 или более ранних версий могут реализовать эту функцию TSPI. TAPI версии 2.0 или более поздней TSP реализуют TUISPI_lineConfigDialogEdit.

Функция TSPI_lineConfigDialogEdit приводит к тому, что поставщик указанного линейного устройства отображает модальное диалоговое окно как дочернее окно hwndOwner, чтобы разрешить пользователю настраивать параметры, связанные с линейным устройством.

Синтаксис

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

Параметры

dwDeviceID

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

hwndOwner

Дескриптор окна, к которому нужно присоединить диалоговое окно.

lpszDeviceClass

Указатель на строку Юникода, завершающуюся значением NULL, которая идентифицирует имя класса устройства. Этот класс устройства позволяет вызывающей стороны выбрать определенный подэкран сведений о конфигурации, применимых к этому классу устройства. Если этот параметр имеет значение NULL или указывает на пустую строку, выбирается конфигурация самого высокого уровня. Допустимые строки совпадают с TSPI_lineGetID.

lpDeviceConfigIn

Указатель на непрозрачную структуру данных конфигурации, возвращенную TSPI_lineGetDevConfig (или предыдущий вызов TSPI_lineConfigDialogEdit) в переменной части структуры VARSTRING .

dwSize

Число байтов в структуре, на которую указывает lpDeviceConfigIn. Это значение возвращается в члене dwStringSize в структуре VARSTRING , возвращаемой TSPI_lineGetDevConfig или предыдущим вызовом TSPI_lineConfigDialogEdit.

lpDeviceConfigOut

Указатель на расположение памяти типа VARSTRING , где возвращается структура конфигурации устройства. После успешного выполнения запроса это расположение заполняется конфигурацией устройства. Член dwStringFormat в структуре VARSTRING имеет значение STRINGFORMAT_BINARY. Перед вызовом lineGetDevConfig (или последующим вызовом lineConfigDialogEdit) приложение должно задать член dwTotalSize этой структуры, чтобы указать объем памяти, доступный ДЛЯ TAPI для возврата информации.

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

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

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

Эта функция заставляет поставщика услуг отображать модальное диалоговое окно (присоединенное к hwndOwner), чтобы разрешить пользователю настраивать параметры, связанные со строкой, заданной dwDeviceID.

Параметр lpszDeviceClass выбирает определенный подэкран сведений о конфигурации, применимый к классу устройства, в котором заинтересован пользователь; допустимые строки такие же, как и для TSPI_lineGetID. Например, если строка поддерживает API Comm, передача comm/datamodem как lpszDeviceClass приводит к тому, что поставщик отображает параметры, связанные с Comm (или, по крайней мере, начинается в соответствующей точке в цепочке диалоговых окон многоуровневой конфигурации, поэтому пользователю не нужно "копать", чтобы найти интересующие параметры).

Параметр lpszDeviceClass имеет значение "tapi/line", "" или NULL , чтобы поставщик отображал конфигурацию самого высокого уровня для строки.

Разница между этой функцией и TSPI_lineConfigDialog является источником редактируемых параметров и результатом редактирования. В TSPI_lineConfigDialog редактируемые параметры — это параметры, используемые в настоящее время на устройстве (или заданные для использования при следующем вызове), а любые внесенные изменения (по возможности) немедленно влияют на любое активное подключение; Кроме того, приложение должно использовать lineGetDevConfig для получения результата изменения параметров из TSPI_lineConfigDialog. При TSPI_lineConfigDialogEdit параметры для редактирования передаются из приложения, а результаты возвращаются в приложение, не влияя на активные подключения; Результаты редактирования возвращаются с помощью этой функции, и приложению не нужно вызывать lineGetDevConfig. Таким образом, TSPI_lineConfigDialogEdit позволяет приложению предоставлять пользователю возможность настраивать параметры для будущих вызовов, не влияя на активный вызов. Однако выходные данные этой функции можно передать TSPI_lineSetDevConfig , чтобы повлиять на текущий или следующий вызов.

Для обеспечения обратной совместимости эта функция не экспортируется старыми поставщиками услуг. TAPI обнаруживает это условие и сообщает LINEERR_OPERATIONUNAVAIL, если приложение пытается вызвать эту функцию в более старом поставщике.