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)