Compartir a través de

Estructura SHFILEOPSTRUCTA (shellapi.h)

  • Artículo

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

Nota A partir de Windows Vista, se recomienda usar la interfaz IFileOperation sobre 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 del 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 a la ubicación especificada en el miembro pTo de .

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 de

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 estándar MS-DOS, 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 imprevisibles.

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 mediante un único carácter NULL. El último nombre de archivo finaliza con un doble carácter NULL ("\0\0") para indicar el final del búfer.

pTo

Tipo: PCZZTSTR de

Nota Esta cadena debe terminar con un valor double-null.
 
Puntero al nombre del 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 con doble null y se controla de la misma manera. Sin embargo, pTo debe cumplir las siguientes especificaciones:

  • No se admiten 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 de 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 fFlags miembro especifica FOF_MULTIDESTFILES.
  • Empaqueta varios nombres en la cadena de pTo de la misma manera que para pFrom.
  • Use rutas de acceso completas. No se prohíbe el uso de rutas de acceso relativas, 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

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

Antes de Windows Vista, las operaciones solo se podían deshacer del 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 Todos los 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 opere 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 nuevo nombre en una operación de movimiento, 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

Muestra un cuadro de diálogo de progreso, pero no muestra nombres de archivo individuales cuando 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 se necesite.

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 de

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

hNameMappings

Tipo: LPVOID de

Cuando la función devuelve, este miembro contiene un identificador para 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 información.

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 de FOF_SIMPLEPROGRESS.

Observaciones

Importante Debe asegurarse de que las rutas de acceso de origen y destino estén terminadas con valores double-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 sobrestatar que las rutas de acceso siempre deben ser rutas de acceso completas. Si los miembros de pFrom o pTo son nombres no calificados, los directorios actuales se toman de la configuración de directorio y unidad actual global administradas por 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 que un nombre de archivo no indique que SHFileOperation que este archivo reside en la raíz del directorio actual.
  • La variable de entorno PATH no la usa SHFileOperation para determinar una ruta de acceso válida.
  • SHFileOperation no se puede confiar en usar el directorio que es el directorio actual cuando comienza a ejecutarse. El directorio visto como el directorio actual está en todo el proceso y se puede cambiar de otro subproceso mientras se ejecuta la operación. Si fuera así, los resultados de SHFileOperation serían impredecibles.

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

SHFileOperation produce un error 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 las cadenas de caracteres anchos (LPCWSTR) se usan 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. Para las aplicaciones ANSI, hNameMappings apunta a un int seguido de una matriz de estructuras SHNAMEMAPPING de ANSI . Para las aplicaciones Unicode, hNameMappings apunta a un int seguido de una matriz de estructuras shNAMEMAPPING 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 de 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 Conventions for Function Prototypes.

Requisitos

Requisito Valor
cliente mínimo admitido Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido Windows 2000 Server [solo aplicaciones de escritorio]
encabezado de shellapi.h