Функция lineConfigDialogEdit (tapi.h)

Статья
08/26/2023

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

Синтаксис

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

Параметры

dwDeviceID

Идентификатор настраиваемого линейного устройства.

hwndOwner

Дескриптор к окну, к которому будет присоединено диалоговое окно. Может иметь значение NULL , чтобы указать, что любое окно, созданное во время выполнения функции, не должно иметь окна-владельца.

lpszDeviceClass

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

lpDeviceConfigIn

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

dwSize

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

lpDeviceConfigOut

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

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

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

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM LINEERR_NODEVICE.

Если возвращается LINEERR_STRUCTURETOOSMALL, член dwTotalSize структуры VARSTRING , на который указывает lpDeviceConfigOut, не указывает достаточный объем памяти для хранения всей структуры конфигурации. Для элемента dwNeededSize задана необходимая сумма. В той степени, в которой записи пользователя были отражены в информации, которую не удалось вернуть из-за нехватки места, эти изменения теряются; Поэтому приложения должны выделить максимальный объем пространства, который может потребоваться классу устройства для возврата структуры конфигурации (дополнительные сведения см. в разделе Классы устройств TAPI).

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

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

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

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