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

Статья
08/26/2023

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

Реализация является необязательной.

Синтаксис

LONG TSPIAPI TUISPI_lineConfigDialogEdit(
  TUISPIDLLCALLBACK lpfnUIDLLCallback,
  DWORD             dwDeviceID,
  HWND              hwndOwner,
  LPCWSTR           lpszDeviceClass,
  LPVOID const      lpDeviceConfigIn,
  DWORD             dwSize,
  LPVARSTRING       lpDeviceConfigOut
);

Параметры

lpfnUIDLLCallback

Указатель на функцию, которую библиотека DLL пользовательского интерфейса может вызывать для взаимодействия с библиотекой DLL поставщика услуг для получения сведений, необходимых для отображения диалогового окна.

dwDeviceID

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

hwndOwner

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

lpszDeviceClass

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

lpDeviceConfigIn

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

dwSize

Число байтов в структуре, на которую указывает lpDeviceConfigIn. Это значение возвращается в члене dwStringSize в структуре VARSTRING , возвращаемой TSPI_lineGetDevConfig или предыдущим вызовом TUISPI_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.

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

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

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

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