CoCreateInstance 関数 (combaseapi.h)

  • [アーティクル]

指定した CLSID に関連付けられた クラスの 1 つのオブジェクトを作成し、既定で初期化します。

ローカル システムでオブジェクトを 1 つだけ作成する場合は、 CoCreateInstance を呼び出します。 リモート システムで 1 つのオブジェクトを作成するには、 CoCreateInstanceEx 関数を呼び出します。 1 つの CLSID に基づいて複数のオブジェクトを作成するには、 CoGetClassObject 関数を呼び出します。

構文

HRESULT CoCreateInstance(
  [in]  REFCLSID  rclsid,
  [in]  LPUNKNOWN pUnkOuter,
  [in]  DWORD     dwClsContext,
  [in]  REFIID    riid,
  [out] LPVOID    *ppv
);

パラメーター

[in] rclsid

オブジェクトの作成に使用されるデータとコードに関連付けられている CLSID。

[in] pUnkOuter

NULL の場合、 は、オブジェクトが集計の一部として作成されていないことを示します。 NULL 以外の場合は、集計オブジェクトの IUnknown インターフェイス (制御する IUnknown) へのポインター。

[in] dwClsContext

新しく作成されたオブジェクトを管理するコードが実行されるコンテキスト。 値は、列挙 CLSCTX から取得されます。

[in] riid

オブジェクトとの通信に使用するインターフェイスの識別子への参照。

[out] ppv

riid で要求されたインターフェイス ポインターを受け取るポインター変数のアドレス。 正常に戻ると、*ppv には要求されたインターフェイス ポインターが含まれます。 失敗した場合、*ppv には NULL が含まれます。

戻り値

この関数は、次の値を返すことができます。

リターン コード 説明
S_OK
 指定したオブジェクト クラスのインスタンスが正常に作成されました。
REGDB_E_CLASSNOTREG
 指定したクラスが登録データベースに登録されていません。 また、 CLSCTX 列挙で要求したサーバーの種類が登録されていないか、レジストリ内のサーバーの種類の値が破損していることを示すことができます。
CLASS_E_NOAGGREGATION
 このクラスを集計の一部として作成することはできません。
E_NOINTERFACE
 指定したクラスは、要求されたインターフェイスを実装しないか、制御する IUnknown が要求されたインターフェイスを公開しません。
E_POINTER
 ppv パラメーターは NULL です。

注釈

CoCreateInstance 関数は、指定された CLSID に関連付けられているクラス オブジェクトに接続し、既定で初期化されたインスタンスを作成し、クラス オブジェクトを解放することで、便利なショートカットを提供します。 そのため、次の機能がカプセル化されます。

CoGetClassObject(rclsid, dwClsContext, NULL, IID_IClassFactory, &pCF); 
hresult = pCF->CreateInstance(pUnkOuter, riid, ppvObj);
pCF->Release();

ローカル コンピューター上にオブジェクトのインスタンスを 1 つだけ作成する必要がある場合は、 CoCreateInstance を使用すると便利です。 リモート コンピューターでインスタンスを作成する場合は、 CoCreateInstanceEx を呼び出します。 複数のインスタンスを作成する場合は、クラス オブジェクトの IClassFactory インターフェイスへのポインターを取得し、必要に応じてそのメソッドを使用する方が効率的です。 後者の場合は、 CoGetClassObject 関数を使用する必要があります。

CLSCTX 列挙では、オブジェクトの管理に使用するサーバーの種類を指定できます。 定数には、CLSCTX_INPROC_SERVER、CLSCTX_INPROC_HANDLER、CLSCTX_LOCAL_SERVER、CLSCTX_REMOTE_SERVER、またはこれらの値の任意の組み合わせを指定できます。 定数CLSCTX_ALLは、4 つすべての組み合わせとして定義されます。 これらの定数の 1 つまたは組み合わせの使用の詳細については、「 CLSCTX」を参照してください。

UWP アプリケーション

UWP アプリケーションが CoCreateInstance に渡すことができる CLSID に制限はありませんが、多くのオブジェクトはセキュリティ上の理由から E_ACCESSDENIED で失敗します(特に、インプロセスで実行されない場合)。 さらに、オブジェクトを正常に作成できたとしても、UWP のセキュリティ制約、アプリ モデルの違いなどによって、後で失敗する可能性があります。特に、バックグラウンド タスクでは、接続されたスタンバイによるハングやその他の複雑さを回避するために、通信するオブジェクトを制限する必要があります。

例

// Create WIC factory
hr = CoCreateInstance(
    CLSID_WICImagingFactory,
    NULL,
    CLSCTX_INPROC_SERVER,
    IID_PPV_ARGS(&m_pIWICFactory)
    );

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー combaseapi.h (Objbase.h を含む)
Library Ole32.lib
[DLL] Ole32.dll

こちらもご覧ください

CoCreateInstanceEx

CoGetClassObject

IClassFactory::CreateInstance

インスタンス作成ヘルパー関数