Структура 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 (0x00000003) | Используйте ключ класса, заданный элементом hkeyClass. Если заданы оба SEE_MASK_CLASSKEY и SEE_MASK_CLASSNAME, используется ключ класса. |
SEE_MASK_IDLIST (0x00000004) | Используйте список идентификаторов элементов, указанный элементом lpIDList. Элемент lpIDList должен указывать на структуру ITEMIDLIST. |
SEE_MASK_INVOKEIDLIST (0x0000000C) | Используйте интерфейс
Примечание. 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) | После создания нового процесса подождите, пока процесс неактивен, прежде чем вернуться, с течением минуты ожидания. Дополнительные сведения см. в |
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, указывающей имя файла или объекта, на котором
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_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 |