Función CfRegisterSyncRoot (cfapi.h)

Artículo
04/06/2023

Realiza un registro raíz de sincronización única, lo que permite a un proveedor de sincronización reclamar una estructura de árbol de directorio completa, con raíz en SyncRootPath, como su propio para administrar.

Sintaxis

HRESULT CfRegisterSyncRoot(
  [in] LPCWSTR                    SyncRootPath,
  [in] const CF_SYNC_REGISTRATION *Registration,
  [in] const CF_SYNC_POLICIES     *Policies,
  [in] CF_REGISTER_FLAGS          RegisterFlags
);

Parámetros

[in] SyncRootPath

Ruta de acceso a la raíz de sincronización que se va a registrar.

[in] Registration

Contiene información sobre el proveedor de sincronización y la raíz de sincronización que se va a registrar.

ProviderName y ProviderVersion son cadenas orientadas al usuario final con una longitud máxima de 255 caracteres cada una.

SyncRootIdentity y FileIdentity son opcionales y cuando no se proporcionan sus longitudes de búfer correspondientes también deben establecerse 0 en. Son una manera de que un proveedor de sincronización asocie de forma persistente datos arbitrarios con una raíz de sincronización.

La plataforma devolverá SyncRootIdentity al proveedor de sincronización en las devoluciones de llamada al proveedor de sincronización. El blob de FileIdentity raíz de sincronización solo se proporcionará cuando el asunto de la devolución de llamada sea la propia raíz de sincronización.

Esta instalación se proporciona únicamente para la comodidad del proveedor de sincronización y ambos blobs no tienen ningún significado especial fuera del proveedor de sincronización.

La longitud máxima permitida de FileIdentity es de 4 KB y la longitud máxima permitida de SyncRootIdentity es de 64 KB. Se produce un error en la API con ERROR_INVALID_PARAMETER cuando se supera cualquier longitud máxima.

ProviderId es un GUID diseñado para identificar un proveedor de sincronización específico. Es opcional. Si no se proporciona, la plataforma genera un GUID mediante el hash MD5 de la cadena ProviderName . La información solo se usa para la telemetría de modo que la plataforma pueda correlacionar mejor las actividades del mismo proveedor de sincronización de forma más eficaz y precisa, incluso si el proveedor de sincronización registra raíces de sincronización con diferentes cadenas ProviderName . Se recomienda que un proveedor de sincronización proporcione siempre el mismo GUID para todas las versiones de sus productos de sincronización. Sin embargo, los proveedores de sincronización pueden elegir diferentes cadenas ProviderName para la mejor experiencia del usuario.

[in] Policies

Las directivas de la raíz de sincronización que se van a registrar.

[in] RegisterFlags

Marcas para registrar raíces de sincronización anteriores y nuevas.

Marca	Descripción
CF_REGISTER_FLAG_UPDATE	Un proveedor de sincronización puede pasar CF_REGISTER_FLAG_UPDATE para volver a registrar las identidades y directivas raíz de sincronización registradas anteriormente.
CF_REGISTER_FLAG_DISABLE_ON_DEMAND_POPULATION_ON_ROOT	El comportamiento de rellenado de carpetas o directorios a petición se controla globalmente mediante la directiva de rellenado. Esta marca permite que un proveedor de sincronización opte por no participar en el comportamiento de rellenado a petición solo para la raíz de sincronización mientras mantiene el rellenado a petición para todos los demás directorios en la raíz de sincronización. Esto resulta útil cuando el proveedor de sincronización desea rellenar previamente los archivos o directorios secundarios inmediatos de la raíz de sincronización.
CF_REGISTER_FLAG_MARK_IN_SYNC_ON_ROOT	Esta marca permite que un proveedor de sincronización marque la raíz de sincronización que se va a registrar simultáneamente en el momento del registro. La alternativa es llamar a CfSetInSyncState en la raíz de sincronización más adelante.

Valor devuelto

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

Comentarios

Esto se puede usar en una hora de instalación del proveedor de sincronización, la primera vez configurada para un usuario individual o cuando un usuario configura otra raíz de sincronización (si se admite este escenario).

Nota

No se permite superponer dos árboles raíz de sincronización. Dado que el sistema de archivos prohíbe los vínculos físicos de directorio, la única manera de que se superpongan dos raíces de sincronización es si tienen una relación directa antecesor/descendiente. La plataforma es responsable de recordar de forma persistente todas las raíces de sincronización registradas en un volumen determinado y no realizar ningún intento de crear raíces de sincronización superpuestas.

