ACMFORMATCHOOSE  PJJ7UD 

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

typedef struct { 

    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;

 

Members

cbStruct

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

fdwStyle

Optional style flags for the acmFormatChoose function. This member must be initialized to a valid combination of the following flags before an application calls the acmFormatChoose function:

ACMFORMATCHOOSE_STYLEF_CONTEXTHELP

Context-sensitive help will be available in the dialog box. To use this feature, an application must register the ACMHELPMSGCONTEXTMENU and ACMHELPMSGCONTEXTHELP constants, using the RegisterWindowMessageXKGSV4 function. When the user invokes help, the registered message will be posted to the owning window. The message will contain the wParam and lParam parameters from the original WM_CONTEXTMENU or WM_CONTEXTHELP message.

ACMFORMATCHOOSE_STYLEF_ENABLEHOOK

Enables the hook function pointed to by the pfnHook member. An application can use hook functions for a variety of customizations, including answering the MM_ACM_FORMATCHOOSEJA9SHM message.

ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE

Causes the ACM to create the dialog box template identified by hInstance and pszTemplateName.

ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE

The hInstance member identifies a data block that contains a preloaded dialog box template. If this flag is specified, the ACM ignores the pszTemplateName member.

ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT

The buffer pointed to by pwfx contains a valid WAVEFORMATEX2R_J_MS structure that the dialog box will use as the initial selection.

ACMFORMATCHOOSE_STYLEF_SHOWHELP

A help button will appear in the dialog box. To use a custom Help file, an application must register the ACMHELPMSGSTRING constant with the RegisterWindowMessageXKGSV4 function. When the user presses the help button, the registered message will be posted to the owner.

hwndOwner

Handle of 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 acmFormatChoose21ZW2Z0 function.

pwfx

Address of a WAVEFORMATEX2R_J_MS structure. If the ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT flag is specified in the fdwStyle member, this structure must be initialized to a valid format. When the acmFormatChoose function returns, this buffer contains the selected format. If the user cancels the dialog box, no changes will be made to this buffer.

cbwfx

Size, in bytes, of the buffer pointed to by pwfx. If the buffer is too small to contain the format information, the acmFormatChoose21ZW2Z0 function returns ACMERR_NOTPOSSIBLE. Also, the ACM copies the required size into this member. An application can use the acmMetrics0KXYCH and acmFormatTagDetailsB6RNTS functions to determine the largest size required for this buffer.

pszTitle

Address of 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,  Sound Selection ).

szFormatTag

Buffer containing a null-terminated string describing the format tag of the format selection when the acmFormatChoose21ZW2Z0 function returns. This string is equivalent to the szFormatTag member of the ACMFORMATTAGDETAILS1TMI6GO structure returned by the acmFormatTagDetailsB6RNTS function. If the user cancels the dialog box, this member will contain a null-terminated string.

szFormat

Buffer containing a null-terminated string describing the format attributes of the format selection when the acmFormatChoose function returns. This string is equivalent to the szFormat member of the ACMFORMATDETAILSF_CHY8 structure returned by the acmFormatDetailsIYE5PC function. If the user cancels the dialog box, this member will contain a null-terminated string.

pszName

Address of a string for a user-defined format name. If this is a non-null-terminated string, the ACM will attempt to match the name with a previously saved user-defined format name. If a match is found, the dialog box is initialized to that format. If a match is not found or this member is a null-terminated string, this member is ignored on input. When the acmFormatChoose21ZW2Z0 function returns, this buffer contains a null-terminated string describing the user-defined format. If the format name is untitled (that is, the user has not given a name for the format), 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 ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT flag is specified in the fdwStyle member, the pszName member is ignored for input.

cchName

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

fdwEnum

Optional flags for restricting the type of formats listed in the dialog box. These flags are identical to the fdwEnum flags for the acmFormatEnum5S26_I2 function. If pwfxEnum is NULL, this member should be zero. The following values are defined:

ACM_FORMATENUMF_CONVERT

The WAVEFORMATEX2R_J_MS structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only destination formats that can be converted from the given pwfxEnum format.

ACM_FORMATENUMF_HARDWARE

The enumerator should enumerate only formats that are supported in hardware by one or more of the installed waveform-audio devices. This flag provides a way for an application to choose only formats native to an installed waveform-audio device.

ACM_FORMATENUMF_INPUT

The enumerator should enumerate only formats that are supported for input (recording).

ACM_FORMATENUMF_NCHANNELS

The nChannels member of the WAVEFORMATEX2R_J_MS structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_NSAMPLESPERSEC

The nSamplesPerSec member of the WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_OUTPUT

The enumerator should enumerate only formats that are supported for output (playback).

ACM_FORMATENUMF_SUGGEST

The WAVEFORMATEX2R_J_MS structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate all suggested destination formats for the given pwfxEnum format.

ACM_FORMATENUMF_WBITSPERSAMPLE

The wBitsPerSample member of the WAVEFORMATEX structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

ACM_FORMATENUMF_WFORMATTAG

The wFormatTag member of the WAVEFORMATEX2R_J_MS structure pointed to by the pwfxEnum member is valid. The enumerator will enumerate only a format that conforms to this attribute.

pwfxEnum

Address of a WAVEFORMATEX structure that will be used to restrict the formats listed in the dialog box. The fdwEnum member defines the members of the structure pointed to by pwfxEnum that should be used for the enumeration restrictions. If no special restrictions are desired, this member can be NULL. For other requirements associated with the pwfxEnum member, see the description for the acmFormatEnum5S26_I2 function.

hInstance

Handle of 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 ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE or ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE flag; otherwise, this member should be NULL on input.

pszTemplateName

Address of 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 MAKEINTRESOURCEXFOY9_ macro for numbered dialog box resources. This member is used only if the fdwStyle member specifies the ACMFORMATCHOOSE_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_INITDIALOGII1W.B message.

pfnHook

Address of a hook function that processes messages intended for the dialog box. An application must specify the ACMFORMATCHOOSE_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.

 

See Also

acmFormatChoose, acmFormatDetails, ACMFORMATDETAILS, acmFormatEnum, acmFormatTagDetails, ACMFORMATTAGDETAILS, acmMetrics, MAKEINTRESOURCE, MM_ACM_FORMATCHOOSE, RegisterWindowMessage, WAVEFORMATEX, WM_INITDIALOG