IDesktopGadget::RunGadget 메서드(shobjidl.h)

아티클
08/26/2023

바탕 화면에 설치된 가젯을 추가합니다.

구문

HRESULT RunGadget(
  [in] LPCWSTR gadgetPath
);

매개 변수

[in] gadgetPath

형식: LPCWSTR

.gadget 폴더의 전체(절대) 경로에 대한 포인터입니다. Windows로 패키지되지 않은 가젯은 다음 두 위치 중 하나에서만 실행할 수 있습니다. 다른 위치에 가젯을 설치하면 액세스 거부 오류와 함께 이 메서드가 실패합니다.

참고 이 경로에는 환경 변수가 포함되어서는 안 됩니다. 완전히 확장된 경로를 제공해야 합니다. ExpandEnvironmentStrings를 사용하여 이 매개 변수에 필요한 양식의 경로를 확장할 수 있습니다.

(%ProgramFiles%\Windows 사이드바\공유 가젯)

모든 사용자가 사용할 수 있는 비 Microsoft 가젯 설치에 권장되는 경로입니다.

(%LOCALAPPDATA%\Microsoft\Windows 사이드바\가젯)

이 위치는 가젯의 단일 사용자 설치에 사용해야 합니다.

반환 값

형식: HRESULT

성공하면 S_OK 반환하고, 그렇지 않으면 다음을 포함하여 오류 값을 반환합니다.

반환 코드	설명
SCHED_E_ALREADY_RUNNING	가젯이 이미 실행 중입니다.
E_INVALIDARG	gadgetPath가 가리키는 가젯 폴더의 경로와 관련된 오류가 발생했습니다.

설명

여기서 가젯을 "실행 중"은 가젯이 바탕 화면에 추가됨을 의미합니다.

RunGadget 은 시스템에 이미 설치된 가젯에서만 호출할 수 있습니다. 이미 실행 중인 가젯에서는 호출할 수 없습니다. 이 메서드를 통해 가젯의 instance 한 개만 언제든지 실행할 수 있습니다.

가젯 설치에는 자체 UI가 없으므로 이 메서드는 설치 프로세스의 마지막 단계 또는 가젯이 연결된 애플리케이션의 첫 번째 시작의 일부로 실행되는 경우가 많습니다. %ProgramFiles%\Windows 사이드바\공유 가젯에 가젯을 설치하려면 관리 권한이 필요합니다. 따라서 가젯 설치는 MSI(Microsoft Installer) 설치의 일부로 수행하는 것이 좋습니다.

중요 애플리케이션은 먼저 사용자에게 권한을 요청하지 않고 RunGadget 을 호출하면 안 됩니다. 사용자에게 검사 상자로 선택되는 경우 해당 검사 상자는 기본적으로 선택 취소되어야 합니다.

가젯은 시스템에 의해 결정되는 위치에 바탕 화면에 추가됩니다. 호출자는 위치를 지정할 수 없습니다.

사용자별 애플리케이션은 사용자당 가젯을 설치해야 합니다. 컴퓨터별 애플리케이션은 머신당 가젯을 설치해야 합니다. 이렇게 하면 사용자에게 통합된 환경이 보장됩니다.

예제

다음 예제에서는 사용 중인 IDesktopGadget::RunGadget을 보여줍니다.

HRESULT RunMyGadget(PCWSTR pszGadgetPath)
{
    IDesktopGadget *pDG;

    HRESULT hr = CoCreateInstance(CLSID_DesktopGadget, 
                                  NULL, 
                                  CLSCTX_INPROC_SERVER, 
                                  IID_PPV_ARGS(&pDG));
    if (SUCCEEDED(hr))
    {
        hr = pDG->RunGadget(pszGadgetPath);
        pDG->Release();
    }

    return hr;
}

요구 사항


지원되는 최소 클라이언트	Windows 7 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2008 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	shobjidl.h

Share via