Un proveedor de sincronización debe tener WRITE_DATA o WRITE_DAC acceso a la raíz de sincronización que se va a registrar o se producirá un error en el registro con ERROR_CLOUD_FILE_ACCESS_DENIED.

El proveedor de sincronización debe proporcionar un registro que contenga varias identidades del propio proveedor de sincronización y la raíz de sincronización que se va a registrar, un conjunto de directivas que la plataforma usa para ajustar su comportamiento por raíz de sincronización y un conjunto de marcas de registro que permiten un control más preciso de la operación de registro por parte del proveedor de sincronización.

A menos que se indique explícitamente como opcional, todos los campos son obligatorios y no se proporcionan, se producirá un error en la llamada API con un error de parámetro no válido.

Todas las estructuras en las que se esperan extensiones futuras comienzan con un campo StructSize . El autor de la llamada es responsable de la contabilidad precisa del tamaño de la estructura.

Actualmente, la plataforma admite cinco tipos de directivas:

Directiva de hidratación

La directiva de hidratación permite a un proveedor de sincronización controlar cómo la plataforma debe hidratar los archivos de marcador de posición. Consta de una directiva principal y un conjunto de modificadores de directiva.

La directiva de hidratación principal tiene cuatro valores diferentes:

Directiva	Descripción
ALWAYS_FULL	Se producirá un error en la plataforma (con ERROR_CLOUD_FILE_INVALID_REQUEST) cualquier operación de marcador de posición que pudiera dar lugar a un marcador de posición no totalmente hidratado, que incluye CfCreatePlaceholders, CfDehydratePlaceholder, CfUpdatePlaceholder con la opción de deshidratación y CfConvertToPlaceholder con la opción de deshidratación.
FULL	La plataforma permitirá que un marcador de posición se deshidrate. Cuando la plataforma detecta el acceso a un marcador de posición deshidratado, se asegurará de que el contenido completo del marcador de posición esté disponible localmente antes de completar la solicitud de E/S del usuario, incluso si la solicitud solo solicita 1 byte.
PROGRESIVA	La plataforma permitirá que un marcador de posición se deshidrate. Cuando la plataforma detecta el acceso a un marcador de posición deshidratado, completará la solicitud de E/S de usuario en cuanto determine que se reciben datos suficientes del proveedor de sincronización. Sin embargo, la plataforma promete continuar solicitando el contenido restante en el marcador de posición del proveedor de sincronización en segundo plano hasta que el contenido completo del marcador de posición esté disponible localmente o se cierre el último identificador de usuario en el marcador de posición. Nota: Es posible que los proveedores de sincronización que opten por PROGRESSIVE no asuman que las devoluciones de llamada de hidratación llegan secuencialmente desde el desplazamiento `0`. Es decir, se espera que los proveedores de sincronización con la directiva PROGRESIVA controle las búsquedas aleatorias en el marcador de posición.
PARTIAL	Esta política es muy similar a PROGRESIVA, siendo la única diferencia la falta de hidratación continua en segundo plano.

Actualmente se admiten tres modificadores de directiva. En general, los modificadores se pueden mezclar y coincidir con cualquier directiva principal y otros modificadores de directiva, siempre y cuando la combinación no sea autoconstante.

Modificador	Descripción
VALIDATION_REQUIRED	Este modificador de directiva ofrece dos garantías para un proveedor de sincronización. En primer lugar, garantiza que los datos devueltos por el proveedor de sincronización siempre se conservan en el disco antes de que se devuelvan a la aplicación de usuario. En segundo lugar, permite al proveedor de sincronización recuperar los mismos datos que ha devuelto anteriormente a la plataforma y validar su integridad. Solo tras una confirmación correcta de la integridad por parte del proveedor de sincronización, la plataforma completará la solicitud de E/S del usuario. Este modificador ayuda a admitir la integridad de los datos de un extremo a otro a costa de E/S de disco adicional.
STREAMING_ALLOWED	Este modificador de directiva concede a la plataforma el permiso para no almacenar ningún dato devuelto por un proveedor de sincronización en discos locales. Este modificador de directiva se excluye mutuamente con VALIDATION_REQUIRED. Se produce un error en la API con ERROR_INVALID_PARAMETER cuando se especifican ambas marcas.
AUTO_DEHYDRATION_ALLOWED	Este modificador de directiva concede a la plataforma el permiso para deshidratar los marcadores de posición de archivos en la nube sincronizados sin la ayuda de los proveedores de sincronización. Sin esta marca, la plataforma no puede llamar directamente a CfDehydratePlaceholder . En su lugar, la única manera admitida de deshidratar un marcador de posición de archivo en la nube es borrar el atributo anclado del archivo y establecer el atributo desanclado del archivo y, a continuación, el motor de sincronización realizará la deshidratación real de forma asincrónica después de recibir la notificación de cambio de directorio en los dos atributos. Cuando se especifica esta marca, la plataforma podrá invocar a CfDehydratePlaceholder directamente en cualquier marcador de posición de archivo en la nube sincronizado. Se recomienda que los proveedores de sincronización admitan la deshidratación automática.

