Estructura SHELLEXECUTEINFOA (shellapi.h)
Contiene información utilizada por ShellExecuteEx.
Sintaxis
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;
Miembros
cbSize
Tipo: DWORD
Necesario. Tamaño de esta estructura, en bytes.
fMask
Tipo: ULONG
Combinación de uno o varios de los valores siguientes que indican el contenido y la validez de los demás miembros de la estructura:
| SEE_MASK_DEFAULT (0x00000000) | Use valores predeterminados. |
| SEE_MASK_CLASSNAME (0x00000001) | Use el nombre de clase proporcionado por el miembro lpClass . Si se establecen SEE_MASK_CLASSKEY y SEE_MASK_CLASSNAME, se usa la clave de clase . |
| SEE_MASK_CLASSKEY (0x00000003) | Use la clave de clase proporcionada por el miembro hkeyClass . Si se establecen SEE_MASK_CLASSKEY y SEE_MASK_CLASSNAME, se usa la clave de clase . |
| SEE_MASK_IDLIST (0x00000004) | Use la lista de identificadores de elemento dada por el miembro lpIDList . El miembro lpIDList debe apuntar a una estructura ITEMIDLIST . |
| SEE_MASK_INVOKEIDLIST (0x0000000C) | Use la interfaz IContextMenu del controlador de menú contextual del elemento seleccionado. Use lpFile para identificar el elemento por su ruta de acceso del sistema de archivos o lpIDList para identificar el elemento por su PIDL. Esta marca permite a las aplicaciones usar ShellExecuteEx para invocar verbos desde extensiones de menú contextual en lugar de los verbos estáticos enumerados en el registro.
Nota: SEE_MASK_INVOKEIDLIST invalida e implica SEE_MASK_IDLIST.
|
| SEE_MASK_ICON (0x00000010) | Use el icono proporcionado por el miembro hIcon . Esta marca no se puede combinar con SEE_MASK_HMONITOR.
Nota: Esta marca solo se usa en Windows XP y versiones anteriores. Se omite a partir de Windows Vista.
|
| SEE_MASK_HOTKEY (0x00000020) | Use el método abreviado de teclado proporcionado por el miembro dwHotKey . |
| SEE_MASK_NOCLOSEPROCESS (0x00000040) | Use para indicar que el miembro hProcess recibe el identificador de proceso. Este identificador se usa normalmente para permitir que una aplicación averigüe cuándo finaliza un proceso creado con ShellExecuteEx . En algunos casos, como cuando se satisface la ejecución a través de una conversación DDE, no se devolverá ningún identificador. La aplicación que realiza la llamada es responsable de cerrar el identificador cuando ya no es necesario. |
| SEE_MASK_CONNECTNETDRV (0x00000080) | Valide el recurso compartido y conéctese a una letra de unidad. Esto permite la reconexión de unidades de red desconectadas. El miembro lpFile es una ruta de acceso UNC de un archivo en una red. |
| SEE_MASK_NOASYNC (0x00000100) | Espere a que se complete la operación de ejecución antes de devolver. Los autores de llamadas que usan formularios ShellExecute que podrían dar lugar a una activación asincrónica, por ejemplo, DDE, y crear un proceso que se pueda ejecutar en un subproceso en segundo plano. (Nota: ShellExecuteEx se ejecuta en un subproceso en segundo plano de forma predeterminada si el modelo de subprocesos del autor de la llamada no es Apartment). Las llamadas a ShellExecuteEx desde procesos que ya se ejecutan en subprocesos en segundo plano siempre deben pasar esta marca. Además, las aplicaciones que salen inmediatamente después de llamar a ShellExecuteEx deben especificar esta marca.
Si la operación de ejecución se realiza en un subproceso en segundo plano y el autor de la llamada no especificó la marca SEE_MASK_ASYNCOK, el subproceso que realiza la llamada espera hasta que se haya iniciado el nuevo proceso antes de devolverlo. Normalmente, esto significa que se ha llamado a CreateProcess , se ha completado la comunicación DDE o que el delegado de ejecución personalizado ha notificado a ShellExecuteEx que se realiza. Si se especifica la marca SEE_MASK_WAITFORINPUTIDLE, ShellExecuteEx llama a WaitForInputIdle y espera a que el nuevo proceso esté inactivo antes de volver, con un tiempo de espera máximo de 1 minuto. Para obtener más información sobre cuándo es necesario esta marca, consulte la sección Comentarios. |
| SEE_MASK_FLAG_DDEWAIT (0x00000100) | Igual que SEE_MASK_NOASYNC, se prefiere el uso de esa opción. |
| SEE_MASK_DOENVSUBST (0x00000200) | Expanda las variables de entorno especificadas en la cadena dada por el miembro lpDirectory o lpFile . |
| SEE_MASK_FLAG_NO_UI (0x00000400) | No muestre ninguna interfaz de usuario (UI), incluidos cuadros de diálogo de error, advertencias de seguridad u otra interfaz de usuario que normalmente se presentaría sin esta opción. |
| SEE_MASK_UNICODE (0x00004000) | Use esta marca para indicar una aplicación Unicode. |
| SEE_MASK_NO_CONSOLE (0x00008000) | Use para heredar la consola del elemento primario para el nuevo proceso en lugar de hacer que cree una nueva consola. Es lo contrario de usar una marca de CREATE_NEW_CONSOLE con CreateProcess. |
| SEE_MASK_ASYNCOK (0x00100000) | La ejecución se puede realizar en un subproceso en segundo plano y la llamada debe devolverse inmediatamente sin esperar a que finalice el subproceso en segundo plano. Tenga en cuenta que en determinados casos ShellExecuteEx omite esta marca y espera a que finalice el proceso antes de devolverlo. |
| SEE_MASK_NOQUERYCLASSSTORE (0x01000000) | No se usa. |
| SEE_MASK_HMONITOR (0x00200000) | Use esta marca al especificar un monitor en sistemas de varios monitores. El monitor se especifica en el miembro hMonitor . Esta marca no se puede combinar con SEE_MASK_ICON. |
| SEE_MASK_NOZONECHECKS (0x00800000) | No realice una comprobación de zona. Esta marca permite que ShellExecuteEx omita la comprobación de zona puesta en marcha por IAttachmentExecute. |
| SEE_MASK_WAITFORINPUTIDLE (0x02000000) | Una vez creado el nuevo proceso, espere a que el proceso esté inactivo antes de volver, con un tiempo de espera de un minuto. Consulte WaitForInputIdle para obtener más detalles. |
| SEE_MASK_FLAG_LOG_USAGE (0x04000000) | Indica un inicio iniciado por el usuario que permite el seguimiento de programas usados con frecuencia y otros comportamientos. |
| SEE_MASK_FLAG_HINST_IS_SITE (0x08000000) | El miembro hInstApp se usa para especificar el IUnknown de un objeto que implementa IServiceProvider. Este objeto se usará como puntero de sitio. El puntero de sitio se usa para proporcionar servicios a la función ShellExecute , el proceso de enlace del controlador y los controladores de verbo invocados.
Se puede proporcionar ICreatingProcess para permitir que el autor de la llamada modifique algunos parámetros del proceso que se está creando. Esta marca se admite en Windows 8 y versiones posteriores. Cuando se especifica esta opción, la llamada se ejecuta sincrónicamente en el subproceso que realiza la llamada. |
hwnd
Tipo: HWND
Opcional. Identificador de la ventana del propietario, que se usa para mostrar y colocar cualquier interfaz de usuario que el sistema pueda producir al ejecutar esta función.
lpVerb
Tipo: LPCTSTR
Cadena, denominada verbo, que especifica la acción que se va a realizar. El conjunto de verbos disponibles depende del archivo o carpeta concretos. Por lo general, las acciones disponibles en el menú contextual de un objeto están disponibles verbos. Este parámetro puede ser NULL, en cuyo caso se usa el verbo predeterminado si está disponible. Si no es así, se usa el verbo "open". Si ninguno de los verbos está disponible, el sistema usa el primer verbo enumerado en el Registro. A menos que haya un motivo para limitar la acción a un verbo específico, pase NULL para usar el valor predeterminado calculado. Esto es necesario en algunos casos, por ejemplo, al especificar SEE_MASK_FLAG_NO_UI y la intención es generar la interfaz de usuario "Abrir con", si no hay ninguna aplicación instalada.
Los verbos siguientes se usan normalmente:
- editar: inicia un editor y abre el documento para su edición. Si lpFile no es un archivo de documento, se producirá un error en la función.
- explore: explora la carpeta especificada por lpFile.
- find: inicia una búsqueda a partir del directorio especificado.
- open: abre el archivo especificado por el parámetro lpFile . El archivo puede ser un archivo ejecutable, un archivo de documento o una carpeta.
- print: imprime el archivo de documento especificado por lpFile. Si lpFile no es un archivo de documento, se producirá un error en la función.
- properties: muestra las propiedades del archivo o la carpeta.
- runas: inicia una aplicación como administrador. El Control de cuentas de usuario (UAC) solicitará al usuario que dé su consentimiento para ejecutar la aplicación con privilegios elevados o escribirá las credenciales de una cuenta de administrador usada para ejecutar la aplicación.
lpFile
Tipo: LPCTSTR
Dirección de una cadena terminada en null que especifica el nombre del archivo o objeto en el que ShellExecuteEx realizará la acción especificada por el parámetro lpVerb . Los verbos del Registro del sistema admitidos por la función ShellExecuteEx incluyen "abrir" para archivos ejecutables y archivos de documento y "imprimir" para los archivos de documento para los que se ha registrado un controlador de impresión. Es posible que otras aplicaciones hayan agregado verbos de Shell a través del registro del sistema, como "reproducir" para archivos .avi y .wav. Para especificar un objeto de espacio de nombres de Shell, pase el nombre de análisis completo y establezca la marca SEE_MASK_INVOKEIDLIST en el parámetro fMask .
lpParameters
Tipo: LPCTSTR
Opcional. Dirección de una cadena terminada en null que contiene los parámetros de la aplicación. Los parámetros deben estar separados por espacios. Si el miembro lpFile especifica un archivo de documento, lpParameters debe ser NULL.
lpDirectory
Tipo: LPCTSTR
Opcional. Dirección de una cadena terminada en null que especifica el nombre del directorio de trabajo. Si este miembro es NULL, el directorio actual se usa como directorio de trabajo.
nShow
Tipo: int
Necesario. Marcas que especifican cómo se va a mostrar una aplicación cuando se abre; uno de los valores de SW_ enumerados para la función ShellExecute . Si lpFile especifica un archivo de documento, la marca se pasa simplemente a la aplicación asociada. La aplicación decide cómo controlarla.
hInstApp
Tipo: HINSTANCE
[out] Si SEE_MASK_NOCLOSEPROCESS se establece y la llamada a ShellExecuteEx se realiza correctamente, establece este miembro en un valor mayor que 32. Si se produce un error en la función, se establece en un valor de error SE_ERR_XXX que indica la causa del error. Aunque hInstApp se declara como HINSTANCE por compatibilidad con aplicaciones Windows de 16 bits, no es un verdadero HINSTANCE. Solo se puede convertir en un valor int y en comparación con los códigos de error 32 o los siguientes SE_ERR_XXX.
| Código de error | Motivo |
|---|---|
| SE_ERR_FNF (2) | No se encontró el archivo. |
| SE_ERR_PNF (3) | Ruta de acceso no encontrada. |
| SE_ERR_ACCESSDENIED (5) | Acceso denegado. |
| SE_ERR_OOM (8) | Memoria insuficiente |
| SE_ERR_DLLNOTFOUND (32) | No se encontró la biblioteca de vínculos dinámicos. |
| SE_ERR_SHARE (26) | No se puede compartir un archivo abierto. |
| SE_ERR_ASSOCINCOMPLETE (27) | Información de asociación de archivo no completada. |
| SE_ERR_DDETIMEOUT (28) | Se agota el tiempo de espera de la operación DDE. |
| SE_ERR_DDEFAIL (29) | Error en la operación DDE. |
| SE_ERR_DDEBUSY (30) | La operación DDE está ocupada. |
| SE_ERR_NOASSOC (31) | La asociación de archivos no está disponible. |
lpIDList
Tipo: LPVOID
Dirección de una estructura ITEMIDLIST absoluta (PCIDLIST_ABSOLUTE) que contiene una lista de identificadores de elemento que identifica de forma única el archivo que se va a ejecutar. Este miembro se omite si el miembro fMask no incluye SEE_MASK_IDLIST o SEE_MASK_INVOKEIDLIST.
lpClass
Tipo: LPCTSTR
Dirección de una cadena terminada en null que especifica una de las siguientes opciones:
- Un progId. Por ejemplo, "Paint.Picture".
- Esquema de protocolo URI. Por ejemplo, "http".
- Extensión de archivo. Por ejemplo, ".txt".
- Ruta de acceso del Registro en HKEY_CLASSES_ROOT que asigna un nombre a una subclave que contiene uno o varios verbos de Shell. Esta clave tendrá una subclave que se ajuste al esquema del registro de verbos de Shell, comoel nombre del verbode shell\.
Este miembro se omite si fMask no incluye SEE_MASK_CLASSNAME.
hkeyClass
Tipo: HKEY
Identificador de la clave del Registro para el tipo de archivo. Los derechos de acceso de esta clave del Registro deben establecerse en KEY_READ. Este miembro se omite si fMask no incluye SEE_MASK_CLASSKEY.
dwHotKey
Tipo: DWORD
Método abreviado de teclado que se va a asociar a la aplicación. La palabra de orden bajo es el código de clave virtual y la palabra de orden superior es una marca modificadora (HOTKEYF_). Para obtener una lista de marcas modificadores, consulte la descripción del mensaje de WM_SETHOTKEY . Este miembro se omite si fMask no incluye SEE_MASK_HOTKEY.
DUMMYUNIONNAME
DUMMYUNIONNAME.hIcon
Tipo: HANDLE
Identificador del icono del tipo de archivo. Este miembro se omite si fMask no incluye SEE_MASK_ICON. Este valor solo se usa en Windows XP y versiones anteriores. Se omite a partir de Windows Vista.
DUMMYUNIONNAME.hMonitor
Tipo: HANDLE
Identificador del monitor en el que se va a mostrar el documento. Este miembro se omite si fMask no incluye SEE_MASK_HMONITOR.
hProcess
Tipo: HANDLE
Identificador de la aplicación recién iniciada. Este miembro se establece en return y siempre es NULL a menos que fMask esté establecido en SEE_MASK_NOCLOSEPROCESS. Incluso si fMask está establecido en SEE_MASK_NOCLOSEPROCESS, hProcess será NULL si no se inició ningún proceso. Por ejemplo, si un documento que se va a iniciar es una dirección URL y ya se está ejecutando una instancia de Internet Explorer, mostrará el documento. No se inicia ningún nuevo proceso y hProcess será NULL.
Comentarios
La marca SEE_MASK_NOASYNC debe especificarse si el subproceso que llama a ShellExecuteEx no tiene un bucle de mensajes o si el subproceso o proceso finalizará poco después de que ShellExecuteEx devuelva. En tales condiciones, el subproceso que realiza la llamada no estará disponible para completar la conversación DDE, por lo que es importante que ShellExecuteEx complete la conversación antes de devolver el control a la aplicación que realiza la llamada. Si no se completa la conversación, se puede producir un inicio incorrecto del documento.
Si el subproceso que realiza la llamada tiene un bucle de mensajes y existirá durante algún tiempo después de que se devuelva la llamada a ShellExecuteEx , la marca SEE_MASK_NOASYNC es opcional. Si se omite la marca, la bomba de mensajes del subproceso que realiza la llamada se usará para completar la conversación DDE. La aplicación que realiza la llamada recupera el control antes, ya que la conversación DDE se puede completar en segundo plano.
Para incluir comillas dobles en lpParameters, incluya cada marca entre comillas, como en el ejemplo siguiente.
sei.lpParameters = "An example: \"\"\"quoted text\"\"\"";
En este caso, la aplicación recibe tres parámetros: An, example:, y "quoted text".
Nota
El encabezado shellapi.h define SHELLEXECUTEINFO como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Encabezado | shellapi.h |
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de