Função CfCreatePlaceholders (cfapi.h)

Cria um ou mais novos arquivos de espaço reservado ou diretórios em uma árvore de diretório raiz de sincronização.

Sintaxe

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

Caminho para o diretório local no qual os espaços reservados são criados. Tenha o seguinte em mente ao especificar o caminho:

• Esse caminho deve estar contido em uma árvore raiz de sincronização registrada. Pode ser o próprio diretório raiz de sincronização ou qualquer diretório descendente. Caso contrário, a chamada falhará com STATUS_CLOUD_FILE_NOT_UNDER_SYNC_ROOT.
• A raiz de sincronização deve ser registrada com uma política de hidratação válida que não seja CF_HYDRATION_POLICY_ALWAYS_FULL, caso contrário, a chamada falhará com STATUS_CLOUD_FILE_NOT_SUPPORTED.
• O chamador deve ter acesso WRITE_DATA ou WRITE_DAC ao diretório base no qual o espaço reservado está prestes a ser criado. Caso contrário, a operação falhará com STATUS_CLOUD_FILE_ACCESS_DENIED.

[in, out] PlaceholderArray

Na criação bem-sucedida, o PlaceholderArray contém o valor final de USN e uma STATUS_OK mensagem. No retorno, essa matriz contém um valor HRESULT que descreve se o espaço reservado foi criado ou não. PlaceholderArray aponta para uma matriz de espaços reservados a serem criados, em relação a BaseDirectoryPath. Cada entrada na matriz inclui os seguintes campos:

• RelativeFileName é o nome do espaço reservado filho, arquivo e diretório, a ser criado.
• FsMetadata contém metadados do sistema de arquivos sobre o espaço reservado a ser criado, incluindo todos os carimbos de data/hora, atributos de arquivo e tamanho do arquivo (opcional para diretórios).
• FileIdentity e FileIdentityLength descrevem um buffer de modo de usuário que contém as informações opacas de arquivo fornecidas pelo provedor de sincronização. O blob FileIdentity não deve exceder CF_PLACEHOLDER_MAX_FILE_IDENTITY_LENGTH (definido como 4 KB) de tamanho. FileIdentity é passado de volta para o provedor de sincronização em todos os retornos de chamada. Esse é um campo obrigatório para arquivos.

Um provedor de sincronização pode escolher os seguintes sinalizadores ou uma combinação deles por espaço reservado:

• CF_PLACEHOLDER_CREATE_FLAG_DISABLE_ON_DEMAND_POPULATION - Esse sinalizador é aplicável somente a um diretório de espaço reservado filho. Quando o sinalizador estiver presente, o diretório de espaço reservado filho recém-criado será considerado com todos os seus filhos presentes localmente, portanto, acessá-lo no futuro não disparará nenhum retorno de chamada FETCH_PLACEHOLDERS nele. Quando o sinalizador estiver ausente, o diretório de espaço reservado recém-criado será considerado parcial e o acesso futuro disparará FETCH_PLACEHOLDERS.
• CF_PLACEHOLDER_CREATE_FLAG_MARK_IN_SYNC – esse sinalizador é aplicável a arquivos de espaço reservado e diretórios. Quando esse sinalizador estiver presente, o espaço reservado recém-criado será marcado como em sincronia como parte da operação de TRANSFER_PLACEHOLDERS .
• CF_PLACEHOLDER_CREATE_FLAG_ALWAYS_FULL – esse sinalizador é imposto somente em um arquivo de espaço reservado. Ele pode ser definido em um diretório de espaço reservado, mas não tem efeito. Quando esse sinalizador estiver presente, o espaço reservado recém-criado será marcado como sempre cheio. Depois de hidratado, qualquer tentativa de desidratar esse espaço reservado de arquivo falhará com o código de erro ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED.

[in] PlaceholderCount

A contagem de espaços reservados no PlaceholderArray.

[in] CreateFlags

Sinalizadores para configurar a criação de um espaço reservado. CreateFlags pode ser definido com os seguintes valores:

• CF_CREATE_FLAG_NONE é o modo padrão em que a API processa todas as entradas na matriz mesmo quando erros são encontrados.
• CF_CREATE_FLAG_STOP_ON_ERROR faz com que a API retorne imediatamente se a criação de um espaço reservado falhar. Nesse caso, a API retorna o código de falha.

[out] EntriesProcessed

O número de entradas processadas, incluindo entradas com falha. Se CF_CREATE_FLAG_STOP_ON_ERROR não tiver sido especificado em CreateFlags, a API retornará o primeiro código de falha encontrado, mas continuará processando o maior número possível de entradas; o chamador deve inspecionar a matriz para ver qual(s) criação(s) de espaço reservado falhou.

Retornar valor

Se essa função for bem-sucedida, ela retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Comentários

É preferível criar um espaço reservado com essa função em comparação com a criação de um novo arquivo com CreateFile e convertê-lo em um espaço reservado com CfConvertToPlaceholder; para eficiência e porque elimina a janela de tempo em que o arquivo não é um espaço reservado. A função também pode criar vários arquivos ou diretórios em um lote, o que também pode ser mais eficiente.

Essa função é útil ao executar uma sincronização inicial de arquivos ou diretórios da nuvem até o cliente ou ao sincronizar um arquivo ou diretório único recém-criado da nuvem.

Requisitos

Confira também

CreateFile

CfConvertToPlaceholder