ACMFILTERCHOOSE structure (msacm.h)

The ACMFILTERCHOOSE structure contains information the ACM uses to initialize the system-defined waveform-audio filter selection dialog box. After the user closes the dialog box, the system returns information about the user's selection in this structure.

Syntax

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;

Members

cbStruct

Size, in bytes, of the ACMFILTERCHOOSE structure. This member must be initialized before an application calls the acmFilterChoose function. The size specified in this member must be large enough to contain the base ACMFILTERCHOOSE structure.

fdwStyle

Optional style flags for the acmFilterChoose function. This member must be initialized to a valid combination of the following flags before an application calls the acmFilterChoose function. The following values are defined:

hwndOwner

Handle to the window that owns the dialog box. This member can be any valid window handle or NULL if the dialog box has no owner. This member must be initialized before calling the acmFilterChoose function.

pwfltr

Pointer to a WAVEFILTER structure. If the ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT flag is specified in the fdwStyle member, this structure must be initialized to a valid filter. When the acmFilterChoose function returns, this buffer contains the selected filter. If the user cancels the dialog box, no changes will be made to this buffer.

cbwfltr

Size, in bytes, of the buffer pointed to by the pwfltr member. The acmFilterChoose function returns ACMERR_NOTPOSSIBLE if the buffer is too small to contain the filter information; the ACM also copies the required size into this member. An application can use the acmMetrics and acmFilterTagDetails functions to determine the largest size required for this buffer.

pszTitle

Pointer to a string to be placed in the title bar of the dialog box. If this member is NULL, the ACM uses the default title (that is, "Filter Selection").

szFilterTag[ACMFILTERTAGDETAILS_FILTERTAG_CHARS]

Buffer containing a null-terminated string describing the filter tag of the filter selection when the ACMFILTERTAGDETAILS structure returned by acmFilterTagDetails. If the user cancels the dialog box, this member will contain a null-terminated string.

szFilter[ACMFILTERDETAILS_FILTER_CHARS]

Buffer containing a null-terminated string describing the filter attributes of the filter selection when the ACMFILTERDETAILS structure returned by acmFilterDetails. If the user cancels the dialog box, this member will contain a null-terminated string.

pszName

Pointer to a string for a user-defined filter name. If this is a non-null-terminated string, the ACM attempts to match the name with a previously saved user-defined filter name. If a match is found, the dialog box is initialized to that filter. If a match is not found or this member is a null-terminated string, this member is ignored for input. When the acmFilterChoose function returns, this buffer contains a null-terminated string describing the user-defined filter. If the filter name is untitled (that is, the user has not given a name for the filter), this member will be a null-terminated string on return. If the user cancels the dialog box, no changes will be made to this buffer.

If the ACMFILTERCHOOSE_STYLEF_INITTOFILTERSTRUCT flag is specified by the fdwStyle member, the pszName member is ignored as an input member.

cchName

Size, in characters, of the buffer identified by the pszName member. This buffer should be at least 128 characters long. If pszName is NULL, this member is ignored.

fdwEnum

Optional flags for restricting the type of filters listed in the dialog box. These flags are identical to the fdwEnum flags for the acmFilterEnum function. If pwfltrEnum is NULL, this member should be zero.

pwfltrEnum

Pointer to a WAVEFILTER structure that will be used to restrict the filters listed in the dialog box. The fdwEnum member defines which members of this structure should be used for the enumeration restrictions. The cbStruct member of this WAVEFILTER structure must be initialized to the size of the WAVEFILTER structure. If no special restrictions are desired, this member can be NULL.

hInstance

Handle to a data block that contains a dialog box template specified by the pszTemplateName member. This member is used only if the fdwStyle member specifies the ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE or ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATEHANDLE flag; otherwise, this member should be NULL on input.

pszTemplateName

Pointer to a null-terminated string that specifies the name of the resource file for the dialog box template that is to be substituted for the dialog box template in the ACM. An application can use the MAKEINTRESOURCE macro for numbered dialog box resources. This member is used only if the fdwStyle member specifies the ACMFILTERCHOOSE_STYLEF_ENABLETEMPLATE flag; otherwise, this member should be NULL on input.

lCustData

Application-defined data that the ACM passes to the hook function identified by the pfnHook member. The system passes the data in the lParam parameter of the WM_INITDIALOG message.

pfnHook

Pointer to a callback function that processes messages intended for the dialog box. An application must specify the ACMFILTERCHOOSE_STYLEF_ENABLEHOOK flag in the fdwStyle member to enable the hook; otherwise, this member should be NULL. The hook function should return FALSE to pass a message to the standard dialog box procedure or TRUE to discard the message. The callback function type is acmFilterChooseHookProc.

Requirements

See also

ACMFILTERDETAILS

ACMFILTERTAGDETAILS

Audio Compression Manager

Audio Compression Structures

MAKEINTRESOURCE

MM_ACM_FILTERCHOOSE

RegisterWindowMessage

WAVEFILTER

WM_INITDIALOG

acmFilterChoose

acmFilterDetails

acmFilterEnum

acmFilterTagDetails

acmMetrics