Compartir a través de

Función CfConvertToPlaceholder (cfapi.h)

  • Artículo

Convierte un archivo o directorio no de marcador de posición existente en un árbol de directorio raíz de sincronización en un marcador de posición. Esto resulta útil, por ejemplo, después de que aparezca un nuevo archivo o directorio local en un cliente y el proveedor de sincronización haya terminado de sincronizarlo con la nube. Tenga en cuenta que no hay parámetros para pasar metadatos del sistema de archivos (marcas de tiempo, tamaño de archivo, etc.); se toman textualmente del archivo local.

Sintaxis

HRESULT CfConvertToPlaceholder(
  [in]                HANDLE           FileHandle,
  [in, optional]      LPCVOID          FileIdentity,
  [in]                DWORD            FileIdentityLength,
  [in]                CF_CONVERT_FLAGS ConvertFlags,
  [out, optional]     USN              *ConvertUsn,
  [in, out, optional] LPOVERLAPPED     Overlapped
);

Parámetros

[in] FileHandle

Identificador del archivo o directorio que se va a convertir.

[in, optional] FileIdentity

Búfer de modo de usuario que contiene la información opaca del archivo o directorio proporcionada por el autor de la llamada. Opcional si el autor de la llamada no está deshidrando el archivo al mismo tiempo, o si el autor de la llamada está convirtiendo un directorio. FileIdentity se devuelve al proveedor de sincronización en todas las devoluciones de llamada. No se puede superar el tamaño de 4 KB.

[in] FileIdentityLength

Longitud, en bytes, de FileIdentity.

[in] ConvertFlags

Marcas de conversión de marcador de posición. ConvertFlags se puede establecer en los valores siguientes:

Marca Descripción
CF_CONVERT_FLAG_MARK_IN_SYNC Si se especifica, la plataforma marca el marcador de posición convertido como sincronizado con la nube tras una conversión correcta del archivo.
CF_CONVERT_FLAG_DEHYDRATE Esto solo es aplicable a los archivos. Cuando se especifica, la plataforma deshidrata el archivo después de convertirlo en un marcador de posición correctamente. 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_CONVERT_FLAG_ENABLE_ON_DEMAND_POPULATION Esto solo se aplica a los directorios. Cuando se especifica, marca el directorio de marcador de posición convertido parcialmente rellenado de forma que cualquier acceso futuro a él dará lugar a una devolución de llamada FETCH_PLACEHOLDERS enviada al proveedor de sincronización.
CF_CONVERT_FLAG_ALWAYS_FULL Esto solo es efectivo en los archivos de marcador de posición. Una vez que un archivo se convierte en un marcador de posición con esta marca, el marcador de posición se marca siempre lleno. Cualquier intento de deshidratar este marcador de posición producirá un error en el código de error ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.
CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE Cuando se especifica, la plataforma permite que un motor de sincronización convierta de forma atómica un marcador de posición de archivos no en la nube (con otra etiqueta o datos de reanálisis) en un marcador de posición de archivos en la nube. Tenga en cuenta que la API normalmente produce un error en la conversión de cualquier archivo que no sea de marcador de posición en un marcador de posición.

Combinación (CF_CONVERT_FLAG_FORCE_CONVERT_TO_CLOUD_FILE | CF_CONVERT_FLAG_DEHYDRATE) es especialmente útil en escenarios de migración cuando determinados proveedores migran desde otra plataforma a la plataforma de archivos en la nube y pretenden convertir marcadores de posición hidratados en la plataforma anterior a marcadores de posición deshidratados en la plataforma de archivos en la nube de forma atómica. Solo se debe pasar esta marca para convertir marcadores de posición completos en marcadores de posición de archivos en la nube. Si la plataforma anterior implementa archivos completos como archivos normales que no son de marcador de posición, esta marca no es necesaria. Si se pasa esta marca en un directorio, también se convierten directorios en archivos en la nube, aunque la marca DEHYDRATE no se aplica a los directorios.

Incluso cuando la directiva CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_TO_UNRESTRICTED se especificó con CfRegisterSyncRoot, solo los procesos que se han registrado o conectado a la raíz de sincronización de archivos en la nube pueden especificar esta marca.

Nota: La marca solo se admite si el PlatformVersion.IntegrationNumber obtenido de CfGetPlatformInfo es 0x500 o superior.

[out, optional] ConvertUsn

Cuando se especifica, este es el valor usn final después de realizar acciones de conversión.

[in, out, optional] Overlapped

Cuando se especifica y se combina con un FileHandle asincrónico, Superpuesta permite a la plataforma realizar la llamada cfConvertToPlaceholder 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 haya creado el identificador.

Valor devuelto

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

Comentarios

En el caso del 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 con los interbloqueos adecuados (a través de CfOpenFileWithOplock) en lugar de usar un identificador de no uso compartido.

Para convertir un marcador de posición:

  • El archivo o directorio que se va a convertir debe estar contenido 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 produjo un error en la llamada con 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 la llamada con error hrESULT(ERROR_CLOUD_FILE_PINNED).
  • Si se solicita la deshidratación, el marcador de posición debe estar sincronizado o la llamada con error HRESULT(ERROR_CLOUD_FILE_NOT_IN_SYNC).
  • El autor de la llamada debe tener WRITE_DATA o WRITE_DAC acceso al archivo o directorio que se va a convertir. 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) al usar superpuesta de forma asincrónica, el autor de la llamada puede esperar mediante 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

GetOverlappedResult