Función CfCreatePlaceholders (cfapi.h)

Crea uno o varios archivos o directorios de marcador de posición nuevos en un árbol de directorios raíz de sincronización.

Sintaxis

HRESULT CfCreatePlaceholders(
  [in]      LPCWSTR                    BaseDirectoryPath,
  [in, out] CF_PLACEHOLDER_CREATE_INFO *PlaceholderArray,
  [in]      DWORD                      PlaceholderCount,
  [in]      CF_CREATE_FLAGS            CreateFlags,
  [out]     PDWORD                     EntriesProcessed
);

Parámetros

[in] BaseDirectoryPath

Ruta de acceso al directorio local en el que se crean los marcadores de posición. Tenga en cuenta lo siguiente al especificar la ruta de acceso:

• Esta ruta de acceso debe estar contenida 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 con STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT.
• 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 con STATUS_CLOUD_FILE_NOT_SUPPORTED.
• El autor de la llamada debe tener WRITE_DATA o WRITE_DAC acceso al directorio base en el que se va a crear el marcador de posición. De lo contrario, se producirá un error en la operación con STATUS_CLOUD_FILE_ACCESS_DENIED.

[in, out] PlaceholderArray

Al crearse correctamente, PlaceholderArray contiene el valor de USN final y un STATUS_OK mensaje. Al devolver, esta matriz contiene un valor HRESULT que describe si el marcador de posición se creó o no. PlaceholderArray apunta a una matriz de marcadores de posición que se van a crear, en relación con BaseDirectoryPath. Cada entrada de la matriz incluye los siguientes campos:

• RelativeFileName es el nombre del marcador de posición secundario, tanto el archivo como el directorio, que se va a crear.
• FsMetadata contiene metadatos del sistema de archivos sobre el marcador de posición que se va a crear, incluidas todas las marcas de tiempo, los atributos de archivo y el tamaño de archivo (opcional para directorios).
• FileIdentity y FileIdentityLength describen un búfer de modo de usuario que contiene la información de archivo opaca proporcionada por el proveedor de sincronización. El blob FileIdentity no debe superar CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (definido en 4 KB) de tamaño. FileIdentity se devuelve al proveedor de sincronización en todas las devoluciones de llamada. Este es un campo obligatorio para los archivos.

Un proveedor de sincronización puede elegir las siguientes marcas o una combinación de ellas por marcador de posición:

• CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION : esta marca solo se aplica a un directorio de marcador de posición secundario. Cuando la marca está presente, el directorio de marcador de posición secundario recién creado se considera que todos sus elementos secundarios están presentes localmente, por lo que acceder a él en el futuro no desencadenará ninguna devolución de llamada FETCH_PLACEHOLDERS en ella. Cuando la marca está ausente, el directorio de marcador de posición recién creado se considera parcial y el acceso futuro se desencadenará FETCH_PLACEHOLDERS.
• CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC : esta marca es aplicable a los directorios y los archivos de marcador de posición. Cuando esta marca esté presente, el marcador de posición recién creado se marcará como sincronizado como parte de la operación de TRANSFER_PLACEHOLDERS .
• CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL : esta marca solo se aplica en un archivo de marcador de posición. Se puede establecer en un directorio de marcador de posición, pero no tiene ningún efecto. Cuando esta marca esté presente, el marcador de posición recién creado se marcará como siempre lleno. Una vez hidratado, cualquier intento de deshidratar este marcador de posición de archivo producirá un error en el código de error ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.

[in] PlaceholderCount

Recuento de marcadores de posición en PlaceholderArray.

[in] CreateFlags

Marcas para configurar la creación de un marcador de posición. CreateFlags se puede establecer en los valores siguientes:

• CF_CREATE_FLAG_NONE es el modo predeterminado en el que la API procesa todas las entradas de la matriz incluso cuando se encuentran errores.
• CF_CREATE_FLAG_STOP_ON_ERROR hace que la API devuelva inmediatamente si se produce un error en la creación de un marcador de posición. En ese caso, la API devuelve el código de error.

[out] EntriesProcessed

Número de entradas procesadas, incluidas las entradas con errores. Si no se especificó CF_CREATE_FLAG_STOP_ON_ERROR en CreateFlags, la API devuelve el primer código de error encontrado, pero continúa procesando tantas entradas como sea posible; Después, el autor de la llamada debe inspeccionar la matriz para ver qué creaciones de marcador de posición no se pudieron crear.

Valor devuelto

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

Comentarios

Se prefiere crear un marcador de posición con esta función en comparación con la creación de un nuevo archivo con CreateFile y, a continuación, convertirlo en un marcador de posición con CfConvertToPlaceholder; tanto por eficiencia como porque elimina la ventana de tiempo en la que el archivo no es un marcador de posición. La función también puede crear varios archivos o directorios en un lote, lo que también puede ser más eficaz.

Esta función es útil al realizar una sincronización inicial de archivos o directorios desde la nube hasta el cliente, o al sincronizar un único archivo o directorio recién creado desde la nube.

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

CreateFile

CfConvertToPlaceholder