Структура SHELLEXECUTEINFOW (shellapi.h)

  • Статья

Содержит сведения, используемые ShellExecuteEx.

Синтаксис

typedef struct _SHELLEXECUTEINFOW {
  DWORD     cbSize;
  ULONG     fMask;
  HWND      hwnd;
  LPCWSTR   lpVerb;
  LPCWSTR   lpFile;
  LPCWSTR   lpParameters;
  LPCWSTR   lpDirectory;
  int       nShow;
  HINSTANCE hInstApp;
  void      *lpIDList;
  LPCWSTR   lpClass;
  HKEY      hkeyClass;
  DWORD     dwHotKey;
  union {
    HANDLE hIcon;
    HANDLE hMonitor;
  } DUMMYUNIONNAME;
  HANDLE    hProcess;
} SHELLEXECUTEINFOW, *LPSHELLEXECUTEINFOW;

Члены

cbSize

Тип: DWORD

Обязательный. Размер этой структуры в байтах.

fMask

Тип: ULONG

Сочетание одного или нескольких из следующих значений, которые указывают на содержимое и допустимость других элементов структуры:

SEE_MASK_DEFAULT (0x00000000) Используйте значения по умолчанию.
SEE_MASK_CLASSNAME (0x00000001) Используйте имя класса, заданное членом lpClass . Если заданы SEE_MASK_CLASSKEY и SEE_MASK_CLASSNAME, используется ключ класса.
SEE_MASK_CLASSKEY (0x00000003) Используйте ключ класса, заданный членом hkeyClass . Если заданы SEE_MASK_CLASSKEY и SEE_MASK_CLASSNAME, используется ключ класса.
SEE_MASK_IDLIST (0x00000004) Используйте список идентификаторов элементов, предоставленный участником lpIDList . Элемент lpIDList должен указывать на структуру ITEMIDLIST .
SEE_MASK_INVOKEIDLIST (0x0000000C) Используйте интерфейс IContextMenuобработчика контекстного меню выбранного элемента. Используйте lpFile , чтобы идентифицировать элемент по пути к файловой системе, или lpIDList , чтобы идентифицировать элемент по его PIDL. Этот флаг позволяет приложениям использовать ShellExecuteEx для вызова команд из расширений контекстного меню вместо статических команд, перечисленных в реестре.
Примечание: SEE_MASK_INVOKEIDLIST переопределяет и подразумевает SEE_MASK_IDLIST.
SEE_MASK_ICON (0x00000010) Используйте значок, предоставленный элементом hIcon . Этот флаг нельзя сочетать с SEE_MASK_HMONITOR.
Примечание: Этот флаг используется только в Windows XP и более ранних версиях. Он игнорируется в Windows Vista.
SEE_MASK_HOTKEY (0x00000020) Используйте сочетание клавиш, заданное элементом dwHotKey .
SEE_MASK_NOCLOSEPROCESS (0x00000040) Используйте , чтобы указать, что член hProcess получает дескриптор процесса. Этот дескриптор обычно используется, чтобы позволить приложению узнать, когда завершается процесс, созданный с помощью ShellExecuteEx . В некоторых случаях, например при выполнении с помощью диалога DDE, дескриптор не возвращается. Вызывающее приложение отвечает за закрытие дескриптора, когда он больше не нужен.
SEE_MASK_CONNECTNETDRV (0x00000080) Проверьте общую папку и подключитесь к букве диска. Это позволяет повторно подключить отключенные сетевые диски. Элемент lpFile — это UNC-путь к файлу в сети.
SEE_MASK_NOASYNC (0x00000100) Учитывается только при запуске файлов, не применяется к URI или элементам пространства имен оболочки (например, "Этот компьютер"). Дождитесь завершения асинхронной части операции выполнения (например, DDE) перед возвратом. Когда это применимо, он гарантирует, что операция запуска завершится перед возвратом. Приложения, завершающие работу сразу после вызова ShellExecuteEx , должны указывать этот флаг. Обратите внимание, что ShellExecuteEx перемещает свою работу в фоновый поток, если модель потоков вызывающего абонента не является Apartment. Принудив синхронный вызов, это поведение отключается и используется подразделение COM вызывающих объектов. Указание SEE_MASK_FLAG_HINST_IS_SITE приводит к постоянному синхронному поведению.

