Estrutura ACMFORMATCHOOSE (msacm.h)

Artigo
03/15/2023

A estrutura ACMFORMATCHOOSE contém informações que o ACM usa para inicializar a caixa de diálogo de seleção de formato de áudio de forma de onda definida pelo sistema. Depois que o usuário fecha a caixa de diálogo, o sistema retorna informações sobre a seleção do usuário nessa estrutura.

Sintaxe

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;

Membros

cbStruct

Tamanho, em bytes, da estrutura ACMFORMATCHOOSE . Esse membro deve ser inicializado antes que um aplicativo chame a função acmFormatChoose . O tamanho especificado neste membro deve ser grande o suficiente para conter a estrutura ACMFORMATCHOOSE base.

fdwStyle

Sinalizadores de estilo opcionais para a função acmFormatChoose . Esse membro deve ser inicializado para uma combinação válida dos seguintes sinalizadores antes que um aplicativo chame a função acmFormatChoose :

Nome	Descrição
ACMFORMATCHOOSE_STYLEF_CONTEXTHELP	A ajuda contextual estará disponível na caixa de diálogo. Para usar esse recurso, um aplicativo deve registrar as constantes ACMHELPMSGCONTEXTMENU e ACMHELPMSGCONTEXTHELP, usando a função RegisterWindowMessage . Quando o usuário invocar ajuda, a mensagem registrada será postada na janela proprietária. A mensagem conterá os parâmetros wParam e lParam da mensagem de WM_CONTEXTMENU ou WM_CONTEXTHELP original.
ACMFORMATCHOOSE_STYLEF_ENABLEHOOK	Habilita a função de gancho apontada pelo membro pfnHook . Um aplicativo pode usar funções de gancho para uma variedade de personalizações, incluindo a resposta à mensagem de MM_ACM_FORMATCHOOSE .
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE	Faz com que o ACM crie o modelo de caixa de diálogo identificado por hInstance e pszTemplateName.
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE	O membro hInstance identifica um bloco de dados que contém um modelo de caixa de diálogo pré-carregado. Se esse sinalizador for especificado, o ACM ignorará o membro pszTemplateName .
ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT	O buffer apontado por pwfx contém uma estrutura WAVEFORMATEX válida que a caixa de diálogo usará como a seleção inicial.
ACMFORMATCHOOSE_STYLEF_SHOWHELP	Um botão de ajuda será exibido na caixa de diálogo. Para usar um arquivo de Ajuda personalizado, um aplicativo deve registrar a constante ACMHELPMSGSTRING com a função RegisterWindowMessage . Quando o usuário pressionar o botão de ajuda, a mensagem registrada será postada no proprietário.

hwndOwner

Identificador da janela à qual a caixa de diálogo pertence. Esse membro pode ser qualquer identificador de janela válido ou NULL se a caixa de diálogo não tiver proprietário. Esse membro deve ser inicializado antes de chamar a função acmFormatChoose .

pwfx

Ponteiro para uma estrutura WAVEFORMATEX . Se o sinalizador ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT for especificado no membro fdwStyle , essa estrutura deverá ser inicializada para um formato válido. Quando a função acmFormatChoose retorna, esse buffer contém o formato selecionado. Se o usuário cancelar a caixa de diálogo, nenhuma alteração será feita nesse buffer.

cbwfx

Tamanho, em bytes, do buffer apontado por pwfx. Se o buffer for muito pequeno para conter as informações de formato, a função acmFormatChoose retornará ACMERR_NOTPOSSIBLE. Além disso, o ACM copia o tamanho necessário para esse membro. Um aplicativo pode usar as funções acmMetrics e acmFormatTagDetails para determinar o maior tamanho necessário para esse buffer.

pszTitle

Ponteiro para uma cadeia de caracteres a ser colocada na barra de título da caixa de diálogo. Se esse membro for NULL, o ACM usará o título padrão (ou seja, "Seleção de Som").

szFormatTag[ACMFORMATTAGDETAILS_FORMATTAG_CHARS]

Buffer que contém uma cadeia de caracteres terminada em nulo que descreve a marca de formato da seleção de formato quando a estrutura ACMFORMATTAGDETAILS retornada pela função acmFormatTagDetails . Se o usuário cancelar a caixa de diálogo, esse membro conterá uma cadeia de caracteres terminada em nulo.

szFormat[ACMFORMATDETAILS_FORMAT_CHARS]

Buffer que contém uma cadeia de caracteres terminada em nulo que descreve os atributos de formato da seleção de formato quando a estrutura ACMFORMATDETAILS retornada pela função acmFormatDetails . Se o usuário cancelar a caixa de diálogo, esse membro conterá uma cadeia de caracteres terminada em nulo.

pszName

