Estructura ACMFORMATCHOOSE (msacm.h)

Artículo
03/15/2023

La estructura ACMFORMATCHOOSE contiene información que usa ACM para inicializar el cuadro de diálogo de selección de formato de onda-audio definido por el sistema. Una vez que el usuario cierra el cuadro de diálogo, el sistema devuelve información sobre la selección del usuario en esta estructura.

Sintaxis

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;

Members

cbStruct

Tamaño, en bytes, de la estructura ACMFORMATCHOOSE . Este miembro debe inicializarse antes de que una aplicación llame a la función acmFormatChoose . El tamaño especificado en este miembro debe ser lo suficientemente grande como para contener la estructura ACMFORMATCHOOSE base.

fdwStyle

Marcas de estilo opcionales para la función acmFormatChoose . Este miembro debe inicializarse en una combinación válida de las marcas siguientes antes de que una aplicación llame a la función acmFormatChoose :

Nombre	Descripción
ACMFORMATCHOOSE_STYLEF_CONTEXTHELP	La ayuda contextual estará disponible en el cuadro de diálogo. Para usar esta característica, una aplicación debe registrar las constantes ACMHELPMSGCONTEXTMENU y ACMHELPMSGCONTEXTHELP, mediante la función RegisterWindowMessage . Cuando el usuario invoca ayuda, el mensaje registrado se publicará en la ventana propietaria. El mensaje contendrá los parámetros wParam y lParam del WM_CONTEXTMENU original o WM_CONTEXTHELP mensaje.
ACMFORMATCHOOSE_STYLEF_ENABLEHOOK	Habilita la función de enlace a la que apunta el miembro pfnHook . Una aplicación puede usar funciones de enlace para diversas personalizaciones, incluida la respuesta al mensaje MM_ACM_FORMATCHOOSE .
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE	Hace que el ACM cree la plantilla del cuadro de diálogo identificada por hInstance y pszTemplateName.
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE	El miembro hInstance identifica un bloque de datos que contiene una plantilla de cuadro de diálogo precargada. Si se especifica esta marca, el ACM omite el miembro pszTemplateName .
ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT	El búfer al que apunta pwfx contiene una estructura WAVEFORMATEX válida que el cuadro de diálogo usará como selección inicial.
ACMFORMATCHOOSE_STYLEF_SHOWHELP	Aparecerá un botón de ayuda en el cuadro de diálogo. Para usar un archivo de Ayuda personalizado, una aplicación debe registrar la constante ACMHELPMSGSTRING con la función RegisterWindowMessage . Cuando el usuario presiona el botón de ayuda, el mensaje registrado se publicará en el propietario.

hwndOwner

Identificador de la ventana que posee el cuadro de diálogo. Este miembro puede ser cualquier identificador de ventana válido o NULL si el cuadro de diálogo no tiene propietario. Este miembro debe inicializarse antes de llamar a la función acmFormatChoose .

pwfx

Puntero a una estructura WAVEFORMATEX . Si se especifica la marca ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT en el miembro fdwStyle , esta estructura debe inicializarse en un formato válido. Cuando la función acmFormatChoose devuelve, este búfer contiene el formato seleccionado. Si el usuario cancela el cuadro de diálogo, no se realizarán cambios en este búfer.

cbwfx

Tamaño, en bytes, del búfer al que apunta pwfx. Si el búfer es demasiado pequeño para contener la información de formato, la función acmFormatChoose devuelve ACMERR_NOTPOSSIBLE. Además, el ACM copia el tamaño necesario en este miembro. Una aplicación puede usar las funciones acmMetrics y acmFormatTagDetails para determinar el tamaño más grande necesario para este búfer.

pszTitle

Puntero a una cadena que se va a colocar en la barra de título del cuadro de diálogo. Si este miembro es NULL, el ACM usa el título predeterminado (es decir, "Selección de sonido").

szFormatTag[ACMFORMATTAGDETAILS_FORMATTAG_CHARS]

Búfer que contiene una cadena terminada en null que describe la etiqueta de formato de la selección de formato cuando la estructura ACMFORMATTAGDETAILS devuelta por la función acmFormatTagDetails . Si el usuario cancela el cuadro de diálogo, este miembro contendrá una cadena terminada en null.

szFormat[ACMFORMATDETAILS_FORMAT_CHARS]

Búfer que contiene una cadena terminada en null que describe los atributos de formato de la selección de formato cuando la estructura ACMFORMATDETAILS devuelta por la función acmFormatDetails . Si el usuario cancela el cuadro de diálogo, este miembro contendrá una cadena terminada en null.

pszName