Если операция выполнения выполняется в фоновом потоке, а вызывающий объект не указал флаг SEE_MASK_ASYNCOK, вызывающий поток ожидает запуска нового процесса перед возвратом. Обычно это означает, что либо был вызван CreateProcess , обмен данными DDE завершен, либо что пользовательский делегат выполнения уведомил ShellExecuteEx о том, что это сделано. Если указан флаг SEE_MASK_WAITFORINPUTIDLE, shellExecuteEx вызывает WaitForInputIdle и ожидает, пока новый процесс не будет бездействующим, прежде чем вернуться, с максимальным временем ожидания в 1 минуту.

Дополнительные сведения о том, когда требуется этот флаг, см. в разделе Примечания.
SEE_MASK_FLAG_DDEWAIT (0x00000100) Как и SEE_MASK_NOASYNC, предпочтительнее использовать этот параметр.
SEE_MASK_DOENVSUBST (0x00000200) Разверните все переменные среды, указанные в строке, заданной элементом lpDirectory или lpFile .
SEE_MASK_FLAG_NO_UI (0x00000400) Не отображайте пользовательский интерфейс, включая диалоговые окна ошибок, предупреждения системы безопасности или другой пользовательский интерфейс, который обычно отображается без этого параметра.
SEE_MASK_UNICODE (0x00004000) Используйте этот флаг, чтобы указать приложение Юникода.
SEE_MASK_NO_CONSOLE (0x00008000) Используйте для наследования родительской консоли для нового процесса, а не для создания новой консоли. Это противоположное использованию флага CREATE_NEW_CONSOLE с CreateProcess.
SEE_MASK_ASYNCOK (0x00100000) Выполнение может выполняться в фоновом потоке, и вызов должен возвращаться немедленно, не дожидаясь завершения фонового потока. Обратите внимание, что в некоторых случаях ShellExecuteEx игнорирует этот флаг и ожидает завершения процесса перед возвратом.
SEE_MASK_NOQUERYCLASSSTORE (0x01000000) Не используется.
SEE_MASK_HMONITOR (0x00200000) Используйте этот флаг при указании монитора в системах с несколькими мониторами. Монитор указывается в элементе hMonitor . Этот флаг нельзя сочетать с SEE_MASK_ICON.
SEE_MASK_NOZONECHECKS (0x00800000) Не выполняйте проверка зоны. Этот флаг позволяет ShellExecuteEx обходить проверку зоны, введенную IAttachmentExecute.
SEE_MASK_WAITFORINPUTIDLE (0x02000000) После создания нового процесса дождитесь, пока процесс не станет бездействующим, прежде чем вернуться, с истечением времени ожидания в одну минуту. Дополнительные сведения см. в разделе WaitForInputIdle .
SEE_MASK_FLAG_LOG_USAGE (0x04000000) Указывает запуск, инициированный пользователем, который позволяет отслеживать часто используемые программы и другие варианты поведения.
SEE_MASK_FLAG_HINST_IS_SITE' (0x08000000) Элемент hInstApp используется для указания IUnknown объекта, реализующего IServiceProvider. Этот объект будет использоваться в качестве указателя сайта. Указатель сайта используется для предоставления служб функции ShellExecuteEx , процесса привязки обработчика и вызываемых обработчиков глаголов. Можно предоставить ICreatingProcess, чтобы разрешить вызывающей объекту изменять некоторые параметры создаваемого процесса.

Этот флаг поддерживается в Windows 8 и более поздних версиях.

Если указан этот параметр, вызов выполняется синхронно в вызывающем потоке.

hwnd

Тип: HWND

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

lpVerb

Тип: LPCTSTR

