Жизненный цикл экземпляра виртуализации

Приложение поставщика поддерживает один или несколько экземпляров виртуализации. Каждый экземпляр виртуализации проходит четыре этапа жизненного цикла:

1. Создание
2. Запуск
3. Среда выполнения
4. Завершить работу

Обратите внимание, что после завершения работы экземпляра виртуализации поставщику не нужно повторно создавать его для повторного использования. Он может просто запустить его снова.

Примечание. В этом разделе приведены примеры API ProjFS. Каждый пример призван проиллюстрировать базовое использование API. Документацию по параметрам, не используемым в этих примерах, см. в справочнике по API ProjFS.

Создание корневого каталога виртуализации

Прежде чем поставщик сможет запустить экземпляр виртуализации, который проецируют элементы в локальную файловую систему, он должен создать корневой каталог виртуализации. Корневой каталог виртуализации — это каталог, в котором поставщик проецируется дерево каталогов и файлов.

Чтобы создать корневой каталог виртуализации, поставщик должен:

1. Создайте каталог, который будет служить корнем виртуализации.

   Поставщик создает каталог, который будет служить корнем виртуализации, используя, например , 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. Создайте идентификатор экземпляра виртуализации.

   Каждый экземпляр виртуализации имеет уникальный идентификатор, который называется идентификатором экземпляра виртуализации. Система использует это значение, чтобы определить, с каким экземпляром виртуализации связано ее содержимое.

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

3. Пометьте новый каталог как корневой каталог виртуализации.

   Поставщик вызывает PrjMarkDirectoryAsPlaceholder , чтобы пометить новый каталог как корневой каталог виртуализации и назначить его экземпляру виртуализации.

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

Поставщику необходимо создать корневой каталог виртуализации только один раз для каждого экземпляра виртуализации. После создания корневого каталога связанный с ним экземпляр можно многократно запускать и останавливать без повторного создания корня.

Запуск экземпляра виртуализации

После создания корневого каталога виртуализации поставщик должен запустить экземпляр виртуализации. Это сигнализирует ProjFS о том, что поставщик готов к приему обратных вызовов и предоставлению данных.

Чтобы запустить экземпляр виртуализации, поставщик должен:

1. Настройте таблицу обратного вызова.

   ProjFS взаимодействует с поставщиком, вызывая процедуры обратного вызова, реализованные поставщиком. Поставщик заполняет структуру PRJ_CALLBACKS указателями на процедуры обратного вызова.

   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. Запустите экземпляр.

   Поставщик вызывает PrjStartVirtualizing для запуска экземпляра виртуализации.

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

   Параметр instanceHandleprjStartVirtualizing возвращает дескриптор экземпляру виртуализации. Поставщик использует этот дескриптор при вызове других API ProjFS.

Среда выполнения экземпляра виртуализации

После возврата вызова PrjStartVirtualizing ProjFS будет вызывать подпрограммы обратного вызова поставщика в ответ на операции файловой системы в экземпляре виртуализации. Сведения о том, как поставщик может обрабатывать различные операции файловой системы, см. в следующих разделах:

• Перечисление файлов и каталогов
• Предоставление данных файлов
• Уведомления об операциях файловой системы
• Обработка изменений представления

Завершение работы экземпляра виртуализации

Чтобы сообщить ProjFS о том, что поставщик хочет прекратить прием обратных вызовов и предоставление данных, поставщик должен остановить экземпляр виртуализации. Для этого поставщик вызывает PrjStopVirtualizing, передав ему дескриптор экземпляру виртуализации, который он получил от вызова PrjStartVirtualizing.

PrjStopVirtualizing(instanceHandle);

Обратите внимание, что до тех пор, пока этот вызов не будет возвращен, ProjFS может продолжать вызывать процедуры обратного вызова поставщика.