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

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

Синтаксис

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

Члены

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)	Дождитесь завершения операции выполнения перед возвратом. Этот флаг должен использоваться вызывающими пользователями, которые используют формы ShellExecute, которые могут привести к асинхронной активации, например DDE, и создать процесс, который может выполняться в фоновом потоке. (Примечание. ShellExecuteEx выполняется в фоновом потоке по умолчанию, если модель потоков вызывающей стороны не является Apartment.) Вызовы ShellExecuteEx из процессов, уже запущенных в фоновых потоках, всегда должны передавать этот флаг. Кроме того, приложения, завершающие работу сразу после вызова ShellExecuteEx, должны указывать этот флаг. Если операция выполнения выполняется в фоновом потоке, а вызывающий объект не указал флаг 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. Этот объект будет использоваться в качестве указателя сайта. Указатель сайта используется для предоставления служб для функции ShellExecute , процесса привязки обработчика и вызываемых обработчиков глаголов. Можно предоставить ICreatingProcess , чтобы разрешить вызывающему объекту изменять некоторые параметры создаваемого процесса. Этот флаг поддерживается в Windows 8 и более поздних версиях. Если этот параметр указан, вызов выполняется синхронно в вызывающем потоке.

hwnd

Тип: HWND

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

lpVerb

Тип: LPCTSTR

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

Обычно используются следующие команды:

• 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 может быть завершена в фоновом режиме.

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

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

В этом случае приложение получает три параметра: An, example:, и "текст в кавычках".

Примечание

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

Требования

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