Cycle de vie de l’instance de virtualisation

L’application fournisseur gère une ou plusieurs instances de virtualisation. Chaque instance de virtualisation passe par quatre étapes de son cycle de vie :

1. Création
2. Démarrage
3. Runtime
4. Shutdown

Notez qu’après l’arrêt d’une virtualisation instance le fournisseur n’a pas besoin de le recréer pour le réutiliser. Il peut simplement le redémarrer.

Remarque : cette section présente des exemples d’API ProjFS. Chaque exemple est destiné à illustrer l’utilisation de base de l’API. Pour obtenir de la documentation sur les options inutilisées dans ces exemples, consultez les informations de référence sur l’API ProjFS.

Création d’une racine de virtualisation

Avant qu’un fournisseur puisse démarrer la virtualisation instance qui projett des éléments dans le système de fichiers local, il doit créer la racine de virtualisation. La racine de virtualisation est le répertoire sous lequel le fournisseur projette une arborescence de répertoires et de fichiers.

Pour créer une racine de virtualisation, le fournisseur doit :

1. Créez un répertoire pour servir de racine de virtualisation.

   Le fournisseur crée un répertoire pour servir de racine de virtualisation à l’aide, par exemple , de 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. Créez un ID de instance de virtualisation.

   Chaque instance de virtualisation a un ID unique appelé ID de instance de virtualisation. Le système utilise cette valeur pour identifier à quelle virtualisation instance son contenu sont associés.

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

3. Marquez le nouveau répertoire comme racine de virtualisation.

   Le fournisseur appelle PrjMarkDirectoryAsPlaceholder pour marquer le nouveau répertoire comme racine de virtualisation et l’affecter à l’instance de virtualisation.

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

Le fournisseur ne doit créer la racine de virtualisation qu’une seule fois pour chaque instance de virtualisation. Une fois qu’une racine a été créée, ses instance associées peuvent être démarrées et arrêtées à plusieurs reprises sans recréer la racine.

Démarrage d’un instance de virtualisation

Une fois la racine de virtualisation créée, le fournisseur doit démarrer la virtualisation instance. Cela indique à ProjFS que le fournisseur est prêt à recevoir des rappels et à fournir des données.

Pour démarrer la virtualisation instance le fournisseur doit :

1. Configurez la table de rappel.

   ProjFS communique avec le fournisseur en appelant des routines de rappel implémentées par le fournisseur. Le fournisseur remplit un struct PRJ_CALLBACKS avec des pointeurs vers ses routines de rappel.

   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. Démarrer l'instance.

   Le fournisseur appelle PrjStartVirtualizing pour démarrer la virtualisation instance.

   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;
   }
   

   Le paramètre instanceHandle de PrjStartVirtualizing retourne un handle à l’instance de virtualisation. Le fournisseur utilise ce handle lors de l’appel d’autres API ProjFS.

Runtime de virtualisation instance

Une fois l’appel à PrjStartVirtualizing retourné, ProjFS appelle les routines de rappel du fournisseur en réponse aux opérations du système de fichiers dans le instance de virtualisation. Pour plus d’informations sur la façon dont le fournisseur peut gérer diverses opérations de système de fichiers, reportez-vous aux sections suivantes :

• Énumération de fichiers et de répertoires
• Envoi de données de fichier
• Notifications d’opération du système de fichiers
• Gestion des modifications d’affichage

Arrêt d’un instance de virtualisation

Pour signaler à ProjFS que le fournisseur souhaite cesser de recevoir des rappels et de fournir des données, le fournisseur doit arrêter la virtualisation instance. Pour ce faire, le fournisseur appelle PrjStopVirtualizing, en lui passant le handle à l’instance de virtualisation qu’il a reçu de l’appel à PrjStartVirtualizing.

PrjStopVirtualizing(instanceHandle);

Notez que tant que cet appel n’est pas retourné, ProjFS peut continuer à appeler les routines de rappel du fournisseur.