Метод IDesktopGadget::RunGadget (shobjidl.h)

Статья
08/26/2023

Добавляет установленный гаджет на рабочий стол.

Синтаксис

HRESULT RunGadget(
  [in] LPCWSTR gadgetPath
);

Параметры

[in] gadgetPath

Тип: LPCWSTR

Указатель на полный (абсолютный) путь к папке .gadget. Гаджет, не упакованный с Windows, можно запускать только из одного из двух следующих расположений. Установка гаджета в любом другом расположении приведет к сбою этого метода с ошибкой отказа в доступе.

Примечание Этот путь не должен содержать переменные среды; Необходимо указать полностью развернутый путь. ExpandEnvironmentStrings можно использовать для расширения пути к форме, необходимой в этом параметре.

(%ProgramFiles%\Боковая панель Windows\Общие гаджеты)

Это рекомендуемый путь для установки гаджетов сторонних пользователей, доступный для всех пользователей.

(%LOCALAPPDATA%\Microsoft\Windows Sidebar\Gadgets)

Это расположение следует использовать для однопользовательской установки гаджета.

Возвращаемое значение

Тип: HRESULT

Возвращает S_OK в случае успешного выполнения, или значение ошибки в противном случае, включая следующее:

Код возврата	Описание
SCHED_E_ALREADY_RUNNING	Гаджет уже работает.
E_INVALIDARG	Произошла ошибка, связанная с путем к папке гаджета, на которую указывает gadgetPath.

RunGadget можно вызвать только на гаджете, который уже установлен в системе. Его нельзя вызвать для уже работающего гаджета. С помощью этого метода в любой момент времени можно запустить только один экземпляр гаджета.

Так как установка гаджета не имеет собственного пользовательского интерфейса, этот метод часто выполняется как последний шаг в процессе установки или как часть первого запуска приложения, с которым связан гаджет. Для установки гаджета в папке %ProgramFiles%\Windows Sidebar\Shared Gadgets требуются права администратора. Поэтому рекомендуется, чтобы установка гаджета выполнялись в рамках установки Установщика Майкрософт (MSI).

Важно Приложения не должны вызывать 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
Header	shobjidl.h

Поделиться через