Compartir a través de

Estructura SHFILEOPSTRUCTA (shellapi.h)

  • Artículo

Contiene información que la función SHFileOperation usa para realizar operaciones de archivo.

Nota A partir de Windows Vista, se recomienda el uso de la interfaz IFileOperation en esta función.
 

Sintaxis

typedef struct _SHFILEOPSTRUCTA {
  HWND         hwnd;
  UINT         wFunc;
  PCZZSTR      pFrom;
  PCZZSTR      pTo;
  FILEOP_FLAGS fFlags;
  BOOL         fAnyOperationsAborted;
  LPVOID       hNameMappings;
  PCSTR        lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;

Miembros

hwnd

Tipo: HWND

Identificador de ventana en el cuadro de diálogo para mostrar información sobre el estado de la operación de archivo.

wFunc

Tipo: UINT

Valor que indica la operación que se va a realizar. Uno de los siguientes valores:

FO_COPY

Copie los archivos especificados en el miembro pFrom en la ubicación especificada en el miembro pTo .

FO_DELETE

Elimine los archivos especificados en pFrom.

FO_MOVE

Mueva los archivos especificados en pFrom a la ubicación especificada en pTo.

FO_RENAME

Cambie el nombre del archivo especificado en pFrom. No puede usar esta marca para cambiar el nombre de varios archivos con una sola llamada de función. Use FO_MOVE en su lugar.

pFrom

Tipo: PCZZTSTR

Nota Esta cadena debe terminar con un valor double-null.
 
Puntero a uno o varios nombres de archivo de origen. Estos nombres deben ser rutas de acceso completas para evitar resultados inesperados.

Los caracteres comodín ms-DOS estándar, como "*", solo se permiten en la posición del nombre de archivo. El uso de un carácter comodín en otra parte de la cadena provocará resultados impredecibles.

Aunque este miembro se declara como una sola cadena terminada en null, en realidad es un búfer que puede contener varios nombres de archivo delimitados por null. Cada nombre de archivo finaliza con un solo carácter NULL . El nombre de archivo finalizó con un carácter NULL doble ("\0\0") para indicar el final del búfer.

pTo

Tipo: PCZZTSTR

Nota Esta cadena debe terminar con un valor double-null.
 
Puntero al nombre de directorio o archivo de destino. Este parámetro debe establecerse en NULL si no se usa. No se permiten caracteres comodín. Su uso dará lugar a resultados imprevisibles.

Al igual que pFrom, el miembro pTo también es una cadena terminada en doble null y se controla de la misma manera. Sin embargo, pTo debe cumplir las siguientes especificaciones:

  • No se admite el uso de caracteres comodín.
  • Las operaciones copiar y mover pueden especificar directorios de destino que no existen. En esos casos, el sistema intenta crearlos y, normalmente, muestra un cuadro de diálogo para preguntar al usuario si desea crear el nuevo directorio. Para suprimir este cuadro de diálogo y hacer que los directorios se creen de forma silenciosa, establezca la marca FOF_NOCONFIRMMKDIR en fFlags.
  • En el caso de las operaciones copiar y mover, el búfer puede contener varios nombres de archivo de destino si el miembro fFlags especifica FOF_MULTIDESTFILES.
  • Empaqueta varios nombres en la cadena pTo de la misma manera que para pFrom.
  • Use rutas de acceso completas. El uso de rutas de acceso relativas no está prohibido, pero puede tener resultados impredecibles.

fFlags

Tipo: FILEOP_FLAGS

Marcas que controlan la operación de archivo. Este miembro puede tomar una combinación de las marcas siguientes.

FOF_ALLOWUNDO

Conserve la información de deshacer, si es posible.

Antes de Windows Vista, las operaciones solo se podían deshacer desde el mismo proceso que realizó la operación original.

En Windows Vista y sistemas posteriores, el ámbito de la deshacer es una sesión de usuario. Cualquier proceso que se ejecute en la sesión de usuario puede deshacer otra operación. El estado de deshacer se mantiene en el proceso de Explorer.exe y, siempre que se ejecute ese proceso, puede coordinar las funciones de deshacer.

Si el parámetro de archivo de origen no contiene nombres de archivo y ruta de acceso completos, se omite esta marca.

FOF_CONFIRMMOUSE

No se usa.

FOF_FILESONLY

Realice la operación solo en archivos (no en carpetas) si se especifica un nombre de archivo comodín (.).

FOF_MULTIDESTFILES

El miembro pTo especifica varios archivos de destino (uno para cada archivo de origen en pFrom) en lugar de un directorio donde se van a depositar todos los archivos de origen.

FOF_NOCONFIRMATION

Responda con Sí a Todo para cualquier cuadro de diálogo que se muestre.

FOF_NOCONFIRMMKDIR

No pida al usuario que confirme la creación de un nuevo directorio si la operación requiere que se cree una.

FOF_NO_CONNECTED_ELEMENTS

Versión 5.0. No mueva archivos conectados como un grupo. Mueva solo los archivos especificados.

FOF_NOCOPYSECURITYATTRIBS

Versión 4.71. No copie los atributos de seguridad del archivo. El archivo de destino recibe los atributos de seguridad de su nueva carpeta.

FOF_NOERRORUI

No muestre un cuadro de diálogo al usuario si se produce un error.

FOF_NORECURSEREPARSE

No se usa.

FOF_NORECURSION

Realice solo la operación en el directorio local. No funcione de forma recursiva en subdirectorios, que es el comportamiento predeterminado.

FOF_NO_UI

Windows Vista. Realice la operación de forma silenciosa, sin presentar ninguna interfaz de usuario al usuario. Esto equivale a FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.

FOF_RENAMEONCOLLISION

Asigne al archivo un nombre nuevo en una operación de traslado, copia o cambio de nombre si ya existe un archivo con el nombre de destino en el destino.

FOF_SILENT

No mostrar un cuadro de diálogo de progreso.

FOF_SIMPLEPROGRESS

Mostrar un cuadro de diálogo de progreso, pero no mostrar nombres de archivo individuales mientras están operados.

FOF_WANTMAPPINGHANDLE

Si se especifica FOF_RENAMEONCOLLISION y se cambia el nombre de los archivos, asigne un objeto de asignación de nombres que contenga sus nombres antiguos y nuevos al miembro hNameMappings . Este objeto debe liberarse mediante SHFreeNameMappings cuando ya no sea necesario.

FOF_WANTNUKEWARNING

Versión 5.0. Envíe una advertencia si un archivo se destruye permanentemente durante una operación de eliminación en lugar de reciclarse. Esta marca invalida parcialmente FOF_NOCONFIRMATION.

fAnyOperationsAborted

Tipo: BOOL

Cuando se devuelve la función, este miembro contiene TRUE si se anuló alguna operación de archivo antes de que se completaran; de lo contrario, FALSE. El usuario puede anular manualmente una operación a través de la interfaz de usuario o el sistema puede anularla de forma silenciosa si se establecieron las marcas de FOF_NOERRORUI o FOF_NOCONFIRMATION.

hNameMappings

Tipo: LPVOID

Cuando se devuelve la función, este miembro contiene un identificador de un objeto de asignación de nombres que contiene los nombres antiguos y nuevos de los archivos cuyo nombre ha cambiado. Este miembro solo se usa si el miembro fFlags incluye la marca FOF_WANTMAPPINGHANDLE . Consulte Comentarios para obtener más detalles.

lpszProgressTitle

Tipo: PCTSTR

Puntero al título de un cuadro de diálogo de progreso. Se trata de una cadena terminada en NULL. Este miembro solo se usa si fFlags incluye la marca FOF_SIMPLEPROGRESS .

Comentarios

Importante Debe asegurarse de que las rutas de acceso de origen y destino están terminadas de doble null. Una cadena normal termina en un solo carácter NULL. Si pasa ese valor en los miembros de origen o destino, la función no se dará cuenta cuando haya alcanzado el final de la cadena y seguirá leyendo en la memoria hasta que llegue a un valor null doble aleatorio. Esto puede provocar al menos una saturación del búfer y, posiblemente, la eliminación no deseada de datos no relacionados.
 
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";

Para tener en cuenta los dos caracteres NULOs de terminación, asegúrese de crear búferes lo suficientemente grandes como para contener MAX_PATH (que normalmente incluye el carácter NULO de terminación único) más 1.

No se puede sobreestado que las rutas de acceso siempre deben ser rutas de acceso completas. Si los miembros pFrom o pTo no son nombres completos, los directorios actuales se toman de la unidad actual global y la configuración del directorio, tal y como administran las funciones GetCurrentDirectory y SetCurrentDirectory .

Si no proporciona una ruta de acceso completa, los siguientes hechos se vuelven pertinentes:

  • La falta de una ruta de acceso antes de un nombre de archivo no indica a SHFileOperation que este archivo reside en la raíz del directorio actual.
  • SHFileOperation no usa la variable de entorno PATH para determinar una ruta de acceso válida.
  • No se puede confiar en SHFileOperation para usar el directorio que es el directorio actual cuando comienza a ejecutarse. El directorio que se ve como el directorio actual está en todo el proceso y se puede cambiar de otro subproceso mientras se ejecuta la operación. Si eso fuera a suceder, los resultados de SHFileOperation serían impredecibles.

Si pFrom se establece en un nombre de archivo sin una ruta de acceso completa, al eliminar el archivo con FO_DELETE no se mueve a la Papelera de reciclaje, aunque se establezca la marca FOF_ALLOWUNDO . Debe proporcionar una ruta de acceso completa para eliminar el archivo en la Papelera de reciclaje.

Se produce un error en SHFileOperation en cualquier ruta de acceso con el prefijo "\?".

Hay dos versiones de esta estructura, una versión ANSI (SHFILEOPSTRUCTA) y una versión Unicode (SHFILEOPSTRUCTW). La versión Unicode es idéntica a la versión ANSI, salvo que se usan cadenas de caracteres anchos (LPCWSTR) en lugar de cadenas de caracteres ANSI (LPCSTR). En Windows 98 y versiones anteriores, solo se admite la versión ANSI. En Microsoft Windows NT 4.0 y versiones posteriores, se admiten las versiones ANSI y Unicode de esta estructura. SHFILEOPSTRUCTW y SHFILEOPTSTRUCTA nunca deben utilizarse directamente; la estructura adecuada se vuelve a definir como SHFILEOPSTRUCT por el precompilador en función de si la aplicación se compila para ANSI o Unicode.

SHNAMEMAPPING tiene versiones ANSI y Unicode similares. En el caso de las aplicaciones ANSI, hNameMappings apunta a un valor int seguido de una matriz de estructuras SHNAMEMAPPING anSI. En el caso de las aplicaciones Unicode, hNameMappings apunta a un valor int seguido de una matriz de estructuras SHNAMEMAPPING de Unicode. Sin embargo, en Microsoft Windows NT 4.0 y versiones posteriores, SHFileOperationsiempre devuelve un identificador a un conjunto Unicode de estructuras SHNAMEMAPPING . Si quiere que las aplicaciones funcionen con todas las versiones de Windows, la aplicación debe emplear código condicional para tratar las asignaciones de nombres. Por ejemplo:

x = SHFileOperation(&shop);

if (fWin9x) 
    HandleAnsiNameMappings(shop.hNameMappings);
else 
    HandleUnicodeNameMappings(shop.hNameMappings);

Trate hNameMappings como puntero a una estructura cuyos miembros son un valor UINT seguido de un puntero a una matriz de estructuras SHNAMEMAPPING , como se muestra en su declaración:

struct HANDLETOMAPPINGS 
{
    UINT              uNumberOfMappings;  // Number of mappings in the array.
    LPSHNAMEMAPPING   lpSHNameMapping;    // Pointer to the array of mappings.
};

El valor UINT indica el número de estructuras SHNAMEMAPPING de la matriz. Cada estructura SHNAMEMAPPING contiene la ruta de acceso antigua y nueva para uno de los archivos cuyo nombre ha cambiado.

Nota El identificador debe liberarse con SHFreeNameMappings.
 

Nota:

El encabezado shellapi.h define SHFILEOPSTRUCT 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

   
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows 2000 Server [solo aplicaciones de escritorio]
Encabezado shellapi.h