acmFormatSuggest

関数

指定したソース形式に適した変換先の波形フォーマットを提案する。

DLLMSACM32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// MSACM32.dll
#include <windows.h>

DWORD acmFormatSuggest(
    HACMDRIVER had,
    WAVEFORMATEX* pwfxSrc,
    WAVEFORMATEX* pwfxDst,
    DWORD cbwfxDst,
    DWORD fdwSuggest
);

パラメーター

名前

型

方向

説明

had

HACMDRIVER

提案する変換先形式を問い合わせる、オープン済みのドライバーインスタンスのハンドル。このパラメーターが NULL の場合、ACM は変換先形式を提案するのに最適なドライバーを検索しようとします。

pwfxSrc

WAVEFORMATEX*

inout

ACM または指定したドライバーが変換先形式を提案する際の、ソース形式を識別する WAVEFORMATEX 構造体へのポインター。

pwfxDst

WAVEFORMATEX*

inout

pwfxSrc 形式に対して提案された変換先形式を受け取る WAVEFORMATEX 構造体へのポインター。fdwSuggest パラメーターによっては、pwfxDst が指す構造体の一部のメンバーをあらかじめ初期化しておく必要があります。

cbwfxDst

DWORD

変換先形式に使用できるサイズ(バイト単位)。指定したドライバー(またはインストールされているすべての ACM ドライバー)で利用可能な任意の形式に必要な最大サイズは、acmMetrics 関数および acmFormatTagDetails 関数を使用して判定できます。

fdwSuggest

DWORD

目的の変換先形式を一致させるためのフラグ。次の値が定義されています。

値	意味
ACM_FORMATSUGGESTF_NCHANNELS	pwfxDst が指す構造体の nChannels メンバーが有効です。ACM は、nChannels に一致する変換先形式を提案できる適切なインストール済みドライバーを問い合わせます。一致しない場合は失敗します。
ACM_FORMATSUGGESTF_NSAMPLESPERSEC	pwfxDst が指す構造体の nSamplesPerSec メンバーが有効です。ACM は、nSamplesPerSec に一致する変換先形式を提案できる適切なインストール済みドライバーを問い合わせます。一致しない場合は失敗します。
ACM_FORMATSUGGESTF_WBITSPERSAMPLE	pwfxDst が指す構造体の wBitsPerSample メンバーが有効です。ACM は、wBitsPerSample に一致する変換先形式を提案できる適切なインストール済みドライバーを問い合わせます。一致しない場合は失敗します。
ACM_FORMATSUGGESTF_WFORMATTAG	pwfxDst が指す構造体の wFormatTag メンバーが有効です。ACM は、wFormatTag に一致する変換先形式を提案できる適切なインストール済みドライバーを問い合わせます。一致しない場合は失敗します。

戻り値の型: DWORD

公式ドキュメント

acmFormatSuggest 関数は、指定したソース形式に対する変換先形式を提案するよう、ACM または指定した ACM ドライバーに問い合わせます。

戻り値

成功した場合は 0 を、それ以外の場合はエラーを返します。返される可能性のあるエラー値には次のものがあります。

戻り値	説明
MMSYSERR_INVALFLAG	少なくとも 1 つのフラグが無効です。
MMSYSERR_INVALHANDLE	指定したハンドルが無効です。
MMSYSERR_INVALPARAM	少なくとも 1 つのパラメーターが無効です。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// MSACM32.dll
#include <windows.h>

DWORD acmFormatSuggest(
    HACMDRIVER had,
    WAVEFORMATEX* pwfxSrc,
    WAVEFORMATEX* pwfxDst,
    DWORD cbwfxDst,
    DWORD fdwSuggest
);

[DllImport("MSACM32.dll", ExactSpelling = true)]
static extern uint acmFormatSuggest(
    IntPtr had,   // HACMDRIVER
    IntPtr pwfxSrc,   // WAVEFORMATEX* in/out
    IntPtr pwfxDst,   // WAVEFORMATEX* in/out
    uint cbwfxDst,   // DWORD
    uint fdwSuggest   // DWORD
);

<DllImport("MSACM32.dll", ExactSpelling:=True)>
Public Shared Function acmFormatSuggest(
    had As IntPtr,   ' HACMDRIVER
    pwfxSrc As IntPtr,   ' WAVEFORMATEX* in/out
    pwfxDst As IntPtr,   ' WAVEFORMATEX* in/out
    cbwfxDst As UInteger,   ' DWORD
    fdwSuggest As UInteger   ' DWORD
) As UInteger
End Function

