ACMFORMATCHOOSE-Struktur (msacm.h)

Artikel
08/24/2023

Die ACMFORMATCHOOSE-Struktur enthält Informationen, die der ACM zum Initialisieren des systemdefinierten Dialogfelds zur Auswahl des Waveform-Audioformats verwendet. Nachdem der Benutzer das Dialogfeld geschlossen hat, gibt das System Informationen zur Auswahl des Benutzers in dieser Struktur zurück.

Syntax

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

Größe der ACMFORMATCHOOSE-Struktur in Bytes. Dieser Member muss initialisiert werden, bevor eine Anwendung die Funktion acmFormatChoose aufruft . Die in diesem Member angegebene Größe muss groß genug sein, um die ACMFORMATCHOOSE-Basisstruktur zu enthalten.

fdwStyle

Optionale Formatflags für die Funktion acmFormatChoose . Dieses Element muss mit einer gültigen Kombination der folgenden Flags initialisiert werden, bevor eine Anwendung die Funktion acmFormatChoose aufruft :

Name	BESCHREIBUNG
ACMFORMATCHOOSE_STYLEF_CONTEXTHELP	Kontextbezogene Hilfe ist im Dialogfeld verfügbar. Um dieses Feature verwenden zu können, muss eine Anwendung die Konstanten ACMHELPMSGCONTEXTMENU und ACMHELPMSGCONTEXTHELPHELP mithilfe der Funktion RegisterWindowMessage registrieren. Wenn der Benutzer Hilfe aufruft, wird die registrierte Nachricht an das Besitzerfenster gesendet. Die Nachricht enthält die Parameter wParam und lParam aus der ursprünglichen WM_CONTEXTMENU oder WM_CONTEXTHELP Nachricht.
ACMFORMATCHOOSE_STYLEF_ENABLEHOOK	Aktiviert die Hookfunktion, auf die das pfnHook-Element verweist. Eine Anwendung kann Hookfunktionen für eine Vielzahl von Anpassungen verwenden, einschließlich der Beantwortung der MM_ACM_FORMATCHOOSE Nachricht.
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE	Bewirkt, dass der ACM die von hInstance und pszTemplateName identifizierte Dialogfeldvorlage erstellt.
ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE	Das hInstance-Element identifiziert einen Datenblock, der eine vorab geladene Dialogfeldvorlage enthält. Wenn dieses Flag angegeben ist, ignoriert der ACM das Element pszTemplateName .
ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT	Der Puffer, auf den pwfx verweist, enthält eine gültige WAVEFORMATEX-Struktur , die das Dialogfeld als Anfangsauswahl verwendet.
ACMFORMATCHOOSE_STYLEF_SHOWHELP	Im Dialogfeld wird eine Hilfeschaltfläche angezeigt. Um eine benutzerdefinierte Hilfedatei zu verwenden, muss eine Anwendung die ACMHELPMSGSTRING-Konstante bei der Funktion RegisterWindowMessage registrieren. Wenn der Benutzer die Hilfeschaltfläche drückt, wird die registrierte Nachricht an den Besitzer gesendet.

hwndOwner

Handle für das Fenster, das das Dialogfeld besitzt. Dieses Element kann ein beliebiges gültiges Fensterhandle oder NULL sein, wenn das Dialogfeld keinen Besitzer hat. Dieses Element muss initialisiert werden, bevor die Funktion acmFormatChoose aufgerufen wird.

pwfx

Zeiger auf eine WAVEFORMATEX-Struktur . Wenn das ACMFORMATCHOOSE_STYLEF_INITTOWFXSTRUCT-Flag im fdwStyle-Member angegeben ist, muss diese Struktur in ein gültiges Format initialisiert werden. Wenn die acmFormatChoose-Funktion zurückgibt, enthält dieser Puffer das ausgewählte Format. Wenn der Benutzer das Dialogfeld abbricht, werden keine Änderungen an diesem Puffer vorgenommen.

