Функция ShellExecuteA (shellapi.h)
Выполняет операцию с указанным файлом.
Синтаксис
HINSTANCE ShellExecuteA(
[in, optional] HWND hwnd,
[in, optional] LPCSTR lpOperation,
[in] LPCSTR lpFile,
[in, optional] LPCSTR lpParameters,
[in, optional] LPCSTR lpDirectory,
[in] INT nShowCmd
);
Параметры
[in, optional] hwnd
Тип: HWND
Дескриптор родительского окна, используемого для отображения пользовательского интерфейса или сообщений об ошибках. Это значение может иметь значение NULL , если операция не связана с окном.
[in, optional] lpOperation
Тип: LPCTSTR
Указатель на строку со значением NULL, которая в данном случае называется глаголом, указывающая выполняемое действие. Набор доступных команд зависит от конкретного файла или папки. Как правило, действия, доступные в контекстном меню объекта, являются доступными командами. Обычно используются следующие команды:
изменение;
Запускает редактор и открывает документ для редактирования. Если lpFile не является файлом документа, функция завершится ошибкой.
обзор
Просматривает папку, указанную lpFile.
поиск
Инициирует поиск, начинающийся в каталоге, указанном lpDirectory.
open
Открывает элемент, заданный параметром lpFile . Элемент может быть файлом или папкой.
Печатает файл, указанный lpFile. Если lpFile не является файлом документа, функция завершается ошибкой.
запуск от имени
Запускает приложение от имени администратора. Контроль учетных записей (UAC) запрашивает у пользователя согласие на запуск приложения с повышенными привилегиями или ввод учетных данных учетной записи администратора, используемой для запуска приложения.
NULL
Используется команда по умолчанию, если она доступна. В противном случае используется команда "открыть". Если ни глаголы не доступны, система использует первую команду, указанную в реестре.
[in] lpFile
Тип: LPCTSTR
Указатель на строку, завершающуюся значением NULL, которая указывает файл или объект, в котором выполняется указанная команда. Чтобы указать объект пространства имен оболочки, передайте полное имя синтаксического анализа. Обратите внимание, что не все команды поддерживаются для всех объектов. Например, не все типы документов поддерживают команду print. Если для параметра lpDirectory используется относительный путь, не используйте относительный путь для lpFile.
[in, optional] lpParameters
Тип: LPCTSTR
Если lpFile указывает исполняемый файл, этот параметр является указателем на строку, завершающуюся значением NULL, которая указывает параметры, передаваемые приложению. Формат этой строки определяется глаголом, который требуется вызвать. Если lpFile указывает файл документа, значение lpParameters должно иметь значение NULL.
[in, optional] lpDirectory
Тип: LPCTSTR
Указатель на строку, завершающуюся значением NULL, которая указывает каталог по умолчанию (рабочий) для действия. Если это значение равно NULL, используется текущий рабочий каталог. Если относительный путь указан в lpFile, не используйте относительный путь для lpDirectory.
[in] nShowCmd
Тип: INT
Флаги, указывающие способ отображения приложения при его открытии. Если lpFile указывает файл документа, флаг просто передается связанному приложению. Решение о том, как его обрабатывать, будет решать приложение. Это может быть любое из значений, которые можно указать в параметре nCmdShow для функции ShowWindow .
Возвращаемое значение
Тип: HINSTANCE
Если функция выполняется успешно, она возвращает значение больше 32. Если функция завершается сбоем, она возвращает значение ошибки, указывающее причину сбоя. Возвращаемое значение приводится как HINSTANCE для обратной совместимости с 16-разрядными приложениями Windows. Это не настоящий HINSTANCE, однако. Его можно привести только к INT_PTR и сравнить с 32 или приведенными ниже кодами ошибок.
| Код возврата | Описание |
|---|---|
|
В операционной системе не хватает памяти или ресурсов. |
|
Указанный файл не найден. |
|
Указанный путь не найден. |
|
Файл .exe недопустим (.exe не Win32 или ошибка в .exe образе). |
|
Операционная система запретила доступ к указанному файлу. |
|
Сопоставление имени файла является неполным или недопустимым. |
|
Не удалось завершить транзакцию DDE, так как обрабатывались другие транзакции DDE. |
|
Сбой транзакции DDE. |
|
Не удалось завершить транзакцию DDE, так как истекло время ожидания запроса. |
|
Указанная библиотека DLL не найдена. |
|
Указанный файл не найден. |
|
Нет приложения, связанного с заданным расширением имени файла. Эта ошибка также будет возвращена при попытке напечатать файл, который недоступен для печати. |
|
Недостаточно памяти для завершения операции. |
|
Указанный путь не найден. |
|
Произошло нарушение общего доступа. |
Вызовите GetLastError для получения расширенных сведений об ошибке.
Комментарии
Так как ShellExecute может делегировать выполнение расширениям оболочки (источникам данных, обработчикам контекстного меню, реализациям команд), которые активируются с помощью модели COM, com следует инициализировать перед вызовом ShellExecute . Для некоторых расширений оболочки требуется тип однопотоковых квартир (STA) COM. В этом случае com следует инициализировать, как показано ниже:
CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)
Конечно, существуют экземпляры, в которых ShellExecute не использует один из этих типов расширения оболочки, и эти экземпляры не требуют инициализации COM. Тем не менее рекомендуется всегда инициализировать COM перед использованием этой функции.
Этот метод позволяет выполнять любые команды в контекстном меню папки или хранящиеся в реестре.
Чтобы открыть папку, используйте один из следующих вызовов:
ShellExecute(handle, NULL, <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);
или
ShellExecute(handle, "open", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);
Чтобы просмотреть папку, используйте следующий вызов:
ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);
Чтобы запустить служебную программу поиска оболочки для каталога, используйте следующий вызов.
ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);
Если lpOperation имеет значение NULL, функция открывает файл, указанный в lpFile. Если lpOperation имеет значение "open" или "explore", функция пытается открыть или изучить папку.
Чтобы получить сведения о приложении, которое запускается в результате вызова ShellExecute, используйте ShellExecuteEx.
Примечание
Заголовок shellapi.h определяет ShellExecute в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | shellapi.h |
| Библиотека | Shell32.lib |
| DLL | Shell32.dll (версия 3.51 или более поздняя) |
См. также раздел
Запуск приложений (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по