' had : HACMDRIVER
' pwfxSrc : WAVEFORMATEX* in/out
' pwfxDst : WAVEFORMATEX* in/out
' cbwfxDst : DWORD
' fdwSuggest : DWORD
Declare PtrSafe Function acmFormatSuggest Lib "msacm32" ( _
    ByVal had As LongPtr, _
    ByVal pwfxSrc As LongPtr, _
    ByVal pwfxDst As LongPtr, _
    ByVal cbwfxDst As Long, _
    ByVal fdwSuggest As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

acmFormatSuggest = ctypes.windll.msacm32.acmFormatSuggest
acmFormatSuggest.restype = wintypes.DWORD
acmFormatSuggest.argtypes = [
    wintypes.HANDLE,  # had : HACMDRIVER
    ctypes.c_void_p,  # pwfxSrc : WAVEFORMATEX* in/out
    ctypes.c_void_p,  # pwfxDst : WAVEFORMATEX* in/out
    wintypes.DWORD,  # cbwfxDst : DWORD
    wintypes.DWORD,  # fdwSuggest : DWORD
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MSACM32.dll')
acmFormatSuggest = Fiddle::Function.new(
  lib['acmFormatSuggest'],
  [
    Fiddle::TYPE_VOIDP,  # had : HACMDRIVER
    Fiddle::TYPE_VOIDP,  # pwfxSrc : WAVEFORMATEX* in/out
    Fiddle::TYPE_VOIDP,  # pwfxDst : WAVEFORMATEX* in/out
    -Fiddle::TYPE_INT,  # cbwfxDst : DWORD
    -Fiddle::TYPE_INT,  # fdwSuggest : DWORD
  ],
  -Fiddle::TYPE_INT)

#[link(name = "msacm32")]
extern "system" {
    fn acmFormatSuggest(
        had: *mut core::ffi::c_void,  // HACMDRIVER
        pwfxSrc: *mut WAVEFORMATEX,  // WAVEFORMATEX* in/out
        pwfxDst: *mut WAVEFORMATEX,  // WAVEFORMATEX* in/out
        cbwfxDst: u32,  // DWORD
        fdwSuggest: u32  // DWORD
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("MSACM32.dll")]
public static extern uint acmFormatSuggest(IntPtr had, IntPtr pwfxSrc, IntPtr pwfxDst, uint cbwfxDst, uint fdwSuggest);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MSACM32_acmFormatSuggest' -Namespace Win32 -PassThru
# $api::acmFormatSuggest(had, pwfxSrc, pwfxDst, cbwfxDst, fdwSuggest)

#uselib "MSACM32.dll"
#func global acmFormatSuggest "acmFormatSuggest" sptr, sptr, sptr, sptr, sptr
; acmFormatSuggest had, varptr(pwfxSrc), varptr(pwfxDst), cbwfxDst, fdwSuggest   ; 戻り値は stat
; had : HACMDRIVER -> "sptr"
; pwfxSrc : WAVEFORMATEX* in/out -> "sptr"
; pwfxDst : WAVEFORMATEX* in/out -> "sptr"
; cbwfxDst : DWORD -> "sptr"
; fdwSuggest : DWORD -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "MSACM32.dll"
#cfunc global acmFormatSuggest "acmFormatSuggest" sptr, var, var, int, int
; res = acmFormatSuggest(had, pwfxSrc, pwfxDst, cbwfxDst, fdwSuggest)
; had : HACMDRIVER -> "sptr"
; pwfxSrc : WAVEFORMATEX* in/out -> "var"
; pwfxDst : WAVEFORMATEX* in/out -> "var"
; cbwfxDst : DWORD -> "int"
; fdwSuggest : DWORD -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "MSACM32.dll"
#cfunc global acmFormatSuggest "acmFormatSuggest" sptr, sptr, sptr, int, int
; res = acmFormatSuggest(had, varptr(pwfxSrc), varptr(pwfxDst), cbwfxDst, fdwSuggest)
; had : HACMDRIVER -> "sptr"
; pwfxSrc : WAVEFORMATEX* in/out -> "sptr"
; pwfxDst : WAVEFORMATEX* in/out -> "sptr"
; cbwfxDst : DWORD -> "int"
; fdwSuggest : DWORD -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。