Función CfUpdatePlaceholder (cfapi.h)

Esta API cambia las características de un marcador de posición existente. El uso más probable de esta API es cuando se ha modificado un archivo en la nube y el proveedor de sincronización desea incorporar los efectos de esa modificación en un marcador de posición. Para admitir este escenario, el autor de la llamada puede pasar nuevos metadatos del sistema de archivos (marcas de tiempo, tamaño de archivo, etc.) para aplicar o un nuevo blob FileIdentity .

Sintaxis

HRESULT CfUpdatePlaceholder(
  [in]                HANDLE               FileHandle,
  [in, optional]      const CF_FS_METADATA *FsMetadata,
  [in, optional]      LPCVOID              FileIdentity,
  [in]                DWORD                FileIdentityLength,
  [in, optional]      const CF_FILE_RANGE  *DehydrateRangeArray,
  [in]                DWORD                DehydrateRangeCount,
  [in]                CF_UPDATE_FLAGS      UpdateFlags,
  [in, out, optional] USN                  *UpdateUsn,
  [in, out, optional] LPOVERLAPPED         Overlapped
);

Parámetros

[in] FileHandle

FileHandle es un identificador del archivo o directorio cuyos metadatos se van a actualizar. En el caso de un archivo, el autor de la llamada debe adquirir un identificador exclusivo para el archivo si también pretende deshidratar el archivo al mismo tiempo o pueden producirse daños en los datos. Para minimizar el impacto en las aplicaciones de usuario, se recomienda encarecidamente que el autor de la llamada obtenga la exclusividad mediante los interbloqueos adecuados (a través de CfOpenFileWithOplock) en lugar de usar un identificador de nada compartido.

[in, optional] FsMetadata

FsMetadata contiene metadatos del sistema de archivos sobre el marcador de posición que se va a actualizar, incluidas todas las marcas de tiempo, los atributos de archivo y el tamaño de archivo (opcional para los directorios). Este campo es opcional. Si no se proporciona, todos estos campos permanecen intactos después de la llamada.

• Un 0 valor en un campo de marca de tiempo (CreationTime, LastAccessTime, LastWriteTime y ChangeTime) significa que no hay ningún cambio en la marca de tiempo actual del archivo.
• Un 0 valor de FileAttributes significa que no hay ningún cambio en los atributos de archivo actuales del archivo.
• No hay ningún valor especial en FileSize; un 0 valor de FileSize trunca el tamaño del archivo en 0.

[in, optional] FileIdentity

FileIdentity es un búfer en modo de usuario que contiene la información opaca del archivo o directorio proporcionada por el autor de la llamada. El blob FileIdentity no debe superar los 4 KB de tamaño. FileIdentity se devuelve al proveedor de sincronización en todas las devoluciones de llamada. Esto es opcional si no se necesita una actualización o si el autor de la llamada desea quitar el blob FileIdentity del marcador de posición que se va a actualizar.

[in] FileIdentityLength

Longitud, en bytes, de FileIdentity.

[in, optional] DehydrateRangeArray

Esta matriz especifica intervalos del marcador de posición existente que ya no se considerará válido después de la actualización.

El uso más sencillo de este parámetro es pasar un único intervalo, indicando a la plataforma que el intervalo de bytes completo de datos ahora no es válido. Un uso más complejo de este parámetro es proporcionar una serie de intervalos discretos que se considerarán no válidos. Esto implica que el proveedor de sincronización puede distinguir los cambios en un nivel de subproceso. Todos los desplazamientos y longitudes deben estar alineados PAGE_SIZE . La plataforma garantizará que todos los intervalos especificados se deshidraten como parte de la actualización. Si se produce un error en la deshidratación de cualquier intervalo, se producirá un error en la API en lugar de provocar un error en el contenido del archivo rasgado.

Nota

Pasar un único intervalo con Offset 0 y Length CF_EOF invalidará todo el archivo: esto tiene el mismo efecto que pasar la marca CF_UPDATE_FLAG_DEHYDRATE en su lugar. Además, pasar CF_UPDATE_FLAG_DEHYDRATE hace que DehydrateRangeArray se quite silenciosamente.

[in] DehydrateRangeCount

Recuento de una serie de particiones discretas de DehydrateRangeArray de datos de marcador de posición.

[in] UpdateFlags

Actualizar marcas para marcadores de posición. UpdateFlags se puede establecer en los valores siguientes:

