Estructura SHELLEXECUTEINFOA (shellapi.h)
Contiene información usada por ShellExex.
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 de
Obligatorio. Tamaño de esta estructura, en bytes.
fMask
Tipo:
Combinación de uno o varios de los siguientes valores 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 de |
| SEE_MASK_CLASSKEY (0x00000003) | Use la clave de clase proporcionada por el miembro hkeyClass |
| SEE_MASK_IDLIST (0x00000004) | Use la lista de identificadores de elemento dada por el miembro lpIDList de |
| SEE_MASK_INVOKEIDLIST (0x0000000C) | Use la interfaz
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 ShellExEx finaliza. En algunos casos, como cuando se cumple 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 habilita 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 pueden provocar una activación asincrónica, por ejemplo, DDE, y crear un proceso que se pueda ejecutar en un subproceso en segundo plano. (Nota: ShellExex 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 ShellExex 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 ShellExEx 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 volver. Esto suele significar que se ha llamado CreateProcess, la comunicación de DDE se ha completado o que el delegado de ejecución personalizado ha notificado ShellExEx que se realiza. Si se especifica la marca SEE_MASK_WAITFORINPUTIDLE, ShellEx 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, vea 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 cualquier variable de entorno especificada en la cadena dada por el lpDirectory o miembro lpFile. |
| SEE_MASK_FLAG_NO_UI (0x00000400) | No muestre cuadros de diálogo de error de la interfaz de usuario (UI) que normalmente se presentarían sin esta opción. Los avisos de seguridad están exentos y se seguirán mostrando. |
| 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 tener que crear 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, ShellExex omite esta marca y espera a que el proceso finalice 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 a ShellExecuteEx omitir la comprobación de zona puesta en marcha IAttachmentExecute. |
| SEE_MASK_WAITFORINPUTIDLE (0x02000000) | Una vez creado el nuevo proceso, espere a que el proceso quede inactivo antes de volver, con un tiempo de espera de un minuto. Consulte WaitForInputIdle para obtener más información. |
| SEE_MASK_FLAG_LOG_USAGE (0x04000000) | Indica un inicio iniciado por el usuario que habilita el seguimiento de programas usados con frecuencia y otros comportamientos. |
| SEE_MASK_FLAG_HINST_IS_SITE (0x08000000) | El miembro ICreatingProcess se puede proporcionar 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 de
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 una razón 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.
- explorar: explora la carpeta especificada por lpFile.
- buscar: inicia una búsqueda a partir del directorio especificado.
abrir : abre el archivo especificado por el parámetro lpFile de. El archivo puede ser un archivo ejecutable, un archivo de documento o una carpeta. - openas: inicia una interfaz de usuario del selector que permite al usuario seleccionar una aplicación con la que abrir el archivo especificado por el parámetro lpFile.
- imprimir: imprime el archivo de documento especificado por lpFile. Si lpFile no es un archivo de documento, se producirá un error en la función.
- propiedades: 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 que se usa para ejecutar la aplicación.
lpFile
Tipo: LPCTSTR de
Dirección de una cadena terminada en null que especifica el nombre del archivo o objeto en el que
lpParameters
Tipo: LPCTSTR de
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 de lpFile de
lpDirectory
Tipo: LPCTSTR de
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
Obligatorio. 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 de
hInstApp
Tipo: HINSTANCE
[out] Si se establece SEE_MASK_NOCLOSEPROCESS y la llamada shellExex de
| Código de error | Razón |
|---|---|
| SE_ERR_FNF (2) | Archivo no encontrado. |
| 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) | La información de asociación de archivos no se ha completado. |
| 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) | Asociación de archivos no disponible. |
lpIDList
Tipo: LPVOID de
Dirección de una estructura ITEMIDLIST absoluta
lpClass
Tipo: LPCTSTR de
Dirección de una cadena terminada en NULL que especifica una de las siguientes opciones:
- A ProgId. Por ejemplo, "Paint.Picture".
- Un 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, como shell\nombre de verbo.
Este miembro se omite si fMask no incluye SEE_MASK_CLASSNAME.
hkeyClass
Tipo: HKEY de
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 de
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, vea la descripción del mensaje WM_SETHOTKEY. Este miembro se omite si fMask no incluye SEE_MASK_HOTKEY.
DUMMYUNIONNAME
DUMMYUNIONNAME.hIcon
Tipo: HANDLE de
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 de
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 de
Identificador de la aplicación recién iniciada. Este miembro se establece en return y siempre se 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 se NULL.
Observaciones
La marca SEE_MASK_NOASYNC debe especificarse si el subproceso que llama a ShellExEx no tiene un bucle de mensajes o si el subproceso o proceso finalizará poco después de que se devuelva ShellExEx. 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 completar 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 de llamada tiene un bucle de mensajes y existirá durante algún tiempo después de la llamada a ShellExEx devuelve, la marca SEE_MASK_NOASYNC es opcional. Si se omite la marca, la bomba de mensajes del subproceso de 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: Un, ejemplo:y "texto entre comillas".
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 Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| cliente mínimo admitido | Windows XP [solo aplicaciones de escritorio] |
| servidor mínimo admitido | Windows 2000 Server [solo aplicaciones de escritorio] |
| encabezado de |
shellapi.h |