Структура 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 .
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.
Комментарии
Флаг 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 |
Обратная связь
https://aka.ms/ContentUserFeedback.
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделеОтправить и просмотреть отзыв по