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


Функция 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 . Элемент может быть файлом или папкой.

print

Печатает файл, указанный 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 или приведенными ниже кодами ошибок.

Код возврата Описание
0
В операционной системе не хватает памяти или ресурсов.
ERROR_FILE_NOT_FOUND
Указанный файл не найден.
ERROR_PATH_NOT_FOUND
Указанный путь не найден.
ERROR_BAD_FORMAT
Файл .exe недопустим (.exe не Win32 или ошибка в .exe образе).
SE_ERR_ACCESSDENIED
Операционная система запретила доступ к указанному файлу.
SE_ERR_ASSOCINCOMPLETE
Сопоставление имени файла является неполным или недопустимым.
SE_ERR_DDEBUSY
Не удалось завершить транзакцию DDE, так как обрабатывались другие транзакции DDE.
SE_ERR_DDEFAIL
Сбой транзакции DDE.
SE_ERR_DDETIMEOUT
Не удалось завершить транзакцию DDE, так как истекло время ожидания запроса.
SE_ERR_DLLNOTFOUND
Указанная библиотека DLL не найдена.
SE_ERR_FNF
Указанный файл не найден.
SE_ERR_NOASSOC
Нет приложения, связанного с заданным расширением имени файла. Эта ошибка также будет возвращена при попытке напечатать файл, который недоступен для печати.
SE_ERR_OOM
Недостаточно памяти для завершения операции.
SE_ERR_PNF
Указанный путь не найден.
SE_ERR_SHARE
Произошло нарушение общего доступа.

Вызовите 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.

Примечание Окно запуска папки в отдельном процессе в разделе Параметры папки влияет на shellExecute. Если этот параметр отключен (параметр по умолчанию), ShellExecute использует открытое окно Обозреватель вместо запуска нового. Если окно Обозреватель не открыто, ShellExecute запускает новое окно.
 

Примечание

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

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header shellapi.h
Библиотека Shell32.lib
DLL Shell32.dll (версия 3.51 или более поздняя)

См. также раздел

CoInitializeEx

CreateProcessA

IShellExecuteHook

Запуск приложений (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)

ShellExecuteEx