CoGetClassObject 함수(combaseapi.h)

아티클
08/22/2023

지정된 CLSID와 연결된 클래스 개체의 인터페이스에 대한 포인터를 제공합니다. CoGetClassObject 는 필요한 경우 이 작업을 수행하는 데 필요한 실행 코드를 동적으로 로드합니다.

CoGetClassObject를 직접 호출하여 시스템 레지스트리에 CLSID가 있는 클래스 개체를 통해 여러 개체를 만듭니다. 특정 원격 컴퓨터에서 클래스 개체를 검색할 수도 있습니다. 대부분의 클래스 개체는 IClassFactory 인터페이스를 구현합니다. 그런 다음 CreateInstance 를 호출하여 초기화되지 않은 개체를 만듭니다. 그러나 이 프로세스를 항상 진행할 필요는 없습니다. 단일 개체를 만들려면 원격 머신에서 instance 만들 수 있는 CoCreateInstanceEx 함수를 호출합니다. 그러면 로컬 컴퓨터에서 instance 만드는 데 계속 사용할 수 있는 CoCreateInstance 함수가 대체됩니다. 두 함수는 모두 클래스 개체에 연결하고, instance 만들고, 클래스 개체를 해제하는 것을 캡슐화합니다. CoGetInstanceFromFile 및 CoGetInstanceFromIStorage라는 두 가지 다른 함수는 원격 시스템에서 instance 생성과 개체 활성화를 모두 제공합니다. 단일 형식의 개체를 만들고 해당 개체의 인터페이스에 대한 포인터를 제공하는 데 목적이 있는 다양한 함수 및 인터페이스 메서드가 있습니다.

구문

HRESULT CoGetClassObject(
  [in]           REFCLSID rclsid,
  [in]           DWORD    dwClsContext,
  [in, optional] LPVOID   pvReserved,
  [in]           REFIID   riid,
  [out]          LPVOID   *ppv
);

매개 변수

[in] rclsid

개체를 만드는 데 사용할 데이터 및 코드와 연결된 CLSID입니다.

[in] dwClsContext

실행 코드를 실행할 컨텍스트입니다. 원격 활성화를 사용하도록 설정하려면 CLSCTX_REMOTE_SERVER 포함합니다. 컨텍스트 값 및 해당 사용에 대한 자세한 내용은 CLSCTX 열거형을 참조하세요.

[in, optional] pvReserved

클래스 개체를 인스턴스화할 컴퓨터에 대한 포인터입니다. 이 매개 변수가 NULL이면 dwClsCtx 매개 변수의 해석에 따라 클래스 개체가 현재 컴퓨터 또는 클래스의 RemoteServerName 키 아래에 지정된 컴퓨터에서 인스턴스화됩니다. COSERVERINFO를 참조하세요.

[in] riid

성공적으로 반환될 때 ppv 로 제공되는 인터페이스의 식별자에 대한 참조입니다. 이 인터페이스는 클래스 개체와 통신하는 데 사용됩니다. 일반적으로 이 값은 IID_IClassFactory 있지만 라이선스 형식을 지원하는 IID_IClassFactory2 같은 다른 값은 허용됩니다. 모든 OLE 정의 인터페이스 IID는 OLE 헤더 파일에 IID_interfacename 정의됩니다. 여기서 interfacename은 인터페이스의 이름입니다.

[out] ppv

riid에서 요청된 인터페이스 포인터를 수신하는 포인터 변수의 주소입니다. 반환이 성공하면 *ppv 에 요청된 인터페이스 포인터가 포함됩니다.

반환 값

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

반환 코드	설명
S_OK	지정된 클래스 개체에 대한 위치 및 연결이 성공했습니다.
REGDB_E_CLASSNOTREG	CLSID가 제대로 등록되지 않았습니다. 이 오류는 dwClsContext 에 지정한 값이 레지스트리에 없음을 나타낼 수도 있습니다.
E_NOINTERFACE	ppv에서 가리키는 개체는 riid로 식별된 인터페이스를 지원하지 않거나 E_NOINTERFACE 반환된 클래스 개체에 대한 QueryInterface 작업을 지원하지 않습니다.
REGDB_E_READREGDB	등록 데이터베이스를 읽는 동안 오류가 발생했습니다.
CO_E_DLLNOTFOUND	컨텍스트에 따라 In Process DLL 또는 처리기 DLL을 찾을 수 없습니다.
CO_E_APPNOTFOUND	실행 파일(.exe)을 찾을 수 없습니다(CLSCTX_LOCAL_SERVER만 해당).
E_ACCESSDENIED	로드 시 일반적인 액세스 오류가 발생했습니다.
CO_E_ERRORINDLL	실행 파일 이미지에 오류가 있습니다.
CO_E_APPDIDNTREG	실행 파일이 시작되었지만 클래스 개체를 등록하지 않았습니다(종료되었을 수 있음).