Directiva de rellenado

La directiva de rellenado permite a un proveedor de sincronización controlar cómo la plataforma debe crear el espacio de nombres de marcador de posición (tanto directorios como archivos). Actualmente hay tres directivas principales sin modificadores definidos:

Directiva	Descripción
ALWAYS_FULL	La plataforma supone que el espacio de nombres completo siempre está disponible localmente. Nunca reenviará ninguna solicitud de enumeración de directorios al proveedor de sincronización.
FULL	Cuando la plataforma detecta el acceso en un directorio no rellenado completamente, solicitará que el proveedor de sincronización devuelva todas las entradas del directorio antes de completar la solicitud del usuario.
PARTIAL	Cuando la plataforma detecta el acceso en un directorio no rellenado completamente, solo solicitará las entradas requeridas por la aplicación de usuario desde el proveedor de sincronización.

Directiva de seguimiento de InSync

La directiva InSync permite que un proveedor de sincronización controle cuándo la plataforma debe borrar el estado de sincronización en un marcador de posición. Además de borrar siempre la sincronización en cualquier modificación de datos, la plataforma actualmente puede borrar la sincronización en los cambios de cualquier combinación de tres atributos de archivo (ReadOnly, System y Hidden) y dos veces de archivo (CreateTime y LastWriteTime). Estas directivas se pueden aplicar a archivos y directorios por separado.

Directiva de vínculo físico

De forma predeterminada, la plataforma no permite crear vínculos duros en ningún marcador de posición. Sin embargo, los proveedores de sincronización que son capaces de controlar vínculos duros pueden indicar a la plataforma que habilite la compatibilidad a través de la directiva ALLOWED . Con esta directiva, las aplicaciones pueden crear tantos vínculos duros como el sistema de archivos admita siempre que los vínculos estén en la misma raíz de sincronización o en ninguna raíz de sincronización. La plataforma obligará a hidratar un marcador de posición cuando se introduzca el primer vínculo de raíz fuera de sincronización y revertirá un marcador de posición al archivo normal cuando se quite su último vínculo raíz en sincronización. Se producirá un error en la creación de vínculos físicos que no sea compatible con la directiva STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS. Las operaciones de marcador de posición que no son compatibles con la directiva también se producirán con STATUS_CLOUD_FILES_INCOMPATIBLE_HARDLINKS.

Directiva de administración de marcadores de posición

De forma predeterminada, solo un proveedor de sincronización puede realizar operaciones de administración de marcadores de posición en una raíz de sincronización. Los procesos del proveedor de no sincronización solo pueden realizar operaciones de administración de marcadores de posición si la raíz de sincronización está inactiva, es decir, cuando ningún proveedor de sincronización no está conectado a la raíz de sincronización. Estas directivas, cuando están habilitadas, permiten que los procesos del proveedor que no son de sincronización realicen operaciones de administración de marcadores de posición respectivas en una raíz de sincronización activa. CF_PLACEHOLDER_MANAGEMENT_POLICY_DEFAULT es la directiva predeterminada que permite que solo un proveedor de sincronización conectado realice las operaciones de administración de marcadores de posición. Las siguientes directivas se pueden especificar en cualquier combinación:

Directiva	Descripción
CF_PLACEHOLDER_MANAGEMENT_POLICY_CREATE_UNRESTRICTED	Cuando se especifica esta directiva durante el registro, cualquier proceso puede crear un marcador de posición dentro de una raíz de sincronización activa llamando a CfCreatePlaceholders.
CF_PLACEHOLDER_MANAGEMENT_POLICY_CONVERT_UNRESTRICTED	Cuando se especifica esta directiva durante el registro, cualquier proceso puede convertir un archivo o un directorio dentro de una raíz de sincronización activa en un marcador de posición llamando a CfConvertToPlaceholder.
CF_PLACEHOLDER_MANAGEMENT_POLICY_UPDATE_UNRESTRICTED	Cuando se especifica esta directiva durante el registro, cualquier proceso puede actualizar un marcador de posición dentro de una raíz de sincronización activa llamando a CfUpdatePlaceholder.

Nota

Estas marcas solo se admiten si PlatformVersion.IntegrationNumber obtenido de CfGetPlatformInfo es 0x310 o superior.

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