cbwfx

Größe des Puffers, auf den pwfx verweist, in Bytes. Wenn der Puffer zu klein ist, um die Formatinformationen zu enthalten, gibt die acmFormatChoose-Funktion ACMERR_NOTPOSSIBLE zurück. Außerdem kopiert der ACM die erforderliche Größe in dieses Element. Eine Anwendung kann die Funktionen acmMetrics und acmFormatTagDetails verwenden, um die größte Größe zu ermitteln, die für diesen Puffer erforderlich ist.

pszTitle

Zeiger auf eine Zeichenfolge, die in der Titelleiste des Dialogfelds platziert werden soll. Wenn dieses Element NULL ist, verwendet der ACM den Standardtitel (also "Soundauswahl").

szFormatTag[ACMFORMATTAGDETAILS_FORMATTAG_CHARS]

Puffer mit einer null-beendeten Zeichenfolge, die das Formattag der Formatauswahl beschreibt, wenn die ACMFORMATTAGDETAILS-Struktur von der Funktion acmFormatTagDetails zurückgegeben wird. Wenn der Benutzer das Dialogfeld abbricht, enthält dieses Element eine NULL-Zeichenfolge.

szFormat[ACMFORMATDETAILS_FORMAT_CHARS]

Puffer mit einer NULL-Zeichenfolge, die die Formatattribute der Formatauswahl beschreibt, wenn die ACMFORMATDETAILS-Struktur von der Funktion acmFormatDetails zurückgegeben wird. Wenn der Benutzer das Dialogfeld abbricht, enthält dieses Element eine NULL-Zeichenfolge.

pszName

Zeiger auf eine Zeichenfolge für einen benutzerdefinierten Formatnamen. Wenn es sich um eine nicht mit NULL beendete Zeichenfolge handelt, versucht der ACM, den Namen mit einem zuvor gespeicherten benutzerdefinierten Formatnamen abzugleichen. Wenn eine Übereinstimmung gefunden wird, wird das Dialogfeld in diesem Format initialisiert. Wenn keine Übereinstimmung gefunden wird oder dieser Member eine null-beendete Zeichenfolge ist, wird dieses Element bei der Eingabe ignoriert. Wenn die acmFormatChoose-Funktion zurückgibt, enthält dieser Puffer eine null-beendete Zeichenfolge, die das benutzerdefinierte Format beschreibt. Wenn der Formatname unbenannt ist (d. h. der Benutzer hat keinen Namen für das Format angegeben), ist dieses Element bei der Rückgabe eine NULL-beendete Zeichenfolge. Wenn der Benutzer das Dialogfeld abbricht, werden keine Änderungen an diesem Puffer vorgenommen.

cchName

Größe des Puffers, der vom element pszName identifiziert wird, in Zeichen. Dieser Puffer sollte mindestens 128 Zeichen lang sein. Wenn das pszName-ElementNULL ist, wird dieses Element ignoriert.

fdwEnum

Optionale Flags zum Einschränken des Typs der im Dialogfeld aufgeführten Formate. Diese Flags sind mit den fdwEnum-Flags für die Funktion acmFormatEnum identisch. Wenn pwfxEnumNULL ist, sollte dieser Member 0 sein. Die folgenden Werte werden definiert:

