Platform SDK: DirectX

IDirectMusic::CreatePort

IDirectMusic::CreatePort メソッドは、特定の DirectMusic ポート用のオブジェクトを作成するために使われる。

HRESULT CreatePort(
  REFCLSID rclsidPort,
  LPDMUS_PORTPARAMS pPortParams,
  LPDIRECTMUSICPORT *ppPort,
  LPUNKNOWN pUnkOuter
);

パラメータ

rclsidPort
IDirectMusicPort インターフェイスの作成先となるポートを識別する GUID への参照 (C++) またはアドレス (C)。IDirectMusic::EnumPort メソッドを使って GUID を取り出す。このパラメータが GUID_NULL の場合は、返されるポートがデフォルト ポートになる。詳細については、「デフォルト ポート」を参照すること。
pPortParams
ポートのパラメータを保持する DMUS_PORTPARAMS 構造体のアドレス。このメソッドを呼び出す前に、この構造体の dwSize メンバを初期化しなければならない。
ppPort
IDirectMusicPort インターフェイスポインタを受け取る変数のアドレス。
pUnkOuter
COM 集合体の場合は、制御オブジェクトの IUnknown インターフェイスのアドレス。集合体は現在サポートされていないため、この値は NULL に設定しなければならない。

戻り値

成功すれば S_OK を返す。指定したパラメータが利用できない場合は S_FALSE を返す。

失敗すれば次のエラー値のいずれかを返す。

DMUS_E_DSOUND_NOT_SET
E_INVALIDARG
E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

注意

ポートはデフォルトで、作成時には非アクティブになっている。これをアクティブにして、IDirectMusic::Activate または IDirectMusicPort::Activate を呼び出さなければならない。

すべてのパラメータが取得できない場合は、DMUS_PORTPARAMS 構造体を以下のように変更して、ポートの利用できるパラメータと一致させる。

エントリ内では、構造体の dwValidParams メンバによって、構造体内の有効なメンバが示される。構造体のメンバについてフラグをセットしていない場合は、ポートの作成時に、そのパラメータにデフォルト値が設定される。

値が返されると、dwValidParams 内のフラグによって、どのポート パラメータが設定されたかが示される。特定のパラメータを指定せず、デフォルト値に設定した場合、そのフラグは渡されたパラメータに追加される。

指定したパラメータをポートがサポートしていても、パラメータの値が範囲外の場合は、*pPortParams 内のパラメータ値が変更される。この場合、dwValidParams 内のフラグはセットされたままであるが、S_FALSE が返され、値が変更されたことが示される。

次のサンプル コードでは、アプリケーションがどのようにリバーブ機能を要求し、それを取得できたかどうかを判別する方法を示す(ポート プロパティのチェックおよび設定の別の方法については、「ポートのプロパティ セット」を参照すること)。

DMUS_PORTPARAMS params; 
 
ZeroMemory(&params, sizeof(params)); 
params.dwSize = sizeof(params); 
params.dwValidParams = DMUS_PORTPARAMS_EFFECTS; 
params.dwEffectFlags = DMUS_EFFECT_REVERB;
HRESULT hr = pDirectMusic->CreatePort(guidPort, &params, 
&port, NULL); 
if (SUCCEEDED(hr))
{ 
fGotReverb = TRUE;
if (hr == S_FALSE) 
    { 
if (!(params.dwValidParams & DMUS_PORTPARAMS_EFFECTS)) 
        { 
// デバイスはどのエフェクトもサポートしない。
fGotReverb = FALSE; 
        } 
else if (!(params.dwEffectFlags & DMUS_EFFECT_REVERB)) 
        { 
// デバイスはエフェクトを認識するが、
// リバーブを割り当てることはできない。
fGotReverb = FALSE;
        } 
    } 
}

動作環境

  Windows NT/2000 : Windows 2000 が必要。
  Windows 95/98 : Windows 95 以降が必要。Windows 95 用に再配布可能な形で使用可能。
  ヘッダー : dmusicc.h で宣言。