ACMFILTERCHOOSE 結構 (msacm.h)

發行項
03/15/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]

當acmFilterTagDetails傳回的ACMFILTERTAGDETAILS結構時，包含描述篩選選取範圍篩選標記之 Null 終止字串的緩衝區。如果使用者取消對話方塊，這個成員將包含以 Null 結尾的字串。

szFilter[ACMFILTERDETAILS_FILTER_CHARS]

當acmFilterDetails傳回的ACMFILTERDETAILS結構時，包含以 Null 結束的字串，描述篩選選取範圍的篩選屬性。如果使用者取消對話方塊，這個成員將包含以 Null 結尾的字串。

pszName

使用者定義篩選名稱之字串的指標。如果這是非 Null 終止的字串，ACM 會嘗試比對名稱與先前儲存的使用者定義篩選名稱。如果找到相符專案，對話方塊就會初始化為該篩選。如果找不到相符專案，或此成員為 Null 終止字串，則會忽略此成員以供輸入使用。當 acmFilterChoose 函式傳回時，這個緩衝區會包含一個以 Null 結尾的字串，描述使用者定義的篩選準則。如果篩選名稱未命名為 (，則使用者尚未為篩選) 指定名稱，則傳回時，此成員會是以 Null 結尾的字串。如果使用者取消對話方塊，將不會對此緩衝區進行任何變更。

如果 fdwStyle 成員指定了ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT旗標， 則會忽略 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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
標頭	msacm.h