Función SHFileOperationA (shellapi.h)

Copia, mueve, cambia el nombre o elimina un objeto del sistema de archivos. Esta función se ha reemplazado en Windows Vista por IFileOperation.

Sintaxis

int SHFileOperationA(
  [in, out] LPSHFILEOPSTRUCTA lpFileOp
);

Parámetros

[in, out] lpFileOp

Tipo: LPSHFILEOPSTRUCT

Puntero a una estructura SHFILEOPSTRUCT que contiene información que esta función necesita para llevar a cabo la operación especificada. Este parámetro debe contener un valor válido que no sea NULL. Usted es responsable de validar el valor. Si no la valida, experimentará resultados inesperados.

Valor devuelto

Tipo: int

Devuelve cero si se ejecuta correctamente; de lo contrario, distinto de cero. Las aplicaciones normalmente deben comprobar si hay cero o distinto de cero.

Es recomendable examinar el valor del miembro fAnyOperationsAborted del SHFILEOPSTRUCT. SHFileOperation puede devolver 0 si el usuario cancela la operación correctamente. Si no comprueba fAnyOperationsAborted , así como el valor devuelto, no puede saber que la función realizó la tarea completa que solicitó y podría continuar bajo suposiciones incorrectas.

No use GetLastError con los valores devueltos de esta función.

Para examinar los valores distintos de cero con fines de solución de problemas, se asignan en gran medida a los definidos en Winerror.h. Sin embargo, varios de sus posibles valores devueltos se basan en códigos de error anteriores a Win32, que en algunos casos se superponen a los valores winerror.h posteriores sin que coincidan con su significado. Estos valores concretos se detallan aquí y , para estos valores específicos, solo se deben aceptar estos significados en los códigos Winerror.h. Sin embargo, estos valores se proporcionan con estas advertencias:

• Estos son códigos de error anteriores a Win32 y ya no se admiten ni definen en ningún archivo de encabezado público. Para usarlos, debe definirlos usted mismo o compararlos con el valor numérico.
• Estos códigos de error están sujetos a cambios y lo han hecho históricamente.
• Estos valores solo se proporcionan como ayuda para la depuración. No deberían considerarse definitivas.

Código de error	Valor	Significado
DE_SAMEFILE	0x71	Los archivos de origen y destino son el mismo archivo.
DE_MANYSRC1DEST	0x72	Se especificaron varias rutas de acceso de archivo en el búfer de origen, pero solo una ruta de acceso de archivo de destino.
DE_DIFFDIR	0x73	Se especificó la operación de cambio de nombre, pero la ruta de acceso de destino es un directorio diferente. Use la operación de movimiento en su lugar.
DE_ROOTDIR	0x74	El origen es un directorio raíz, que no se puede mover ni cambiar de nombre.
DE_OPCANCELLED	0x75	El usuario canceló la operación o canceló silenciosamente si se proporcionaron las marcas adecuadas a SHFileOperation.
DE_DESTSUBTREE	0x76	El destino es un subárbol del origen.
DE_ACCESSDENIEDSRC	0x78	La configuración de seguridad denegó el acceso al origen.
DE_PATHTOODEEP	0x79	La ruta de acceso de origen o de destino superó o superaría MAX_PATH.
DE_MANYDEST	0x7A	La operación implica varias rutas de acceso de destino, que pueden producir un error en el caso de una operación de movimiento.
DE_INVALIDFILES	0x7C	La ruta de acceso del origen o el destino o ambas no eran válidas.
DE_DESTSAMETREE	0x7D	El origen y el destino tienen la misma carpeta primaria.
DE_FLDDESTISFILE	0x7E	La ruta de acceso de destino es un archivo existente.
DE_FILEDESTISFLD	0x80	La ruta de acceso de destino es una carpeta existente.
DE_FILENAMETOOLONG	0x81	El nombre del archivo supera MAX_PATH.
DE_DEST_IS_CDROM	0x82	El destino es un CD-ROM de solo lectura, posiblemente sin formato.
DE_DEST_IS_DVD	0x83	El destino es un DVD de solo lectura, posiblemente sin formato.
DE_DEST_IS_CDRECORD	0x84	El destino es un CD-ROM grabable, posiblemente sin formato.
DE_FILE_TOO_LARGE	0x85	El archivo implicado en la operación es demasiado grande para el sistema de archivos o medios de destino.
DE_SRC_IS_CDROM	0x86	El origen es un CD-ROM de solo lectura, posiblemente sin formato.
DE_SRC_IS_DVD	0x87	El origen es un DVD de solo lectura, posiblemente sin formato.
DE_SRC_IS_CDRECORD	0x88	El origen es un CD-ROM grabable, posiblemente sin formato.
DE_ERROR_MAX	0xB7	MAX_PATH se superó durante la operación.
	0x402	Se produjo un error desconocido. Esto suele deberse a una ruta de acceso no válida en el origen o destino. Este error no se produce en Windows Vista y versiones posteriores.
