IMarshal::MarshalInterface 메서드(objidlbase.h)

아티클
08/25/2023

인터페이스 포인터를 마샬링합니다.

구문

HRESULT MarshalInterface(
  [in] IStream *pStm,
  [in] REFIID  riid,
  [in] void    *pv,
  [in] DWORD   dwDestContext,
  [in] void    *pvDestContext,
  [in] DWORD   mshlflags
);

매개 변수

[in] pStm

마샬링하는 동안 사용할 스트림에 대한 포인터입니다.

[in] riid

마샬링할 인터페이스의 식별자에 대한 참조입니다. 이 인터페이스는 IUnknown 인터페이스에서 파생되어야 합니다.

[in] pv

마샬링할 인터페이스 포인터에 대한 포인터입니다. 호출자에게 원하는 인터페이스에 대한 포인터가 없는 경우 이 매개 변수는 NULL 일 수 있습니다.

[in] dwDestContext

지정된 인터페이스를 숨기지 않을 대상 컨텍스트입니다. dwDestContext에 대한 가능한 값은 열거형 MSHCTX에서 가져옵니다. 현재 현재 프로세스의 다른 아파트(MSHCTX_INPROC)에서 또는 현재 프로세스(MSHCTX_LOCAL)와 동일한 컴퓨터의 다른 프로세스에서 구분 해제가 발생할 수 있습니다.

[in] pvDestContext

이 매개 변수는 예약되어 있으며 0이어야 합니다.

[in] mshlflags

마샬링할 데이터를 클라이언트 프로세스(일반적인 경우)로 다시 전송할지 아니면 여러 클라이언트에서 검색할 수 있는 전역 테이블에 쓸지 여부를 나타냅니다. 가능한 값은 MSHLFLAGS 열거형에서 가져옵니다.

반환 값

이 메서드는 E_FAIL 표준 반환 값과 다음 값을 반환할 수 있습니다.

반환 코드	Description
S_OK	인터페이스 포인터가 성공적으로 마샬링되었습니다.
E_NOINTERFACE	지정된 인터페이스는 지원되지 않습니다.
STG_E_MEDIUMFULL	스트림이 가득 찼습니다.

설명

이 메서드는 서버 프로세스에서 개체의 인터페이스에 대한 포인터를 마샬링하는 모든 코드에 의해 CoMarshalInterface 호출에서 간접적으로 호출됩니다. 이 마샬링 코드는 일반적으로 완전히 다른 개체에 구현된 인터페이스에 대한 포인터를 마샬링할 수 있는 여러 인터페이스 중 하나에 대해 COM에서 생성한 스텁입니다. 예를 들어 IClassFactory 및 IOleItemContainer 인터페이스가 있습니다. 설명을 위해 포인터 마샬링을 담당하는 코드를 마샬링 스텁이라고 합니다.

발신자에 대한 참고 사항

일반적으로 MarshalInterface 를 직접 호출하는 대신 마샬링 스텁은 이 메서드에 대한 호출을 포함하는 CoMarshalInterface 함수를 호출해야 합니다. 스텁은 이 호출을 통해 개체를 명령하여 마샬링 데이터를 스트림에 씁니다. 그런 다음 스텁은 마샬링 데이터를 클라이언트 프로세스에 다시 전달하거나 전역 테이블에 씁니다. 이 경우 여러 클라이언트에서 숨김을 해제할 수 있습니다. CoMarshalInterface에 대한 스텁의 호출은 일반적으로 CoGetMarshalSizeMax를 호출하여 마샬링 데이터가 기록될 스트림 버퍼의 최대 크기를 가져옵니다.

기존 COM 인터페이스를 구현하거나 MIDL(Microsoft Interface Definition Language)을 사용하여 사용자 고유의 인터페이스를 정의하는 경우 이 메서드를 명시적으로 호출하지 않습니다. 두 경우 모두 MIDL에서 생성된 스텁이 자동으로 호출됩니다.

MIDL을 사용하여 고유한 인터페이스를 정의하지 않는 경우 마샬링 스텁은 직접 또는 간접적으로 이 메서드를 호출해야 합니다. 스텁 구현은 IMarshal::GetMarshalSizeMax에 대한 이전 호출이 반환된 직후 MarshalInterface를 호출해야 합니다. GetMarshalSizeMax에서 반환된 값은 마샬링되는 개체의 내부 상태가 변경되지 않는 한 유효하도록 보장되므로 MarshalInterface 호출 지연으로 인해 개체에 원래 표시된 것보다 더 큰 스트림 버퍼가 필요할 위험이 있습니다.

호출자에게 마샬링할 인터페이스에 대한 포인터가 있는 경우 효율성상 pv 매개 변수를 사용하여 해당 포인터를 전달해야 합니다. 이러한 방식으로 이러한 포인터를 사용하여 프록시에 적절한 CLSID를 결정할 수 있는 구현은 QueryInterface 자체를 호출할 필요가 없습니다. 호출자에게 마샬링할 인터페이스에 대한 포인터가 없는 경우 NULL을 전달할 수 있습니다.

구현자에 대한 참고 사항

MarshalInterface 구현은 수신 쪽에서 프록시를 초기화하는 데 필요한 모든 데이터를 스트림에 기록해야 합니다. 이러한 데이터에는 마샬링할 인터페이스에 대한 참조, 데이터를 클라이언트 프로세스에 반환할지 아니면 전역 테이블에 쓸지 여부를 지정하는 MSHLFLAGS 값, 명명된 파이프, 창에 대한 핸들 또는 RPC 채널에 대한 포인터와 같은 개체에 연결하는 데 필요한 모든 항목이 포함됩니다.

구현에서는 스트림이 모든 데이터를 저장할 수 있을 만큼 크다고 가정해서는 안 됩니다. 대신 STG_E_MEDIUMFULL 오류를 정상적으로 처리해야 합니다. 종료 직전에 구현은 기록된 데이터의 마지막 바이트 바로 뒤 스트림에 검색 포인터를 배치해야 합니다.

pv 매개 변수가 NULL 이고 구현에 인터페이스 포인터가 필요한 경우 현재 개체에서 QueryInterface 를 호출하여 가져올 수 있습니다. pv 매개 변수는 단순히 효율성을 개선하기 위해 존재합니다.

나중에 새 대상 컨텍스트가 지원될 때 MarshalInterface 구현이 계속 제대로 작동하도록 하려면 구현에서 처리하지 않는 모든 dwDestContext 값에 대해 COM 기본 구현으로 마샬링을 위임합니다. COM 기본 구현에 마샬링을 위임하려면 CoGetStandardMarshal 도우미 함수를 호출합니다.

호출자는 MSHLFLAGS 열거형을 사용하여 인터페이스 포인터를 단일 클라이언트로 다시 마샬링할지 아니면 여러 클라이언트에서 숨기지 않을 수 있는 전역 테이블에 쓸지 여부를 지정할 수 있습니다. 개체가 동일한 초기화 데이터에서 만들 수 있는 여러 프록시의 호출을 처리할 수 있는지 확인해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows 2000 Server [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	objidlbase.h(ObjIdl.h 포함)

추가 정보

CoMarshalInterface

IMarshal

Share via