Ciclo de vida da instância de virtualização

O aplicativo provedor mantém uma ou mais instâncias de virtualização. Cada instância de virtualização passa por quatro estágios em seu ciclo de vida:

1. Criação
2. Inicialização
3. Runtime
4. Shutdown

Observe que, depois de desligar uma instância de virtualização, o provedor não precisa recriá-la para reutilizá-la. Ele pode simplesmente iniciá-lo novamente.

Observação: esta seção mostra exemplos de APIs do ProjFS. Cada exemplo destina-se a ilustrar o uso básico da API. Para obter a documentação das opções não usadas nestes exemplos, consulte a referência da API do ProjFS.

Criando uma raiz de virtualização

Antes que um provedor possa iniciar a instância de virtualização que projetará itens no sistema de arquivos local, ele deve criar a raiz de virtualização. A raiz de virtualização é o diretório no qual o provedor projeta uma árvore de diretórios e arquivos.

Para criar uma raiz de virtualização, o provedor deve:

1. Crie um diretório para servir como a raiz de virtualização.

   O provedor cria um diretório para servir como a raiz de virtualização usando, por exemplo , CreateDirectory:

   HRESULT hr;
   const wchar_t* rootName = LR"(C:\virtRoot)";
   if (!CreateDirectoryW(rootName, nullptr))
   {
       hr = HRESULT_FROM_WIN32(GetLastError());
       wprintf(L"Failed to create virtualization root (0x%08x)\n", hr);
       return;
   }
   

2. Crie uma ID de instância de virtualização.

   Cada instância de virtualização tem uma ID exclusiva chamada ID da instância de virtualização. O sistema usa esse valor para identificar a qual instância de virtualização seu conteúdo está associado.

   GUID instanceId;
   hr = CoCreateGuid(&instanceId);
   if (FAILED(hr))
   {
       wprintf(L"Failed to create instance ID (0x%08x)\n", hr);
       return;
   }
   

3. Marque o novo diretório como a raiz de virtualização.

   O provedor chama PrjMarkDirectoryAsPlaceholder para marcar o novo diretório como a raiz de virtualização e atribuí-lo à instância de virtualização.

   hr = PrjMarkDirectoryAsPlaceholder(rootName,
                                      nullptr,
                                      nullptr,
                                      &instanceId);
   if (FAILED(hr))
   {
       wprintf(L"Failed to mark virtualization root (0x%08x)\n", hr);
       return;
   }
   

O provedor só precisa criar a raiz de virtualização uma vez para cada instância de virtualização. Depois que uma raiz tiver sido criada, sua instância associada poderá ser iniciada e interrompida repetidamente sem recriar a raiz.

Iniciando uma instância de virtualização

Depois que a raiz de virtualização tiver sido criada, o provedor deverá iniciar a instância de virtualização. Isso sinaliza ao ProjFS que o provedor está pronto para receber retornos de chamada e fornecer dados.

Para iniciar a instância de virtualização, o provedor deve:

1. Configure a tabela de retorno de chamada.

   O ProjFS se comunica com o provedor invocando rotinas de retorno de chamada implementadas pelo provedor. O provedor preenche um struct PRJ_CALLBACKS com ponteiros para suas rotinas de retorno de chamada.

   PRJ_CALLBACKS callbackTable;
   
   // Supply required callbacks.
   callbackTable.StartDirectoryEnumerationCallback = MyStartEnumCallback;
   callbackTable.EndDirectoryEnumerationCallback = MyEndEnumCallback;
   callbackTable.GetDirectoryEnumerationCallback = MyGetEnumCallback;
   callbackTable.GetPlaceholderInfoCallback = MyGetPlaceholderInfoCallback;
   callbackTable.GetFileDataCallback = MyGetFileDataCallback;
   
   // The rest of the callbacks are optional.
   callbackTable.QueryFileNameCallback = nullptr;
   callbackTable.NotificationCallback = nullptr;
   callbackTable.CancelCommandCallback = nullptr;
   

2. Inicie a instância.

   O provedor chama PrjStartVirtualizing para iniciar a instância de virtualização.

   PRJ_NAMESPACE_VIRTUALIZATION_CONTEXT instanceHandle;
   hr = PrjStartVirtualizing(rootName,
                             &callbackTable,
                             nullptr,
                             nullptr,
                             &instanceHandle);
   if (FAILED(hr))
   {
       wprintf(L"Failed to start the virtualization instance (0x%08x)\n", hr);
       return;
   }
   

   O parâmetro instanceHandle de PrjStartVirtualizing retorna um identificador para a instância de virtualização. O provedor usa esse identificador ao chamar outras APIs ProjFS.

Runtime da instância de virtualização

Depois que a chamada para PrjStartVirtualizing retornar, o ProjFS invocará as rotinas de retorno de chamada do provedor em resposta às operações do sistema de arquivos na instância de virtualização. Para obter informações sobre como o provedor pode lidar com várias operações do sistema de arquivos, consulte as seguintes seções:

• Enumerar arquivos e diretórios
• Fornecer dados de arquivo
• Notificações de operação do sistema de arquivos
• Manipulando alterações de exibição

Desligar uma instância de virtualização

Para sinalizar ao ProjFS que o provedor deseja parar de receber retornos de chamada e fornecer dados, o provedor deve interromper a instância de virtualização. Para fazer isso, o provedor chama PrjStopVirtualizing, passando o identificador para a instância de virtualização que recebeu da chamada para PrjStartVirtualizing.

PrjStopVirtualizing(instanceHandle);

Observe que, até que essa chamada retorne, o ProjFS pode continuar a invocar as rotinas de retorno de chamada do provedor.