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

Статья
08/24/2023

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

Синтаксис

typedef struct tACMFORMATCHOOSE {
  DWORD                   cbStruct;
  DWORD                   fdwStyle;
  HWND                    hwndOwner;
  LPWAVEFORMATEX          pwfx;
  DWORD                   cbwfx;
  LPCSTR                  pszTitle;
  char                    szFormatTag[ACMFORMATTAGDETAILS_FORMATTAG_CHARS];
  char                    szFormat[ACMFORMATDETAILS_FORMAT_CHARS];
  LPSTR                   pszName;
  DWORD                   cchName;
  DWORD                   fdwEnum;
  LPWAVEFORMATEX          pwfxEnum;
  HINSTANCE               hInstance;
  LPCSTR                  pszTemplateName;
  LPARAM                  lCustData;
  ACMFORMATCHOOSEHOOKPROC pfnHook;
} ACMFORMATCHOOSE, *PACMFORMATCHOOSE, *LPACMFORMATCHOOSE;

Члены

cbStruct

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

fdwStyle

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

Имя	Описание
ACMFORMATCHOOSE_STYLEF_CONTEXTHELP	Контекстно-чувствительная справка будет доступна в диалоговом окне. Чтобы использовать эту функцию, приложение должно зарегистрировать константы ACMHELPMSGCONTEXTMENU и ACMHELPMSGCONTEXTHELP с помощью функции RegisterWindowMessage . Когда пользователь вызывает справку, зарегистрированное сообщение будет опубликовано в окне владельцев. Сообщение будет содержать параметры wParam и lParam из исходного WM_CONTEXTMENU или WM_CONTEXTHELP сообщения.
ACMFORMATCHOOSE_STYLEF_ENABLEHOOK	Включает функцию перехватчика, на которую указывает член pfnHook . Приложение может использовать функции перехватчика для различных настроек, включая ответы на MM_ACM_FORMATCHOOSE сообщение.
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE	Заставляет ACM создать шаблон диалогового окна, определяемый hInstance и pszTemplateName.
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE	Элемент hInstance определяет блок данных, содержащий предварительно загруженный шаблон диалогового окна. Если этот флаг указан, ACM игнорирует элемент pszTemplateName .
ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT	Буфер, на который указывает pwfx , содержит допустимую структуру WAVEFORMATEX , которую диалоговое окно будет использовать в качестве начального выбора.
ACMFORMATCHOOSE_STYLEF_SHOWHELP	В диалоговом окне появится кнопка справки. Чтобы использовать пользовательский файл справки, приложение должно зарегистрировать константу ACMHELPMSGSTRING с помощью функции RegisterWindowMessage . Когда пользователь нажимает кнопку "Справка", зарегистрированное сообщение будет отправлено владельцу.

hwndOwner

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

pwfx

Указатель на структуру WAVEFORMATEX . Если флаг ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT указан в элементе fdwStyle , эта структура должна быть инициализирована в допустимом формате. Когда функция acmFormatChoose возвращает значение , этот буфер содержит выбранный формат. Если пользователь отменит диалоговое окно, изменения в этом буфере не будут вноситься.

cbwfx

Размер (в байтах) буфера, на который указывает pwfx. Если буфер слишком мал для хранения сведений о формате, функция acmFormatChoose возвращает ACMERR_NOTPOSSIBLE. Кроме того, ACM копирует необходимый размер в этот элемент. Приложение может использовать функции acmMetrics и acmFormatTagDetails , чтобы определить максимальный размер, необходимый для этого буфера.

pszTitle

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

szFormatTag[ACMFORMATTAGDETAILS_FORMATTAG_CHARS]

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

szFormat[ACMFORMATDETAILS_FORMAT_CHARS]

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

pszName

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

cchName

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

fdwEnum

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

Имя	Описание
ACM_FORMATENUMF_CONVERT	Допустимая структура WAVEFORMATEX , на которую указывает член pwfxEnum . Перечислитель перечисляет только форматы назначения, которые можно преобразовать из заданного формата pwfxEnum .
ACM_FORMATENUMF_HARDWARE	Перечислитель должен перечислять только форматы, поддерживаемые на оборудовании одним или несколькими установленными устройствами waveform-audio. Этот флаг позволяет приложению выбирать только собственные форматы для установленного устройства waveform-audio.
ACM_FORMATENUMF_INPUT	Перечислитель должен перечислять только форматы, поддерживаемые для ввода (записи).
ACM_FORMATENUMF_NCHANNELS	Элемент nChannels структуры WAVEFORMATEX , на который указывает элемент pwfxEnum, является допустимым . Перечислитель будет перечислять только формат, соответствующий этому атрибуту.
ACM_FORMATENUMF_NSAMPLESPERSEC	Элемент nSamplesPerSec структуры WAVEFORMATEX , на который указывает элемент pwfxEnum, является допустимым . Перечислитель будет перечислять только формат, соответствующий этому атрибуту.
ACM_FORMATENUMF_OUTPUT	Перечислитель должен перечислять только форматы, которые поддерживаются для вывода (воспроизведения).
ACM_FORMATENUMF_SUGGEST	Допустимая структура WAVEFORMATEX , на которую указывает член pwfxEnum . Перечислитель перечисляет все предлагаемые форматы назначения для заданного формата pwfxEnum .
ACM_FORMATENUMF_WBITSPERSAMPLE	Член wBitsPerSample структуры WAVEFORMATEX , на который указывает элемент pwfxEnum, является допустимым . Перечислитель будет перечислять только формат, соответствующий этому атрибуту.
ACM_FORMATENUMF_WFORMATTAG	Член wFormatTag структуры WAVEFORMATEX , на который указывает элемент pwfxEnum, является допустимым . Перечислитель будет перечислять только формат, соответствующий этому атрибуту.

pwfxEnum

Указатель на структуру WAVEFORMATEX , которая будет использоваться для ограничения форматов, перечисленных в диалоговом окне. Член fdwEnum определяет элементы структуры, на которую указывает pwfxEnum , которые должны использоваться для ограничений перечисления. Если никаких специальных ограничений не требуется, этот элемент может иметь значение NULL. Другие требования, связанные с элементом pwfxEnum , см. в описании функции acmFormatEnum .

hInstance

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

pszTemplateName

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

lCustData

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

pfnHook

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

Требования


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