Структура 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 выполняется в фоновом потоке по умолчанию, если модель потоков вызова не является квартирой.) Вызовы ShellExecuteEx из процессов, уже работающих в фоновых потоках, всегда должны передавать этот флаг. Кроме того, приложения, которые выходят сразу после вызова ShellExecuteExex должны указать этот флаг. Если операция выполнения выполняется в фоновом потоке, и вызывающий объект не указал флаг SEE_MASK_ASYNCOK, вызывающий поток ожидает, пока новый процесс не начнется до возвращения. Обычно это означает, что был вызван CreateProcess, обмен данными DDE завершен или что делегат пользовательского выполнения уведомил ShellExecuteExecuteEx, что это сделано. Если указан флаг 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, в этом случае используется команда по умолчанию, если она доступна. Если нет, используется команда open. Если ни глаголы не доступны, система использует первую команду, указанную в реестре. Если нет причины ограничить действие определенной командой, передайте NULL для использования вычисляемого по умолчанию. Это необходимо в некоторых случаях, например при указании SEE_MASK_FLAG_NO_UI и намерении создать пользовательский интерфейс Open With, если приложения не установлены.

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

• изменить: запускает редактор и открывает документ для редактирования. Если lpFile не является файлом документа, функция завершится ошибкой.
• изучить: просматривает папку, указанную lpFile.
• найти: инициирует поиск, начиная с указанного каталога.
• открыть: открывает файл, указанный параметром lpFile. Файл может быть исполняемым файлом, файлом документа или папкой.
• openas: запускает пользовательский интерфейс средства выбора, позволяющий пользователю выбрать приложение, с помощью которого открыть файл, указанный параметром lpFile.
• печати: выводит файл документа, указанный lpFile. Если lpFile не является файлом документа, функция завершится ошибкой.
• свойства: отображает свойства файла или папки.
• запуска: запускает приложение от имени администратора. Контроль учетных записей пользователей (UAC) предложит пользователю предоставить согласие на запуск приложения с повышенными привилегиями или ввести учетные данные учетной записи администратора, используемой для запуска приложения.

lpFile

Тип: LPCTSTR

Адрес строки, завершаемой значением NULL, указывающей имя файла или объекта, на котором ShellExecuteExecuteEx выполнит действие, указанное параметром lpVerb. Системные команды реестра, поддерживаемые функцией shellExecuteExecuteEx, включают "open" для исполняемых файлов и файлов документов и "печать" для файлов документов, для которых был зарегистрирован обработчик печати. Другие приложения могли добавлять команды оболочки через системный реестр, например "воспроизведение" для .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, а вызов ShellExecuteExecuteEx выполнен успешно, он задает этому элементу значение больше 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, указывающей одно из следующих значений:

• A 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. Даже если задано значение SEE_MASK_NOCLOSEPROCESS, hProcess будет null, если процесс не был запущен. Например, если документ, который будет запущен, является URL-адресом и экземпляром Internet Explorer уже запущен, он отобразит документ. Новый процесс не запускается, и hProcess будет NULL.

Примечание. ShellExecuteEx не всегда возвращает hProcess, даже если процесс запускается в результате вызова. Например, hProcess не возвращается при использовании SEE_MASK_INVOKEIDLIST для вызова IContextMenu.

Замечания

Флаг SEE_MASK_NOASYNC должен быть указан, если вызывающий поток ShellExecuteEx не имеет цикла сообщений или если поток или процесс завершится вскоре после возвращения ShellExecuteExecuteEx. В таких условиях вызывающий поток не будет доступен для завершения беседы DDE, поэтому важно, чтобы ShellExecute Ex завершить беседу, прежде чем возвращать управление вызывающему приложению. Сбой завершения беседы может привести к неудачном запуску документа.

Если вызывающий поток имеет цикл сообщений и будет существовать некоторое время после вызова ShellExecute Ex возвращается, флаг SEE_MASK_NOASYNC необязателен. Если флаг опущен, для завершения беседы DDE будет использоваться насос сообщения вызывающего потока. Вызывающее приложение быстрее восстанавливает управление, так как беседа DDE может быть завершена в фоновом режиме.

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
заголовка	shellapi.h