Строка, называемая глаголом, которая указывает выполняемое действие. Набор доступных команд зависит от конкретного файла или папки. Как правило, действия, доступные в контекстном меню объекта, являются доступными командами. Этот параметр может иметь значение NULL. В этом случае используется команда по умолчанию, если она доступна. В противном случае используется команда "открыть". Если ни глаголы не доступны, система использует первую команду, указанную в реестре. Обычно используются следующие команды:

  • edit: запускает редактор и открывает документ для редактирования. Если lpFile не является файлом документа, функция завершится ошибкой.
  • explore: просматривает папку, указанную в lpFile.
  • find: инициирует поиск, начиная с указанного каталога.
  • open: открывает файл, указанный параметром lpFile . Файл может быть исполняемым файлом, файлом документа или папкой.
  • print: печатает файл документа, заданный lpFile. Если lpFile не является файлом документа, функция завершится ошибкой.
  • properties: отображает свойства файла или папки.
  • runas: запускает приложение от имени администратора. Контроль учетных записей (UAC) запрашивает у пользователя согласие на запуск приложения с повышенными привилегиями или ввод учетных данных учетной записи администратора, используемой для запуска приложения.

lpFile

Тип: LPCTSTR

Адрес строки, заканчивающейся null, которая указывает имя файла или объекта, для которого ShellExecuteEx будет выполнять действие, указанное параметром lpVerb . Системные команды реестра, поддерживаемые функцией ShellExecuteEx , включают "открыть" для исполняемых файлов и файлов документов и "print" для файлов документов, для которых зарегистрирован обработчик печати. Другие приложения могли добавлять команды оболочки через системный реестр, например "воспроизвести" для .avi и .wav файлов. Чтобы указать объект пространства имен оболочки, передайте полное имя синтаксического анализа и установите флаг SEE_MASK_INVOKEIDLIST в параметре fMask .

Примечание: Если установлен флаг SEE_MASK_INVOKEIDLIST , можно использовать lpFile или lpIDList для идентификации элемента по его пути к файловой системе или piDL соответственно. Необходимо задать одно из двух значений — lpFile или lpIDList.
Примечание: Если путь не включен в имя, предполагается, что используется текущий каталог.

lpParameters

Тип: LPCTSTR

Необязательный элемент. Адрес строки, заканчивающейся null, которая содержит параметры приложения. Параметры должны быть разделены пробелами. Если элемент lpFile указывает файл документа, значение lpParameters должно иметь значение NULL.

lpDirectory

Тип: LPCTSTR

Необязательный элемент. Адрес строки, завершающейся значением NULL, которая указывает имя рабочего каталога. Если этот член имеет значение NULL, текущий каталог используется в качестве рабочего каталога.

nShow

Тип: int

Обязательный. Флаги, указывающие способ отображения приложения при его открытии; одно из SW_ значений, перечисленных для функции ShellExecute . Если lpFile указывает файл документа, флаг просто передается связанному приложению. Решение о том, как его обрабатывать, будет решать приложение.

hInstApp

Тип: HINSTANCE

[out] Если SEE_MASK_NOCLOSEPROCESS задано и вызов ShellExecuteEx успешно выполнен, он устанавливает для этого элемента значение больше 32. Если функция завершается сбоем, ей присваивается значение ошибки SE_ERR_XXX, указывающее причину сбоя. Хотя hInstApp объявлен как HINSTANCE для совместимости с 16-разрядными приложениями Windows, он не является истинным HINSTANCE. Его можно привести только к int и сравнить с 32 или следующими кодами ошибок SE_ERR_XXX.


Код ошибки Причина
SE_ERR_FNF (2) Файл не найден.
SE_ERR_PNF (3) Путь не найден.
SE_ERR_ACCESSDENIED (5) Доступ запрещен.
SE_ERR_OOM (8) Недостаточно памяти.
SE_ERR_DLLNOTFOUND (32) Библиотека динамической компоновки не найдена.
SE_ERR_SHARE (26) Не удается предоставить общий доступ к открытому файлу.
SE_ERR_ASSOCINCOMPLETE (27) Сведения о сопоставлении файлов не полны.
SE_ERR_DDETIMEOUT (28) Истекло время ожидания операции DDE.
SE_ERR_DDEFAIL (29) Операция DDE завершилась сбоем.
SE_ERR_DDEBUSY (30) Операция DDE занята.
SE_ERR_NOASSOC (31) Сопоставление файлов недоступно.

lpIDList

Тип: LPVOID

