Función ShellExecuteA (shellapi.h)
Realiza una operación en un archivo especificado.
Sintaxis
HINSTANCE ShellExecuteA(
[in, optional] HWND hwnd,
[in, optional] LPCSTR lpOperation,
[in] LPCSTR lpFile,
[in, optional] LPCSTR lpParameters,
[in, optional] LPCSTR lpDirectory,
[in] INT nShowCmd
);
Parámetros
[in, optional] hwnd
Tipo: HWND
Identificador de la ventana primaria que se usa para mostrar una interfaz de usuario o mensajes de error. Este valor puede ser NULL si la operación no está asociada a una ventana.
[in, optional] lpOperation
Tipo: LPCTSTR de
Puntero a un cadena terminadanull, denominada en este caso como un 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. 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 una carpeta especificada por lpFile.
encontrar
Inicia una búsqueda que comienza en el directorio especificado por lpDirectory.
abrir
Abre el elemento especificado por el parámetro lpFile
Impresión
Imprime el archivo especificado por lpFile. Si lpFile no es un archivo de documento, se produce un error en la función.
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.
NULO
Si está disponible, se usa el verbo predeterminado. 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.
[in] lpFile
Tipo: LPCTSTR de
Puntero a un cadena terminada en nullque especifica el archivo o el objeto en el que se va a ejecutar el verbo especificado. Para especificar un objeto de espacio de nombres shell, pase el nombre de análisis completo. Tenga en cuenta que no todos los verbos se admiten en todos los objetos. Por ejemplo, no todos los tipos de documento admiten el verbo "print". Si se usa una ruta de acceso relativa para el parámetro lpDirectory
[in, optional] lpParameters
Tipo: LPCTSTR de
Si lpFile especifica un archivo ejecutable, este parámetro es un puntero a un cadena terminada en nullque especifica los parámetros que se van a pasar a la aplicación. El formato de esta cadena viene determinado por el verbo que se va a invocar. Si lpFile especifica un archivo de documento, lpParameters debe ser NULL.
[in, optional] lpDirectory
Tipo: LPCTSTR de
Puntero a un cadena terminada en nullque especifica el directorio predeterminado (de trabajo) para la acción. Si este valor es NULL, se usa el directorio de trabajo actual. Si se proporciona una ruta de acceso relativa en lpFile, no use una ruta de acceso relativa para lpDirectory.
[in] nShowCmd
Tipo: INT
Marcas que especifican cómo se va a mostrar una aplicación cuando se abre. Si lpFile especifica un archivo de documento, la marca simplemente se pasa a la aplicación asociada. Es necesario que la aplicación decida cómo controlarla. Puede ser cualquiera de los valores que se pueden especificar en el parámetro nCmdShow para la función ShowWindow.
Valor devuelto
Tipo: HINSTANCE
Si la función se ejecuta correctamente, devuelve un valor mayor que 32. Si se produce un error en la función, devuelve un valor de error que indica la causa del error. El valor devuelto se convierte como HINSTANCE para la compatibilidad con versiones anteriores con aplicaciones Windows de 16 bits. Sin embargo, no es un verdadero HINSTANCE. Solo se puede convertir a un INT_PTR y en comparación con los códigos de error 32 o los siguientes.
| Código devuelto | Descripción |
|---|---|
|
El sistema operativo no tiene memoria o recursos. |
|
No se encontró el archivo especificado. |
|
No se encontró la ruta de acceso especificada. |
|
El archivo de .exe no es válido (no win32 .exe o error en .exe imagen). |
|
El sistema operativo denegó el acceso al archivo especificado. |
|
La asociación del nombre de archivo está incompleta o no es válida. |
|
No se pudo completar la transacción DDE porque se estaban procesando otras transacciones DDE. |
|
Error en la transacción DDE. |
|
No se pudo completar la transacción DDE porque se agota el tiempo de espera de la solicitud. |
|
No se encontró el archivo DLL especificado. |
|
No se encontró el archivo especificado. |
|
No hay ninguna aplicación asociada a la extensión de nombre de archivo especificada. Este error también se devolverá si intenta imprimir un archivo que no se puede imprimir. |
|
No había suficiente memoria para completar la operación. |
|
No se encontró la ruta de acceso especificada. |
|
Se ha producido una infracción de uso compartido. |
Llame a GetLastError para obtener información de error extendida.
Observaciones
Dado que ShellExecute puede delegar la ejecución en extensiones de Shell (orígenes de datos, controladores de menú contextual, implementaciones de verbo) que se activan mediante el modelo de objetos componentes (COM), se debe inicializar COM antes de que se llame a ShellExecute. Algunas extensiones de Shell requieren el tipo de apartamento de un solo subproceso COM (STA). En ese caso, COM debe inicializarse como se muestra aquí:
CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)
Sin duda, hay instancias en las que ShellExecute no usa uno de estos tipos de extensión de Shell y esas instancias no requerirían que COM se inicialice en absoluto. No obstante, es recomendable siempre inicializar COM antes de usar esta función.
Este método permite ejecutar cualquier comando en el menú contextual de una carpeta o almacenarse en el Registro.
Para abrir una carpeta, use cualquiera de las siguientes llamadas:
ShellExecute(handle, NULL, <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);
o
ShellExecute(handle, "open", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);
Para explorar una carpeta, use la siguiente llamada:
ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);
Para iniciar la utilidad Find de Shell para un directorio, use la siguiente llamada.
ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);
Si lpOperation es null, la función abre el archivo especificado por lpFile. Si lpOperation es "open" o "explore", la función intenta abrir o explorar la carpeta.
Para obtener información sobre la aplicación que se inicia como resultado de llamar a ShellExecute, use ShellExex.
Nota
El encabezado shellapi.h define ShellExecute 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] |
| de la plataforma de destino de |
Windows |
| encabezado de |
shellapi.h |
| biblioteca de |
Shell32.lib |
| DLL de |
Shell32.dll (versión 3.51 o posterior) |
Consulte también
iniciar aplicaciones (ShellExecute, ShellExecuteEx, SHELLEXECUTEINFO)