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.
- Cree un archivo denominado Test.htm en el directorio C:\Files (C:\Files\Test.htm).
- Cree una carpeta denominada Test.files en el directorio C:\Files (C:\Files\Test.files).
- Rellene la carpeta con algunos archivos. Cualquier archivo colocado en esta carpeta está conectado a Test.htm.
- Mueva o copie el archivo Test.htm al directorio C:\Files2.
- 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) |