Name	BESCHREIBUNG
ACM_FORMATENUMF_CONVERT	Die WAVEFORMATEX-Struktur , auf die das pwfxEnum-Element verweist, ist gültig. Der Enumerator listet nur Zielformate auf, die aus dem angegebenen pwfxEnum-Format konvertiert werden können.
ACM_FORMATENUMF_HARDWARE	Der Enumerator sollte nur Formate auflisten, die von mindestens einem installierten Waveform-Audio-Gerät in der Hardware unterstützt werden. Dieses Flag bietet eine Möglichkeit für eine Anwendung, nur native Formate für ein installiertes Waveform-Audiogerät auszuwählen.
ACM_FORMATENUMF_INPUT	Der Enumerator sollte nur Formate aufzählen, die für die Eingabe (Aufzeichnung) unterstützt werden.
ACM_FORMATENUMF_NCHANNELS	Das nChannels-Element der WAVEFORMATEX-Struktur , auf die vom pwfxEnum-Element verwiesen wird, ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht.
ACM_FORMATENUMF_NSAMPLESPERSEC	Das nSamplesPerSec-Element der WAVEFORMATEX-Struktur , auf das vom pwfxEnum-Element verwiesen wird, ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht.
ACM_FORMATENUMF_OUTPUT	Der Enumerator sollte nur Formate aufzählen, die für die Ausgabe (Wiedergabe) unterstützt werden.
ACM_FORMATENUMF_SUGGEST	Die WAVEFORMATEX-Struktur , auf die das pwfxEnum-Element verweist, ist gültig. Der Enumerator listet alle vorgeschlagenen Zielformate für das angegebene pwfxEnum-Format auf.
ACM_FORMATENUMF_WBITSPERSAMPLE	Das wBitsPerSample-Element der WAVEFORMATEX-Struktur , auf das vom pwfxEnum-Element verwiesen wird, ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht.
ACM_FORMATENUMF_WFORMATTAG	Das wFormatTag-Element der WAVEFORMATEX-Struktur , auf die vom pwfxEnum-Element verwiesen wird, ist gültig. Der Enumerator listet nur ein Format auf, das diesem Attribut entspricht.

pwfxEnum

Zeiger auf eine WAVEFORMATEX-Struktur , die verwendet wird, um die im Dialogfeld aufgeführten Formate einzuschränken. Das fdwEnum-Member definiert die Member der Struktur, auf die von pwfxEnum verwiesen wird, die für die Enumerationseinschränkungen verwendet werden sollen. Wenn keine besonderen Einschränkungen gewünscht sind, kann dieser Member NULL sein. Weitere Anforderungen, die dem pwfxEnum-Member zugeordnet sind, finden Sie in der Beschreibung der Funktion acmFormatEnum .

hInstance

Behandeln Sie einen Datenblock, der eine Dialogfeldvorlage enthält, die vom Element pszTemplateName angegeben wird. Dieses Element wird nur verwendet, wenn das fdwStyle-Element das ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE- oder ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATEHANDLE-Flag angibt. Andernfalls sollte dieser Member bei der Eingabe NULL sein.

pszTemplateName

Zeiger auf eine NULL-Zeichenfolge, die den Namen der Ressourcendatei für die Dialogfeldvorlage angibt, die durch die Dialogfeldvorlage im ACM ersetzt werden soll. Eine Anwendung kann das MAKEINTRESOURCE-Makro für nummerierte Dialogfeldressourcen verwenden. Dieses Element wird nur verwendet, wenn das fdwStyle-Element das flag ACMFORMATCHOOSE_STYLEF_ENABLETEMPLATE angibt. Andernfalls sollte dieser Member bei der Eingabe NULL sein.

lCustData

Anwendungsdefinierte Daten, die der ACM an die hook-Funktion übergibt, die vom pfnHook-Member identifiziert wird. Das System übergibt die Daten im lParam-Parameter der WM_INITDIALOG Meldung.

pfnHook

Zeiger auf eine Rückruffunktion, die nachrichten verarbeitet, die für das Dialogfeld vorgesehen sind. Eine Anwendung muss das ACMFORMATCHOOSE_STYLEF_ENABLEHOOK-Flag im fdwStyle-Member angeben, um den Hook zu aktivieren. Andernfalls sollte dieser Member NULL sein. Die Hookfunktion sollte FALSE zurückgeben, um eine Nachricht an die Standarddialogfeldprozedur zu übergeben, oder TRUE , um die Nachricht zu verwerfen. Der Rückruffunktionstyp ist acmFormatChooseHookProc.

Anforderungen


Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Kopfzeile	msacm.h