IOleObject::D oVerb 메서드(oleidl.h)

아티클
03/15/2023

개체가 최종 사용자의 작업에 대한 응답으로 작업을 수행하도록 요청합니다. 가능한 작업은 IOleObject::EnumVerbs의 개체에 대해 열거됩니다.

구문

HRESULT DoVerb(
  [in] LONG           iVerb,
  [in] LPMSG          lpmsg,
  [in] IOleClientSite *pActiveSite,
  [in] LONG           lindex,
  [in] HWND           hwndParent,
  [in] LPCRECT        lprcPosRect
);

매개 변수

[in] iVerb

IOleObject::EnumVerbs에서 반환된 OLEVERB 구조체의 동사에 할당된 번호입니다.

[in] lpmsg

동사를 호출한 이벤트(예: 두 번 클릭)를 설명하는 MSG 구조체에 대한 포인터입니다. 호출자는 구조체 멤버의 값을 해석하거나 변경하지 않고 수정되지 않은 MSG 구조를 전달해야 합니다.

[in] pActiveSite

동사를 호출하는 이벤트가 발생한 개체의 활성 클라이언트 사이트의 IOleClientSite 인터페이스에 대한 포인터입니다.

[in] lindex

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

[in] hwndParent

개체가 포함된 문서 창의 핸들입니다. 이 창과 lprcPosRect 를 함께 사용하면 개체에 대한 임시 창을 열 수 있습니다. 여기서 hwndParent 는 개체의 창을 표시할 부모 창이고 lprcPosRect 는 해당 부모 내에서 개체 창을 표시하는 데 사용할 수 있는 영역을 정의합니다. 예를 들어 임시 창은 재생을 위해 열리지만 편집할 수는 없는 멀티미디어 개체에 유용합니다.

[in] lprcPosRect

hwndParent에서 개체의 경계 사각형을 정의하는 좌표(픽셀)를 포함하는 RECT 구조체에 대한 포인터입니다. 이 및 hwndParent를 함께 사용하면 멀티미디어 개체를 열어 재생하지만 편집할 수는 없습니다.

반환 값

이 메서드는 성공에 대한 S_OK 반환합니다. 가능한 다른 반환 값은 다음과 같습니다.

반환 코드	설명
OLE_E_NOT_INPLACEACTIVE	iVerb이 OLEIVERB_UIACTIVATE 또는 OLEIVERB_INPLACEACTIVATE 설정되었으며 개체가 아직 표시되지 않습니다.
OLE_E_CANT_BINDTOSOURCE	개체 처리기 또는 링크 개체는 링크 원본에 연결할 수 없습니다.
DV_E_LINDEX	잘못된 린덱스입니다.
OLEOBJ_S_CANNOT_DOVERB_NOW	동사는 유효하지만 개체의 현재 상태에서는 해당 작업을 수행할 수 없습니다.
OLEOBJ_S_INVALIDHWND	DoVerb이 성공했지만 hwndParent 가 잘못되었습니다.
OLEOBJ_E_NOVERBS	개체는 동사를 지원하지 않습니다.
OLEOBJ_S_INVALIDVERB	링크 원본은 이 컴퓨터의 드라이브에 연결되지 않은 네트워크를 통해 수행됩니다.
MK_E_CONNECT	링크 원본은 이 컴퓨터의 드라이브에 연결되지 않은 네트워크를 통해 수행됩니다.
OLE_E_CLASSDIFF	링크 원본에 대한 클래스가 변환되었습니다.
E_NOTIMPL	개체는 현재 위치 활성화를 지원하지 않거나 음의 동사 번호를 인식하지 않습니다.

설명

"동사"는 OLE 개체가 컨테이너의 메시지에 대한 응답으로 수행하는 작업입니다. 개체의 컨테이너 또는 개체에 연결된 클라이언트는 일반적으로 개체를 두 번 클릭하는 등 일부 최종 사용자 작업에 대한 응답으로 IOleObject::D oVerb 을 호출합니다. 지정된 개체에 사용할 수 있는 다양한 작업은 IOleObject::EnumVerbs를 호출하여 컨테이너가 가져오는 OLEVERB 구조체에 열거됩니다. IOleObject::D oVerb 은 iVerb 값을 구조체의 iVerb 멤버와 일치하여 호출할 동사를 결정합니다.