Marca	Descripción
CF_UPDATE_FLAG_VERIFY_IN_SYNC	Se producirá un error en la actualización si el atributo IN_SYNC no está establecido actualmente en el marcador de posición. Esto es para evitar que una carrera entre la sincronización de cambios desde la nube hasta un marcador de posición local y el flujo de datos del marcador de posición se modifique localmente.
CF_UPDATE_FLAG_MARK_IN_SYNC	La plataforma marca el marcador de posición como sincronizado tras una operación correcta de marcador de posición de actualización.
CF_UPDATE_FLAG_DEHYDRATE	Solo se aplica a los archivos. Cuando se especifica, la plataforma deshidrata el archivo después de actualizar correctamente el marcador de posición. El autor de la llamada debe adquirir un identificador exclusivo al especificar esta marca o daños en los datos. Tenga en cuenta que la plataforma no valida la exclusividad del identificador.
CF_UPDATE_FLAG_ENABLE_ON_DEMAND_POPULATION	Solo se aplica a directorios. Cuando se especifica, marca el directorio de marcador de posición actualizado parcialmente rellenado de modo que cualquier acceso futuro a él dará lugar a una devolución de llamada FETCH_PLACEHOLDERS enviada al proveedor de sincronización.
CF_UPDATE_FLAG_DISABLE_ON_DEMAND_POPULATION	Solo se aplica a directorios. Cuando se especifica, marca el directorio de marcador de posición actualizado completamente rellenado de forma que cualquier acceso futuro a él se controlará mediante la plataforma sin devoluciones de llamada al proveedor de sincronización.
CF_UPDATE_FLAG_REMOVE_FILE_IDENTITY	FileIdentity y FileIdentityLength se omiten y la plataforma quitará el blob de identidad de archivo existente en el marcador de posición tras una llamada de actualización correcta.
CF_UPDATE_FLAG_CLEAR_IN_SYNC	La plataforma marca el marcador de posición como no sincronizado tras una operación correcta de marcador de posición de actualización.
CF_UPDATE_FLAG_REMOVE_PROPERTY	La plataforma quita todas las propiedades extrinsicas existentes en el marcador de posición.
CF_UPDATE_FLAG_PASSTHROUGH_FS_METADATA	La plataforma pasa CF_FS_METADATA al sistema de archivos sin ningún filtrado; de lo contrario, la plataforma omite la configuración de los campos cuyo valor es 0.
CF_UPDATE_FLAG_ALWAYS_FULL	Efectivo solo en los archivos de marcador de posición. Cuando se especifica, el marcador de posición que se va a actualizar se marca siempre lleno. Una vez hidratado, cualquier intento de deshidratar este archivo de marcador de posición producirá un error en el código de error ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
CF_UPDATE_FLAG_ALLOW_PARTIAL	Efectivo solo en los archivos de marcador de posición. Cuando se especifica, el estado siempre completo en un archivo de marcador de posición, si está presente, se borra, lo que permite volver a deshidratarlo. No es válido especificar esta marca junto con CF_UPDATE_FLAG_ALWAYS_FULL y el código de error ERROR_CLOUD_FILE_INVALID_REQUEST se devolverá como resultado.

[in, out, optional] UpdateUsn

En la entrada, UpdateUsn indica a la plataforma que solo realice la actualización si el archivo sigue teniendo el mismo valor USN que el pasado. Esto sirve para un propósito similar a CF_UPDATE_FLAG_VERIFY_IN_SYNC , pero también abarca los cambios de metadatos locales. Pasar un puntero a un valor USN de 0 en la entrada es el mismo que pasar un NULL puntero.

Cuando se devuelve, UpdateUsn recibe el valor de USN final después de realizar acciones de actualización.

[in, out, optional] Overlapped

Cuando se especifica y se combina con un FileHandle asincrónico, Superpuesta permite a la plataforma realizar la llamada cfUpdatePlaceholder de forma asincrónica. Consulte los comentarios para obtener más detalles.

Si no se especifica, la plataforma realizará la llamada API de forma sincrónica, independientemente de cómo se creó el identificador.

Valor devuelto

Si esta función se ejecuta correctamente, devuelve S_OK. De lo contrario, devuelve un código de error de HRESULT.

Comentarios

Para actualizar un marcador de posición:

• El marcador de posición que se va a actualizar debe estar incluido en un árbol raíz de sincronización registrado; puede ser el propio directorio raíz de sincronización o cualquier directorio descendiente; de lo contrario, se producirá un error en la llamada a HRESULT(ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT).
• Si se solicita la deshidratación, la raíz de sincronización debe registrarse con una directiva de hidratación válida que no sea CF_HYDRATION_POLICY_ALWAYS_FULL; de lo contrario, se producirá un error en la llamada a HRESULT(ERROR_CLOUD_FILE_NOT_SUPPORTED).
• Si se solicita la deshidratación, el marcador de posición no se debe anclar localmente o se producirá un error en la llamada a HRESULT(ERROR_CLOUD_FILE_PINNED).
• Si se solicita la deshidratación, el marcador de posición debe estar sincronizado o se producirá un error en la llamada a HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
• El autor de la llamada debe tener WRITE_DATA o WRITE_DAC acceso al marcador de posición que se va a actualizar. De lo contrario, se producirá un error en la operación con HRESULT(ERROR_CLOUD_FILE_ACCESS_DENIED).

Si la API devuelve HRESULT_FROM_WIN32(ERROR_IO_PENDING) cuando se usa superpuesta de forma asincrónica, el autor de la llamada puede esperar con GetOverlappedResult.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 10, versión 1709 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2016 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	cfapi.h
Library	CldApi.lib
Archivo DLL	CldApi.dll

Consulte también

CfOpenFileWithOplock

CF_UPDATE_FLAGS