CoCreateInstance 함수(combaseapi.h)

아티클
08/22/2023

지정된 CLSID와 연결된 클래스의 단일 개체를 만들고 기본값으로 초기화합니다.

로컬 시스템에서 하나의 개체만 만들려면 CoCreateInstance 를 호출합니다. 원격 시스템에서 단일 개체를 만들려면 CoCreateInstanceEx 함수를 호출합니다. 단일 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이 포함됩니다.

반환 값

이 함수는 다음 값을 반환할 수 있습니다.

반환 코드	Description
S_OK	지정된 개체 클래스의 instance 성공적으로 만들어졌습니다.
REGDB_E_CLASSNOTREG	지정된 클래스가 등록 데이터베이스에 등록되지 않았습니다. CLSCTX 열거형에서 요청한 서버 유형이 등록되지 않았거나 레지스트리의 서버 형식 값이 손상되었음을 나타낼 수도 있습니다.
CLASS_E_NOAGGREGATION	이 클래스는 집계의 일부로 만들 수 없습니다.
E_NOINTERFACE	지정된 클래스가 요청된 인터페이스를 구현하지 않거나 제어하는 IUnknown 이 요청된 인터페이스를 노출하지 않습니다.
E_POINTER	ppv 매개 변수는 NULL입니다.

설명

CoCreateInstance 함수는 지정된 CLSID와 연결된 클래스 개체에 연결하고, 기본 초기화된 instance 만들고, 클래스 개체를 해제하여 편리한 바로 가기를 제공합니다. 따라서 다음 기능을 캡슐화합니다.

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

로컬 컴퓨터에서 개체의 단일 instance 만들어야 하는 경우 CoCreateInstance를 사용하는 것이 편리합니다. 원격 컴퓨터에서 instance 만드는 경우 CoCreateInstanceEx를 호출합니다. 여러 인스턴스를 만들 때 클래스 개체의 IClassFactory 인터페이스에 대한 포인터를 가져오고 필요에 따라 해당 메서드를 사용하는 것이 더 효율적입니다. 후자의 경우 CoGetClassObject 함수를 사용해야 합니다.

CLSCTX 열거형에서 개체를 관리하는 데 사용되는 서버 유형을 지정할 수 있습니다. 상수는 CLSCTX_INPROC_SERVER, CLSCTX_INPROC_HANDLER, CLSCTX_LOCAL_SERVER, CLSCTX_REMOTE_SERVER 또는 이러한 값의 조합일 수 있습니다. 상수 CLSCTX_ALL 네 가지 모두의 조합으로 정의됩니다. 이러한 상수 중 하나 또는 조합의 사용에 대한 자세한 내용은 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 포함)
라이브러리	Ole32.lib
DLL	Ole32.dll