Función ShellExecuteA (shellapi.h)

Artículo
03/15/2023

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 utilizada 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

Puntero a una cadena terminada en null, a la que se hace referencia en este caso como 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:

edición

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 una carpeta especificada por lpFile.

find

Inicia una búsqueda que comienza en el directorio especificado por lpDirectory.

abrir

Abre el elemento especificado por el parámetro lpFile . El elemento puede ser un archivo o una carpeta.

imprimir

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) pedirá al usuario que dé su consentimiento para ejecutar la aplicación con privilegios elevados o escriba las credenciales de una cuenta de administrador usada para ejecutar la aplicación.

NULL

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

Puntero a una cadena terminada en null que 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 completo del análisis. Tenga en cuenta que no todos los verbos son compatibles con 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 , no use una ruta de acceso relativa para lpFile.

[in, optional] lpParameters

Tipo: LPCTSTR

Si lpFile especifica un archivo ejecutable, este parámetro es un puntero a una cadena terminada en null que 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

Puntero a una cadena terminada en null que 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 se pasa simplemente 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 realiza 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 compararlo con los códigos de error 32 o siguientes.

Código devuelto	Descripción
0	El sistema operativo no tiene memoria o recursos.
ERROR_FILE_NOT_FOUND	No se encontró el archivo especificado.
ERROR_PATH_NOT_FOUND	No se encontró la ruta de acceso especificada.
ERROR_BAD_FORMAT	El archivo de .exe no es válido (no es win32 .exe o error en .exe imagen).
SE_ERR_ACCESSDENIED	El sistema operativo denegó el acceso al archivo especificado.
SE_ERR_ASSOCINCOMPLETE	La asociación del nombre de archivo está incompleta o no es válida.
SE_ERR_DDEBUSY	No se pudo completar la transacción DDE porque se estaban procesando otras transacciones DDE.
SE_ERR_DDEFAIL	Error en la transacción DDE.
SE_ERR_DDETIMEOUT	No se pudo completar la transacción DDE porque se agota el tiempo de espera de la solicitud.
SE_ERR_DLLNOTFOUND	No se encontró el archivo DLL especificado.
SE_ERR_FNF	No se encontró el archivo especificado.
SE_ERR_NOASSOC	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.
SE_ERR_OOM	No había suficiente memoria para completar la operación.
SE_ERR_PNF	No se encontró la ruta de acceso especificada.
SE_ERR_SHARE	Se ha producido una infracción de uso compartido.

Llame a GetLastError para obtener información de error extendida.

Comentarios

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 llamar a ShellExecute . Algunas extensiones de Shell requieren el tipo de apartamento de un solo subproceso (STA) COM. 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 inicializar siempre 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);

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 ShellExecuteEx.

Nota Las ventanas iniciar carpeta en una configuración de proceso independiente en Opciones de carpeta afectan a ShellExecute. Si esa opción está deshabilitada (la configuración predeterminada), ShellExecute usa una ventana del Explorador abierta en lugar de iniciar una nueva. Si no hay ninguna ventana del Explorador abierta, ShellExecute inicia una nueva.

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 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]
Plataforma de destino	Windows
Encabezado	shellapi.h
Library	Shell32.lib
Archivo DLL	Shell32.dll (versión 3.51 o posterior)