Microsoft DirectX 8.0 (C++)

IDirectMusic8::CreatePort

DirectMusic ポートのオブジェクトを作成する。

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

パラメータ

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

戻り値

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

失敗した場合は、次のいずれかのエラー値を返す。

DMUS_E_DSOUND_NOT_SET
E_INVALIDARG
CLASS_E_NOAGGREGATION
E_NOINTERFACE
E_OUTOFMEMORY
E_POINTER

注意

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

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

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

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

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

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

DMUS_PORTPARAMS8 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;
        } 
    } 
}

動作環境

  ヘッダー : dmusicc.h で宣言。