설명

OLE의 클래스 개체는 개체 그룹에 공통된 작업을 허용하는 인터페이스를 지원하는 중간 개체입니다. 이 그룹의 개체는 단일 CLSID로 표현되는 동일한 개체 정의에서 파생된 인스턴스입니다. 일반적으로 클래스 개체에 구현된 인터페이스는 지정된 정의(클래스)의 개체 인스턴스를 만들 수 있는 IClassFactory입니다.

CoGetClassObject에 대한 호출은 클래스 개체에 대한 호출자 액세스(riid 매개 변수로 지정된 인터페이스에 대한 포인터를 통해)를 만들고 초기화하며 제공합니다. 클래스 개체는 rclsid 매개 변수에서 지정한 CLSID와 연결된 개체입니다. 시스템이 컴퓨터 내에서 연결된 코드 및 데이터를 찾는 방법에 대한 세부 정보는 아직 로드되지 않은 코드의 동적 로드와 마찬가지로 호출자에게 투명합니다.

원격 활성화가 필요함을 나타내는 클래스 컨텍스트가 CLSCTX_REMOTE_SERVER 경우 pServerInfo 매개 변수에 제공된 COSERVERINFO 구조를 사용하면 서버가 있는 컴퓨터를 지정할 수 있습니다. pServerInfo가 NULL일 때 원격 서버를 찾는 데 사용되는 알고리즘에 대한 자세한 내용은 CLSCTX 열거형을 참조하세요.

클래스에 대한 CLSID를 찾을 수 있는 위치는 두 가지입니다.

레지스트리는 CLSID와 파일 접미사 간의 연결과 개체의 클래스를 결정하기 위한 CLSID와 파일 서명 간의 연결을 보유합니다.
개체가 영구 스토리지에 저장되면 해당 CLSID는 해당 데이터와 함께 저장됩니다.

포함되거나 연결된 OLE 문서 개체를 만들고 초기화하려면 CoGetClassObject 를 직접 호출할 필요가 없습니다. 대신 OleCreate 또는 OleCreateXXX 함수를 호출합니다. 이러한 함수는 전체 개체 인스턴스화 및 초기화 프로세스를 캡슐화하고 다른 함수 중 에서 CoGetClassObject를 호출합니다.

riid 매개 변수는 클라이언트가 클래스 개체와 통신하는 데 사용할 인터페이스를 지정합니다. 대부분의 경우 이 인터페이스는 IClassFactory입니다. 이렇게 하면 호출자가 구현에 지정된 종류의 초기화되지 않은 개체를 만들 수 있는 CreateInstance 메서드에 액세스할 수 있습니다. CLSID를 사용하여 시스템에 등록된 모든 클래스는 IClassFactory를 구현해야 합니다.

그러나 드문 경우에서는 개체 집합에 공통적인 작업을 정의하는 다른 인터페이스를 지정할 수 있습니다. 예를 들어 OLE가 모니커를 구현하는 방식에서 클래스 개체의 인터페이스는 개체의 표시 이름을 모니커로 변환하는 데 사용되는 IParseDisplayName입니다.

dwClsContext 매개 변수는 실행 컨텍스트를 지정하여 하나의 CLSID를 다른 실행 컨텍스트의 다른 코드 조각과 연결할 수 있도록 합니다. CLSCTX 열거형은 사용 가능한 컨텍스트 플래그를 지정합니다. CoGetClassObject 는 CoRegisterClassObject 함수를 호출하여 현재 등록된 레지스트리 및 클래스 개체를 모두 참조합니다(표시된 컨텍스트에 적합).

클래스 개체를 해제하려면 클래스 개체의 Release 메서드를 사용합니다. CoRevokeClassObject 함수는 시스템 레지스트리에서 클래스 개체의 CLSID를 제거하는 데만 사용됩니다.

요구 사항


지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	combaseapi.h(Objbase.h 포함)
라이브러리	Ole32.lib
DLL	Ole32.dll