Puntero a una cadena para un nombre de formato definido por el usuario. Si se trata de una cadena no terminada en null, el ACM intentará hacer coincidir el nombre con un nombre de formato definido por el usuario guardado anteriormente. Si se encuentra una coincidencia, el cuadro de diálogo se inicializa con ese formato. Si no se encuentra una coincidencia o este miembro es una cadena terminada en null, este miembro se omite en la entrada. Cuando la función acmFormatChoose devuelve, este búfer contiene una cadena terminada en null que describe el formato definido por el usuario. Si el nombre del formato no tiene título (es decir, el usuario no ha dado un nombre para el formato), este miembro será una cadena terminada en null al devolver. Si el usuario cancela el cuadro de diálogo, no se realizarán cambios en este búfer.

cchName

Tamaño, en caracteres, del búfer identificado por el miembro pszName . Este búfer debe tener al menos 128 caracteres. Si el miembro pszName es NULL, este miembro se omite.

fdwEnum

Marcas opcionales para restringir el tipo de formatos enumerados en el cuadro de diálogo. Estas marcas son idénticas a las marcas fdwEnum para la función acmFormatEnum . Si pwfxEnum es NULL, este miembro debe ser cero. Se definen los valores siguientes:

Nombre	Descripción
ACM_FORMATENUMF_CONVERT	La estructura WAVEFORMATEX a la que apunta el miembro pwfxEnum es válida. El enumerador enumerará solo los formatos de destino que se pueden convertir del formato pwfxEnum especificado.
ACM_FORMATENUMF_HARDWARE	El enumerador solo debe enumerar los formatos admitidos en el hardware por uno o varios de los dispositivos de audio de forma de onda instalados. Esta marca proporciona una manera de que una aplicación elija solo los formatos nativos de un dispositivo de audio de forma de onda instalado.
ACM_FORMATENUMF_INPUT	El enumerador debe enumerar solo los formatos que se admiten para la entrada (grabación).
ACM_FORMATENUMF_NCHANNELS	El miembro nChannels de la estructura WAVEFORMATEX a la que apunta el miembro pwfxEnum es válido. El enumerador enumerará solo un formato que se ajuste a este atributo.
ACM_FORMATENUMF_NSAMPLESPERSEC	El miembro nSamplesPerSec de la estructura WAVEFORMATEX a la que apunta el miembro pwfxEnum es válido. El enumerador enumerará solo un formato que se ajuste a este atributo.
ACM_FORMATENUMF_OUTPUT	El enumerador debe enumerar solo los formatos que se admiten para la salida (reproducción).
ACM_FORMATENUMF_SUGGEST	La estructura WAVEFORMATEX a la que apunta el miembro pwfxEnum es válida. El enumerador enumerará todos los formatos de destino sugeridos para el formato pwfxEnum especificado.
ACM_FORMATENUMF_WBITSPERSAMPLE	El miembro wBitsPerSample de la estructura WAVEFORMATEX a la que apunta el miembro pwfxEnum es válido. El enumerador enumerará solo un formato que se ajuste a este atributo.
ACM_FORMATENUMF_WFORMATTAG	El miembro wFormatTag de la estructura WAVEFORMATEX a la que apunta el miembro pwfxEnum es válido. El enumerador enumerará solo un formato que se ajuste a este atributo.

pwfxEnum

Puntero a una estructura WAVEFORMATEX que se usará para restringir los formatos enumerados en el cuadro de diálogo. El miembro fdwEnum define los miembros de la estructura a los que apunta pwfxEnum que se deben usar para las restricciones de enumeración. Si no se desea ninguna restricción especial, este miembro puede ser NULL. Para conocer otros requisitos asociados al miembro pwfxEnum , consulte la descripción de la función acmFormatEnum .

hInstance

Controle a un bloque de datos que contenga una plantilla de cuadro de diálogo especificada por el miembro pszTemplateName . Este miembro solo se usa si el miembro fdwStyle especifica la marca ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE o ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE; de lo contrario, este miembro debe ser NULL en la entrada.

pszTemplateName

Puntero a una cadena terminada en null que especifica el nombre del archivo de recursos para la plantilla de cuadro de diálogo que se va a sustituir por la plantilla del cuadro de diálogo en el ACM. Una aplicación puede usar la macro MAKEINTRESOURCE para los recursos de cuadro de diálogo numerados. Este miembro solo se usa si el miembro fdwStyle especifica la marca ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE; de lo contrario, este miembro debe ser NULL en la entrada.

lCustData

Datos definidos por la aplicación que el ACM pasa a la función de enlace identificada por el miembro pfnHook . El sistema pasa los datos en el parámetro lParam del mensaje WM_INITDIALOG .

pfnHook

Puntero a una función de devolución de llamada que procesa los mensajes destinados al cuadro de diálogo. Una aplicación debe especificar la marca ACMFORMATCHOOSE_STYLEF_ENABLEHOOK en el miembro fdwStyle para habilitar el enlace; de lo contrario, este miembro debe ser NULL. La función de enlace debe devolver FALSE para pasar un mensaje al procedimiento del cuadro de diálogo estándar o TRUE para descartar el mensaje. El tipo de función de devolución de llamada es acmFormatChooseHookProc.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado	msacm.h