Ponteiro para uma cadeia de caracteres para um nome de formato definido pelo usuário. Se essa for uma cadeia de caracteres não terminada em nulo, o ACM tentará corresponder o nome com um nome de formato definido pelo usuário salvo anteriormente. Se uma correspondência for encontrada, a caixa de diálogo será inicializada para esse formato. Se uma correspondência não for encontrada ou esse membro for uma cadeia de caracteres terminada em nulo, esse membro será ignorado na entrada. Quando a função acmFormatChoose retorna, esse buffer contém uma cadeia de caracteres terminada em nulo que descreve o formato definido pelo usuário. Se o nome do formato não for definido (ou seja, o usuário não deu um nome para o formato), esse membro será uma cadeia de caracteres terminada em nulo no retorno. Se o usuário cancelar a caixa de diálogo, nenhuma alteração será feita nesse buffer.

cchName

Tamanho, em caracteres, do buffer identificado pelo membro pszName . Esse buffer deve ter pelo menos 128 caracteres. Se o membro pszName for NULL, esse membro será ignorado.

fdwEnum

Sinalizadores opcionais para restringir o tipo de formatos listados na caixa de diálogo. Esses sinalizadores são idênticos aos sinalizadores fdwEnum para a função acmFormatEnum . Se pwfxEnum for NULL, esse membro deverá ser zero. Os seguintes valores são definidos:

Nome	Descrição
ACM_FORMATENUMF_CONVERT	A estrutura WAVEFORMATEX apontada pelo membro pwfxEnum é válida. O enumerador enumerará apenas os formatos de destino que podem ser convertidos do formato pwfxEnum fornecido.
ACM_FORMATENUMF_HARDWARE	O enumerador deve enumerar somente os formatos com suporte no hardware por um ou mais dos dispositivos de áudio waveform instalados. Esse sinalizador fornece uma maneira de um aplicativo escolher apenas formatos nativos para um dispositivo de áudio waveform instalado.
ACM_FORMATENUMF_INPUT	O enumerador deve enumerar somente formatos com suporte para entrada (gravação).
ACM_FORMATENUMF_NCHANNELS	O membro nChannels da estrutura WAVEFORMATEX apontada pelo membro pwfxEnum é válido. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo.
ACM_FORMATENUMF_NSAMPLESPERSEC	O membro nSamplesPerSec da estrutura WAVEFORMATEX apontada pelo membro pwfxEnum é válido. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo.
ACM_FORMATENUMF_OUTPUT	O enumerador deve enumerar somente formatos com suporte para saída (reprodução).
ACM_FORMATENUMF_SUGGEST	A estrutura WAVEFORMATEX apontada pelo membro pwfxEnum é válida. O enumerador enumerará todos os formatos de destino sugeridos para o formato pwfxEnum fornecido.
ACM_FORMATENUMF_WBITSPERSAMPLE	O membro wBitsPerSample da estrutura WAVEFORMATEX apontada pelo membro pwfxEnum é válido. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo.
ACM_FORMATENUMF_WFORMATTAG	O membro wFormatTag da estrutura WAVEFORMATEX apontada pelo membro pwfxEnum é válido. O enumerador enumerará apenas um formato que esteja em conformidade com esse atributo.

pwfxEnum

Ponteiro para uma estrutura WAVEFORMATEX que será usada para restringir os formatos listados na caixa de diálogo. O membro fdwEnum define os membros da estrutura apontada por pwfxEnum que devem ser usados para as restrições de enumeração. Se nenhuma restrição especial for desejada, esse membro poderá ser NULL. Para outros requisitos associados ao membro pwfxEnum , consulte a descrição da função acmFormatEnum .

hInstance

Manipule para um bloco de dados que contém um modelo de caixa de diálogo especificado pelo membro pszTemplateName . Esse membro será usado somente se o membro fdwStyle especificar o sinalizador ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE ou ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE; caso contrário, esse membro deve ser NULL na entrada.

pszTemplateName

Ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do arquivo de recurso para o modelo de caixa de diálogo que deve ser substituído pelo modelo de caixa de diálogo no ACM. Um aplicativo pode usar a macro MAKEINTRESOURCE para recursos numerados da caixa de diálogo. Esse membro será usado somente se o membro fdwStyle especificar o sinalizador ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE; caso contrário, esse membro deve ser NULL na entrada.

lCustData

Dados definidos pelo aplicativo que o ACM passa para a função de gancho identificada pelo membro pfnHook . O sistema passa os dados no parâmetro lParam da mensagem WM_INITDIALOG .

pfnHook

Ponteiro para uma função de retorno de chamada que processa mensagens destinadas à caixa de diálogo. Um aplicativo deve especificar o sinalizador ACMFORMATCHOOSE_STYLEF_ENABLEHOOK no membro fdwStyle para habilitar o gancho; caso contrário, esse membro deve ser NULL. A função hook deve retornar FALSE para passar uma mensagem para o procedimento da caixa de diálogo padrão ou TRUE para descartar a mensagem. O tipo de função de retorno de chamada é acmFormatChooseHookProc.

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	msacm.h