IOleObject::EnumVerbs를 통해 컨테이너가 아닌 개체가 지원하는 동사(즉, 작업)를 결정합니다. OLE 2는 모든 개체에 사용할 수 있지만 반드시 유용하지는 않은 7개의 동사를 정의합니다. 또한 각 개체는 고유한 추가 동사를 정의할 수 있습니다. 다음 표에서는 OLE로 정의된 동사에 대해 설명합니다.

동사	Description
OLEIVERB_PRIMARY(0L)	최종 사용자가 컨테이너에서 개체를 두 번 클릭할 때 발생하는 작업을 지정합니다. 컨테이너가 아닌 개체가 이 작업을 결정합니다. 개체가 현재 위치 활성화를 지원하는 경우 주 동사는 일반적으로 개체를 활성화합니다.
OLEIVERB_SHOW(-1)	개체를 편집하거나 보기 위해 표시하도록 지시합니다. 초기 편집을 위해 새로 삽입된 개체를 표시하고 링크 원본을 표시하기 위해 호출됩니다. 일반적으로 다른 개체 정의 동사에 대한 별칭입니다.
OLEIVERB_OPEN(-2)	현재 위치 활성화를 지원하는 개체를 포함하여 개체가 컨테이너의 창과 별도로 편집할 수 있도록 자체적으로 열도록 지시합니다. 개체가 현재 위치 활성화를 지원하지 않는 경우 이 동사는 OLEIVERB_SHOW 의미 체계와 동일합니다.
OLEIVERB_HIDE(-3)	개체가 뷰에서 사용자 인터페이스를 제거하도록 합니다. 현재 위치에서 활성화된 개체에만 적용됩니다.
OLEIVERB_UIACTIVATE(-4)	컨테이너 창의 제목 표시줄에 메뉴, 도구 모음 및 해당 이름을 비롯한 전체 사용자 인터페이스 도구 집합과 함께 개체를 활성화합니다. 개체가 현재 위치 활성화를 지원하지 않는 경우 E_NOTIMPL 반환해야 합니다.
OLEIVERB_INPLACEACTIVATE(-5)	최종 사용자가 개체의 동작이나 모양을 변경해야 하는 메뉴 및 도구 모음과 같은 도구를 표시하지 않고 개체를 활성화합니다. 이러한 개체를 한 번 클릭하면 해당 컨테이너와 해당 사용자 인터페이스 도구의 표시를 협상하게 됩니다. 컨테이너가 거부되면 개체는 활성 상태로 유지되지만 도구가 표시되지 않습니다.
OLEIVERB_DISCARDUNDOSTATE(-6)	개체를 비활성화하지 않고 유지 관리할 수 있는 실행 취소 상태를 취소하도록 개체에 지시하는 데 사용됩니다.

발신자에 대한 참고 사항

컨테이너는 새로 만든 개체를 초기화하는 과정의 일부로 IOleObject::D oVerb 을 호출합니다. 호출하기 전에 컨테이너는 먼저 IOleObject::SetClientSite 를 호출하여 개체의 표시 위치를 알리고 IOleObject::SetHostNames 를 호출하여 개체가 포함된 개체임을 알리고 편집 창을 열 준비를 위해 개체 애플리케이션의 사용자 인터페이스에 대한 적절한 변경 내용을 트리거해야 합니다.

IOleObject::D oVerb 은 OLE 서버 애플리케이션을 자동으로 실행합니다. 동사를 실행하는 동안 오류가 발생하면 개체 애플리케이션이 종료됩니다.

최종 사용자가 메뉴에서 명령을 선택하는 것 외에 다른 수단으로 동사를 호출하는 경우(예: 두 번 클릭하거나 개체를 한 번 클릭하는 경우) 개체의 컨테이너는 적절한 메시지가 포함된 Windows MSG 구조체에 대한 포인터를 전달해야 합니다. 예를 들어 최종 사용자가 개체를 두 번 클릭하여 동사를 호출하는 경우 컨테이너는 WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK 또는 WM_RBUTTONDBLCLK 포함하는 MSG 구조를 전달해야 합니다. 컨테이너가 메시지를 전달하지 않으면 lpmsg를 NULL로 설정해야 합니다. 개체는 전달된 MSG 구조체의 hwnd 멤버를 무시해야 하지만 다른 모든 MSG 멤버를 사용할 수 있습니다.