ERRORONDEST	0x10000	Error no especificado en el destino.
DE_ROOTDIR | ERRORONDEST	0x10074	El destino es un directorio raíz y no se puede cambiar el nombre.

Comentarios

Debe usar nombres de ruta de acceso completos con esta función. Su uso con nombres de ruta de acceso relativos no es seguro para subprocesos.

Con dos excepciones, no se puede usar SHFileOperation para mover carpetas especiales de una unidad local a un equipo remoto especificando una ruta de acceso de red. Las excepciones son las carpetas Mis documentos (CSIDL_PERSONAL, CSIDL_DOCUMENTS) y Mis imágenes (CSIDL_MYPICTURES).

Cuando se usa para eliminar un archivo, SHFileOperation elimina permanentemente el archivo a menos que establezca la marca FOF_ALLOWUNDO en el miembro fFlags de la estructura SHFILEOPSTRUCT a la que apunta lpFileOp. Establecer esa marca envía el archivo a la Papelera de reciclaje. Si desea eliminar simplemente un archivo y garantizar que no se coloca en la Papelera de reciclaje, use DeleteFile.

Si se expone y registra un controlador de devolución de llamada de copia, SHFileOperation lo llama a menos que establezca una marca como FOF_NOCONFIRMATION en el miembro fFlags de la estructura a la que apunta lpFileOp. Consulte ICopyHook::CopyCallback para obtener más información sobre cómo implementar controladores de devolución de llamada de copia.

La eliminación de archivos es recursiva a menos que establezca la marca FOF_NORECURSION en lpFileOp.

Conexión de archivos

Con Windows 2000 o posterior, es posible conectar un archivo HTML con una carpeta que contenga archivos relacionados, como imágenes de formato de intercambio de gráficos (GIF) o hojas de estilos. Si la conexión de archivos está habilitada, al mover o copiar el archivo HTML, la carpeta conectada y todos sus archivos también se mueven o copian. Por el contrario, si mueve la carpeta con los archivos relacionados, también se mueve el archivo HTML.

El archivo HTML debe tener una extensión .htm o .html. Para crear la conexión a los archivos relacionados, coloque la carpeta que los contiene en la misma carpeta que el archivo HTML. El nombre de la carpeta que contiene los archivos conectados debe ser el mismo que el nombre del archivo HTML seguido de "_files" o ".files" (esto distingue mayúsculas de minúsculas; por ejemplo, ". Los archivos" no funcionan). Aquí se proporciona un ejemplo.

1. Cree un archivo denominado Test.htm en el directorio C:\Files (C:\Files\Test.htm).
2. Cree una carpeta denominada Test.files en el directorio C:\Files (C:\Files\Test.files).
3. Rellene la carpeta con algunos archivos. Cualquier archivo colocado en esta carpeta está conectado a Test.htm.
4. Mueva o copie el archivo Test.htm al directorio C:\Files2.
5. Tenga en cuenta que el directorio Test.files también se encuentra en el directorio C:\Files2.

La conexión de archivos está habilitada de forma predeterminada. Se puede deshabilitar agregando una entrada de REG_DWORD , NoFileFolderConnection, como se muestra aquí:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  NoFileFolderConnection

Si se establece NoFileFolderConnection en 1, se deshabilita la conexión de archivos. Si el valor está establecido en cero o falta, la conexión de archivos está habilitada.

Para mover solo los archivos especificados y ninguno de los archivos conectados, establezca la marca FOF_NO_CONNECTED_ELEMENTS en el miembro fFlags de la estructura a la que apunta lpFileOp.

Tenga en cuenta que el uso de una carpeta con un nombre como "MyFile_files" para definir una conexión puede no ser válido para las versiones localizadas de Windows. Es posible que el término "files" tenga que reemplazarse por la palabra equivalente en el idioma local.

Nota

El encabezado shellapi.h define SHFileOperation 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 4.0 o posterior)
Conjunto de API	ext-ms-win-shell-shell32-l1-2-1 (introducido en Windows 10, versión 10.0.10240)