ACMFILTERCHOOSE 结构 (msacm.h)

项目
08/24/2023

ACMFILTERCHOOSE 结构包含 ACM 用于初始化系统定义的波形音频筛选器选择对话框的信息。用户关闭对话框后，系统会返回有关此结构中用户选择的信息。

语法

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	对话框中将提供上下文相关帮助。若要使用此功能，应用程序必须使用 RegisterWindowMessage 函数注册 ACMHELPMSGCONTEXTMENU 和 ACMHELPMSGCONTEXTHELP 常量。当用户调用帮助时，注册的消息将发布到拥有窗口。消息将包含原始WM_CONTEXTMENU或WM_CONTEXTHELP消息中的 wParam 和 lParam 参数。
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	对话框中将显示一个帮助按钮。若要使用自定义帮助文件，应用程序必须使用 RegisterWindowMessage 函数注册 ACMHELPMSGSTRING 值。当用户按下帮助按钮时，注册的消息将发布到所有者。

hwndOwner

对话框所在的窗口的句柄。此成员可以是任何有效的窗口句柄，如果对话框没有所有者，则为 NULL 。在调用 acmFilterChoose 函数之前，必须初始化此成员。

pwfltr

指向 WAVEFILTER 结构的指针。如果在 fdwStyle 成员中指定了 ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT 标志，则必须将此结构初始化为有效的筛选器。当 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 结尾的字符串，用于描述用户定义的筛选器。如果筛选器名称未命名 (即用户尚未为筛选器) 指定名称，则返回时此成员将是以 null 结尾的字符串。如果用户取消对话框，则不会对此缓冲区进行更改。

如果 ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT 标志由 fdwStyle 成员指定，则将 pszName 成员忽略为输入成员。

cchName

pszName 成员标识的缓冲区的大小（以字符为单位）。此缓冲区的长度应至少为 128 个字符。如果 pszName 为 NULL，则忽略此成员。

fdwEnum

用于限制对话框中列出的筛选器类型的可选标志。这些标志与 acmFilterEnum 函数的 fdwEnum 标志相同。如果 pwfltrEnum 为 NULL，则此成员应为零。

名称	说明
ACM_FILTERENUMF_DWFILTERTAG	pwfltrEnum 成员指向的 WAVEFILTER 结构的 dwFilterTag 成员有效。枚举器将仅枚举符合此属性的筛选器。

pwfltrEnum

指向 WAVEFILTER 结构的指针，该结构将用于限制对话框中列出的筛选器。 fdwEnum 成员定义此结构的哪些成员应用于枚举限制。此 WAVEFILTER 结构的 cbStruct 成员必须初始化为 WAVEFILTER 结构的大小。如果不需要特殊限制，则此成员可以为 NULL。

hInstance

包含 由 pszTemplateName 成员指定的对话框模板的数据块的句柄。仅当 fdwStyle 成员指定ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE或ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE标志时，才使用此成员;否则，此成员在输入时应为 NULL 。

pszTemplateName

指向以 null 结尾的字符串的指针，该字符串指定要在 ACM 中替换对话框模板的对话框模板的资源文件的名称。应用程序可以将 MAKEINTRESOURCE 宏用于编号对话框资源。仅当 fdwStyle 成员指定ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE标志时，才使用此成员;否则，此成员在输入时应为 NULL 。

lCustData

ACM 传递给 pfnHook 成员标识的挂钩函数的应用程序定义数据。系统传递WM_INITDIALOG消息的 lParam 参数中的数据。

pfnHook

指向回调函数的指针，该函数处理用于对话框的消息。应用程序必须在 fdwStyle 成员中指定 ACMFILTERCHOOSE_STYLEF_ENABLEHOOK 标志才能启用挂钩;否则，此成员应为 NULL。挂钩函数应返回 FALSE 以将消息传递到标准对话框过程，或 返回 TRUE 以放弃消息。回调函数类型为 acmFilterChooseHookProc。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	msacm.h