Структура ACMFILTERCHOOSE (msacm.h)

Статья
03/15/2023

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

Синтаксис

typedef struct tACMFILTERCHOOSE {
  DWORD                   cbStruct;
  DWORD                   fdwStyle;
  HWND                    hwndOwner;
  LPWAVEFILTER            pwfltr;
  DWORD                   cbwfltr;
  LPCSTR                  pszTitle;
  char                    szFilterTag[ACMFILTERTAGDETAILS_FILTERTAG_CHARS];
  char                    szFilter[ACMFILTERDETAILS_FILTER_CHARS];
  LPSTR                   pszName;
  DWORD                   cchName;
  DWORD                   fdwEnum;
  LPWAVEFILTER            pwfltrEnum;
  HINSTANCE               hInstance;
  LPCSTR                  pszTemplateName;
  LPARAM                  lCustData;
  ACMFILTERCHOOSEHOOKPROC pfnHook;
} ACMFILTERCHOOSE, *PACMFILTERCHOOSE, *LPACMFILTERCHOOSE;

Члены

cbStruct

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

fdwStyle

Необязательные флаги стиля для функции acmFilterChoose . Этот элемент должен быть инициализирован допустимым сочетанием следующих флагов, прежде чем приложение вызовет функцию acmFilterChoose . Определены следующие значения:

Имя	Описание
ACMFILTERCHOOSE_STYLEF_CONTEXTHELP	Контекстно-зависимые справки будут доступны в диалоговом окне. Чтобы использовать эту функцию, приложение должно зарегистрировать константы ACMHELPMSGCONTEXTMENU и ACMHELPMSGCONTEXTHELP с помощью функции RegisterWindowMessage . Когда пользователь вызывает справку, зарегистрированное сообщение будет опубликовано в окне владельцев. Сообщение будет содержать параметры wParam и lParam из исходного WM_CONTEXTMENU или WM_CONTEXTHELP сообщения.
ACMFILTERCHOOSE_STYLEF_ENABLEHOOK	Включает функцию-перехватчик, указанную в элементе pfnHook . Приложение может использовать функции-перехватчики для различных настроек, включая ответы на MM_ACM_FILTERCHOOSE сообщение.
ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE	Заставляет ACM создать шаблон диалогового окна, определяемый элементами hInstance и pszTemplateName .
ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE	Элемент hInstance определяет блок данных, содержащий предварительно загруженный шаблон диалогового окна. Если этот флаг указан, ACM игнорирует элемент pszTemplateName .
ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT	Буфер, на который указывает pwfltr , содержит допустимую структуру WAVEFILTER , которую диалоговое окно будет использовать в качестве начального выбора.
ACMFILTERCHOOSE_STYLEF_SHOWHELP	В диалоговом окне появится кнопка справки. Чтобы использовать пользовательский файл справки, приложение должно зарегистрировать значение ACMHELPMSGSTRING с помощью функции RegisterWindowMessage . Когда пользователь нажимает кнопку справки, зарегистрированное сообщение публикуется владельцу.

hwndOwner

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

pwfltr

Указатель на структуру WAVEFILTER . Если флаг ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT указан в элементе fdwStyle , эта структура должна быть инициализирована допустимым фильтром. При возврате функции acmFilterChoose этот буфер содержит выбранный фильтр. Если пользователь отменит диалоговое окно, изменения в этом буфере не будут вноситься.

cbwfltr

Размер (в байтах) буфера, на который указывает элемент pwfltr . Функция acmFilterChoose возвращает ACMERR_NOTPOSSIBLE, если буфер слишком мал, чтобы содержать сведения о фильтре; ACM также копирует требуемый размер в этот элемент. Приложение может использовать функции acmMetrics и acmFilterTagDetails для определения максимального размера, необходимого для этого буфера.

pszTitle

Указатель на строку, помещаемую в заголовок диалогового окна. Если этот элемент имеет значение NULL, ACM использует заголовок по умолчанию (т. е. "Фильтр выбора").

szFilterTag[ACMFILTERTAGDETAILS_FILTERTAG_CHARS]

Буфер, содержащий строку, завершающуюся значением NULL, описывающую тег фильтра при выборе структуры ACMFILTERTAGDETAILS , возвращаемой acmFilterTagDetails. Если пользователь отменит диалоговое окно, этот элемент будет содержать строку, завершаемую null.

szFilter[ACMFILTERDETAILS_FILTER_CHARS]

Буфер, содержащий строку, завершающуюся значением NULL, описывающую атрибуты фильтра при выборе структуры ACMFILTERDETAILS , возвращаемой acmFilterDetails. Если пользователь отменит диалоговое окно, этот элемент будет содержать строку, завершаемую null.

pszName

Указатель на строку для определяемого пользователем имени фильтра. Если это строка, не завершающаяся null, ACM пытается сопоставить имя с ранее сохраненным именем определяемого пользователем фильтра. Если совпадение найдено, диалоговое окно инициализируется этим фильтром. Если совпадение не найдено или этот элемент является строкой, завершаемой null, этот элемент игнорируется для входных данных. При возврате функции acmFilterChoose этот буфер содержит строку, завершающуюся значением NULL, описывающую определяемый пользователем фильтр. Если имя фильтра без названия (т. е. пользователь не дал имя фильтра), этот элемент будет строкой, завершающейся нулевым значением, при возврате. Если пользователь отменит диалоговое окно, изменения в этом буфере не будут вноситься.

Если флаг ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT указан элементом fdwStyle , элемент pszName игнорируется как входной элемент.

cchName

Размер (в символах) буфера, определяемого элементом pszName . Длина этого буфера должна быть не менее 128 символов. Если pszName имеет значение NULL, этот элемент игнорируется.

fdwEnum

Необязательные флаги для ограничения типа фильтров, перечисленных в диалоговом окне. Эти флаги идентичны флагам fdwEnum для функции acmFilterEnum . Если pwfltrEnum имеет значение NULL, этот элемент должен быть равен нулю.

Имя	Описание
ACM_FILTERENUMF_DWFILTERTAG	Элемент dwFilterTag структуры WAVEFILTER , на который указывает элемент pwfltrEnum, является допустимым . Перечислитель будет перечислять только фильтр, соответствующий этому атрибуту.

pwfltrEnum

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

hInstance

Дескриптор блока данных, содержащего шаблон диалогового окна, указанный элементом pszTemplateName . Этот элемент используется только в том случае, если элемент fdwStyle задает флаг ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE или ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE; в противном случае этот элемент должен иметь значение NULL на входных данных.

pszTemplateName

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

lCustData

Определяемые приложением данные, которые ACM передает в функцию-перехватчик, определяемую элементом pfnHook . Система передает данные в параметре lParamсообщения WM_INITDIALOG .

pfnHook

Указатель на функцию обратного вызова, которая обрабатывает сообщения, предназначенные для диалогового окна. Чтобы включить перехватчик, приложение должно указать флаг ACMFILTERCHOOSE_STYLEF_ENABLEHOOK в элементе fdwStyle ; В противном случае этот элемент должен иметь значение NULL. Функция перехватчика должна возвращать значение FALSE для передачи сообщения стандартной процедуре диалогового окна или TRUE , чтобы отменить сообщение. Тип функции обратного вызова — acmFilterChooseHookProc.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхняя часть	msacm.h