개체의 포함 컨테이너가 IOleObject::D oVerb을 호출하는 경우 IOleObject::D oVerb에 전달된 클라이언트 사이트 포인터(pClientSite)는 포함 사이트의 포인터와 동일합니다. 포함된 개체가 링크 원본인 경우 IOleObject::D oVerb 에 전달된 포인터는 연결 클라이언트의 클라이언트 사이트의 포인터입니다.

IOleObject::D OVerb이 OLE 링크에서 호출되면 OLE_E_CLASSDIFF 또는 MK_CONNECTMANUALLY 반환될 수 있습니다. 링크 개체는 링크가 수동인 동안 링크 원본에 일종의 변환이 적용될 때 이전 오류를 반환합니다. 링크 개체는 링크 원본이 현재 호출자의 컴퓨터에 연결되어 있지 않은 네트워크 드라이브에 있을 때 후자의 오류를 반환합니다. 이러한 조건에서 링크를 연결하는 유일한 방법은 먼저 IUnknown::QueryInterface를 호출하고, IOleLink를 요청하고, 바인딩 컨텍스트를 할당하고, IOleLink::BindToSource를 호출하여 링크 원본을 실행하는 것입니다.

일반적인 현재 위치 활성화를 지원하지 않는 컨테이너 애플리케이션은 여전히 hwndParent 및 lprcPosRect 매개 변수를 사용하여 멀티미디어 파일의 현재 위치 재생을 지원할 수 있습니다. 컨테이너는 유효한 hwndParent 및 lprcPosRect 매개 변수를 IOleObject::D oVerb에 전달해야 합니다.

일부 코드 샘플은 0이 아닌 -1의 lindex 값을 전달합니다. 값 -1은 작동하지만 0을 위해 피해야 합니다. lindex 매개 변수는 예약된 매개 변수이며 일관성을 위해 모든 예약된 매개 변수에 0 값을 할당하는 것이 좋습니다.

구현자에 대한 참고 사항

위의 동사 외에도 개체는 자체에 특정한 추가 동사를 OLEVERB 구조로 정의할 수 있습니다. 양수는 이러한 개체별 동사를 지정합니다. 개체는 알 수 없는 양의 동사 번호를 주 동사인 것처럼 처리하고 호출 함수에 OLEOBJ_S_INVALIDVERB 반환해야 합니다. 개체는 인식할 수 없는 음수의 동사를 무시하고 E_NOTIMPL 반환해야 합니다.

실행 중인 동사가 개체를 실행 중 상태로 두는 경우 서버 애플리케이션에서 연결을 지원하지 않더라도 ROT(실행 중인 개체 테이블)에 개체를 등록해야 합니다. 특정 시점에 개체가 포함에 대한 링크를 지원하는 컨테이너의 링크 원본으로 사용될 수 있으므로 등록이 중요합니다. ROT에 개체를 등록하면 링크 클라이언트가 개체의 컨테이너를 거치지 않고 개체에 대한 포인터를 직접 가져올 수 있습니다. 등록을 수행하려면 IOleClientSite::GetMoniker 를 호출하여 개체의 전체 모니커를 얻고 GetRunningObjectTable 함수를 호출하여 ROT에 대한 포인터를 가져옵니다. 그런 다음 IRunningObjectTable::Register를 호출합니다.

참고 개체가 실행 상태를 벗어나면 IOleObject::Close를 호출하여 ROT에 대한 개체 등록을 취소해야 합니다. 개체가 실행되는 동안 개체의 컨테이너 문서의 이름이 바뀌면 개체의 등록을 취소하고 새 이름을 사용하여 ROT에 다시 등록해야 합니다. 컨테이너는 IOleObject::SetMoniker 를 호출하거나 개체의 호출 IOleClientSite::GetMoniker에 응답하여 개체에 새 모니커를 알려야 합니다.

IOleObject::D oVerb의 결과로 창을 표시하는 경우 개체가 편집 창에서 SetForegroundWindow를 명시적으로 호출하는 것이 매우 중요합니다. 이렇게 하면 다른 프로세스가 원래 개체를 가리더라도 개체의 창이 사용자에게 표시됩니다. 자세한 내용은 SetForegroundWindow 및 SetActiveWindow를 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000 Professional[데스크톱 앱만]
지원되는 최소 서버	Windows 2000 Server[데스크톱 앱만]
대상 플랫폼	Windows
헤더	oleidl.h