Адрес абсолютной структуры ITEMIDLIST (PCIDLIST_ABSOLUTE), содержащей список идентификаторов элементов, который однозначно идентифицирует файл для выполнения. Этот элемент игнорируется, если элемент fMask не включает SEE_MASK_IDLIST или SEE_MASK_INVOKEIDLIST.

lpClass

Тип: LPCTSTR

Адрес строки, завершающейся значением NULL, которая указывает одно из следующих значений:

  • Идентификатор ProgId. Например, "Paint.Picture".
  • Схема протокола URI. Например, "http".
  • Расширение файла. Например, ".txt".
  • Путь к реестру в HKEY_CLASSES_ROOT с именем подраздела, содержащего одну или несколько команд оболочки. Этот раздел будет содержать подраздел, соответствующий схеме реестра команд оболочки, напримеримя командыоболочки\.

Этот элемент игнорируется, если fMask не включает SEE_MASK_CLASSNAME.

hkeyClass

Тип: HKEY

Дескриптор раздела реестра для типа файла. Права доступа для этого раздела реестра должны иметь значение KEY_READ. Этот элемент игнорируется, если fMask не включает SEE_MASK_CLASSKEY.

dwHotKey

Тип: DWORD

Сочетание клавиш для связывания с приложением. Слово низкого порядка — это код виртуального ключа, а слово высокого порядка — флаг модификатора (HOTKEYF_). Список флагов модификаторов см. в описании сообщения WM_SETHOTKEY . Этот элемент игнорируется, если fMask не включает SEE_MASK_HOTKEY.

DUMMYUNIONNAME

DUMMYUNIONNAME.hIcon

Тип: HANDLE

Дескриптор значка для типа файла. Этот элемент игнорируется, если fMask не включает SEE_MASK_ICON. Это значение используется только в Windows XP и более ранних версиях. По состоянию на Windows Vista он не учитывается.

DUMMYUNIONNAME.hMonitor

Тип: HANDLE

Дескриптор монитора, на котором должен отображаться документ. Этот элемент игнорируется, если fMask не включает SEE_MASK_HMONITOR.

hProcess

Тип: HANDLE

Дескриптор для только что запущенного приложения. Этот элемент задается при возврате и всегда имеет значение NULL , если fMask не имеет значение SEE_MASK_NOCLOSEPROCESS. Даже если параметру fMask присвоено значение SEE_MASK_NOCLOSEPROCESS, hProcess будет иметь значение NULL , если процесс не был запущен. Например, если документ для запуска является URL-адресом и экземпляр интернет-Обозреватель уже запущен, документ будет отображаться. Новый процесс не запускается, а hProcess будет иметь значение NULL.

Примечание. ShellExecuteEx не всегда возвращает hProcess, даже если процесс запускается в результате вызова. Например, hProcess не возвращается при использовании SEE_MASK_INVOKEIDLIST для вызова IContextMenu.

Комментарии

Флаг SEE_MASK_NOASYNC должен быть указан, если поток, вызывающий ShellExecuteEx , не имеет цикла сообщений или если поток или процесс завершится вскоре после возврата ShellExecuteEx . В таких условиях вызывающий поток будет недоступен для завершения диалога DDE, поэтому важно, чтобы ShellExecuteEx завершил беседу, прежде чем возвращать управление вызывающему приложению. Невозможность завершить беседу может привести к неудаче запуска документа.

Если вызывающий поток имеет цикл сообщений и будет существовать в течение некоторого времени после вызова ShellExecuteEx , флаг SEE_MASK_NOASYNC является необязательным. Если флаг не указан, для завершения диалога DDE будет использоваться поток сообщений вызывающего потока. Вызывающее приложение восстанавливает контроль раньше, так как беседа DDE может быть завершена в фоновом режиме.

Для вызовов этого API, которые возникают в результате взаимодействия с пользователем, укажите SEE_MASK_FLAG_LOG_USAGE.

Чтобы включить двойные кавычки в lpParameters, заключите каждую метку в пару кавычек, как показано в следующем примере.

sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";

В этом случае приложение получает три параметра: An, example:, и "quoted text".

Примечание

Заголовок shellapi.h определяет SHELLEXECUTEINFO в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Верхняя часть shellapi.h