ShellExecute

La función ShellExecute realiza una operación en el fichero especificado.

Sintaxis

HINSTANCE ShellExecute(
  HWND    hwnd,
  LPCTSTR lpOperation,
  LPCTSTR lpFile,
  LPCTSTR lpParameters,
  LPCTSTR lpDirectory,
  INT     nShowCmd
);

Parámetros

hWnd: Un manipulador a la ventana padre usada para mostrar un interfaz de usuario o mensajes de error. Este valor puede serNULL si la operación no está asociada con una ventana.

lpOperation: Un puntero a una cadena terminada en cero, usada en este caso como un verbo, que especifica la acción a realizar. El conjunto de verbos disponibles depende del fichero o carpeta en particular. Generalmente, las acciones disponibles desde el atajo de menú del objeto están disponibles como verbos. Los siguientes verbos son de uso general:

edit

Lanza un editor y abre el documento para edición. Si lpFile no es un fichero de documento, la función fallará.

explore

Explora una carpeta especificada por lpFile.

find

Inicia una búsqueda en el directorio especifiado por lpDirectory.

open

Abre el ítem especificado por el parámetro lpFile. El ítem puede ser un fichero o una carpeta.

print

Imprime el fichero especificado por lpFile. Si lpFile no es un fichero de documento, la función fallará.

NULL

Se usa el verbo por defecto, si está disponible. Si no, se usará el verbo "open". Si ningún verbo está disponible, el sistema usa el primer verbo listado en el registro.

lpFile: Un puntero a una cadena terminada en cero que especifica el fichero u objeto en el que se ejecutará el verbo especifiado. Para especificar un objeto del espacio de nombres del Shell, hay que pasar el nombre completo de análisis. Hay que tener en cuenta que no todos los verbos están soportados para todos los objetos. Por ejemplo, no todos los tipos de documentos soportan el verbo "print". Si se usa un camino relativo para el parámetro lpDirectory no se debe usar uno para lpFile.

lpParameters: Si lpFile especifica un fichero ejecutable, este parámetro es un puntero a una cadena terminada en cero que especifica los parámetros a pasar a la aplicación. El formato de esta cadena se determina por el verbo que se va a invocar. Si lpFile especifica un fichero de documento, lpParameters debe ser NULL.

lpDirectory: Un puntero a una cadena terminada con cero que especifica el directorio de trabajo por defecto para la acción. Si este valor es NULL, se usará el directorio de trabajo actual. Si se proporciona un camino relativo para lpFile, no se debe usar para lpDirectory.

nShowCmd: Las banderas que especifican como se mostrará la aplicación cuando se abra. Si lpFile especifica un fichero de documento, la bandera sencillamente es pasada a la aplicación asociada. Se deja a la aplicación la decisión de como manejarla. Estos valores se definen en Winuser.h.

SW_HIDE (0)

Oculta la ventana y activa otra.

SW_MAXIMIZE (3)

Maximiza la ventana especificada.

SW_MINIMIZE (6)

Minimiza la ventana especificada y activa la siguiente ventana top-level en el orden z.

SW_RESTORE (9)

Activa y muestra la ventana. Si la ventana está minimizada o maximizada, Windows restaura su tamaño y posición originales. Una aplicación debe especificar esta bandera cuando restaure una ventana minimizada.

SW_SHOW (5)

Activa la ventana y la muestra en su tamaño y posición actuales.

SW_SHOWDEFAULT (10)

Asigna el estado de muestra basándose en la bandera SW_ especificada en la estructura STARTUPINFO pasada a la función CreateProcess por el programa que ha lanzado la aplicación. La aplicación debe invocar ShowWindow con esta bandera para asignar el estado de muestra inicial de su ventana principal.

SW_SHOWMAXIMIZED (3)

Activa la ventana y la muestra como una ventana maximizada.

SW_SHOWMINIMIZED (2)

Activa la ventana y la muestra como una ventana minimizada.

SW_SHOWMINNOACTIVE (7)

Muestra la ventana como una ventana minimizada. La ventana activa permanece activa.

SW_SHOWNA (8)

Muestra la ventana en su estado actual. la ventana activa permanece activa.

SW_SHOWNOACTIVATE (4)

Muestra la ventana en su tamaño y posición más reciente. La ventana activa permance activa.

SW_SHOWNORMAL (1)

Activa y muestra la ventana. Si la ventana está minimizada o maximizada, Windows la restaura a su tamaño y posición originales. Una aplicación debe especificar esta bandera cuando muestra la ventana por primera vez.

Valor de retorno

Si la función tiene éxito, devuelve un valor mayor de 32. Si falla, devuelve un valor de error que indica el motivo del fallo. El valor de retorno se devuelve como un HINSTANCE por compatibilidad con aplicaciones Windows de 16 bits. Sin embargo, no se trata de un HINSTANCE auténtico. Se puede convetir sólo a un int y comparado con 32 o con uno de los siguientes códigos de error.

Observaciones

Como ShellExecute puede delegar la ejecución a extensiones del Shell (fuentes de datos, manipuladores de menú contextual, implementaciones de verbos) que se activan usando Component Object Model (COM), COM debe ser iniciado antes de llamar a ShellExecute. Algunas extensiones del Shell requieren el tipo de COM single-threaded apartment (STA). En ese caso, se debe iniciar COM como se muestra a continuación:

CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE)

Hay ciertas instancias donde ShellExecute no usa uno de estos tipos de extensión de Shell y esas instancias no requieren que se inicie COM. No obstanet, es una buena práctica iniciar siempre COM antes de usar esta función.

Este método permite ejecutar cualquier comando en el atajo de menú de una carpeta o almacenados en el registro.

Para abrir una carpeta, usar 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, usar la siguiente llamada.

ShellExecute(handle, "explore", <fully_qualified_path_to_folder>, NULL, NULL, SW_SHOWNORMAL);

Para lanzar la utilidad de búsqueda del Shell para un directorio, usar esta llamada:

ShellExecute(handle, "find", <fully_qualified_path_to_folder>, NULL, NULL, 0);

Si lpOperation es NULL, la función abre el fichero 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 será lanzada como resultado de la llamada a ShellExecute, usar ShellExecuteEx.

Nota: las ventanas de carpeta de un proceso separado asignadas por las opciones de carpeta afectan a ShellExecute. Si esta opción está desactivada (activada por defecto), ShellExecute usa una ventana de Explorer abierta en lugar de lanzar una nueva. Si no hay una ventana de Explorer abierta, ShellExecute abre una nueva.