Функция ShellExecuteA (shellapi.h)

Статья
11/20/2024

Выполняет операцию в указанном файле.

Синтаксис

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-terminated, называемую в данном случае командой, указывающей выполняемое действие. Набор доступных команд зависит от конкретного файла или папки. Как правило, действия, доступные в контекстном меню объекта, доступные в контекстном меню, доступны. Часто используются следующие команды:

редактировать

Запускает редактор и открывает документ для редактирования. Если lpFile не является файлом документа, функция завершится ошибкой.

исследовать

Просматривает папку, указанную lpFile.

находить

Инициирует поиск, начинающийся в каталоге, указанный lpDirectory.

открытый

Открывает элемент, указанный параметром lpFile. Элемент может быть файлом или папкой.

печатать

Выводит файл, указанный lpFile. Если lpFile не является файлом документа, функция завершается ошибкой.

runas

Запускает приложение от имени администратора. Контроль учетных записей пользователей (UAC) предложит пользователю предоставить согласие на запуск приложения с повышенными привилегиями или ввести учетные данные учетной записи администратора, используемой для запуска приложения.

НЕДЕЙСТВИТЕЛЬНЫЙ

По умолчанию используется команда, если она доступна. Если нет, используется команда open. Если ни глаголы не доступны, система использует первую команду, указанную в реестре.

[in] lpFile

Тип: LPCTSTR

Указатель на строку, завершающуюnull, которая указывает файл или объект, на который необходимо выполнить указанную команду. Чтобы указать объект пространства имен Оболочки, передайте полное имя синтаксического анализа. Обратите внимание, что для всех объектов поддерживаются не все команды. Например, не все типы документов поддерживают команду print. Если относительный путь используется для параметра lpDirectory, не используйте относительный путь для lpFile.

[in, optional] lpParameters

Тип: LPCTSTR

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

[in, optional] lpDirectory

Тип: LPCTSTR

Указатель на строку null-terminated, указывающую каталог по умолчанию (рабочий) для действия. Если это значение равно 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 (не win32 .exe или ошибка в образе .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. Для некоторых расширений оболочки требуется тип однопоточной квартиры COM (STA). В этом случае 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);

Если lpOperationNULL, функция открывает файл, указанный lpFile. Если lpOperation является "открытым" или "изучением", функция пытается открыть или исследовать папку.

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	shellapi.h
библиотеки	Shell32.lib
DLL	Shell32.dll (версия 3.51 или более поздняя)