共用方式為

虛擬化實例生命週期

  • 發行項

提供者應用程式會維護一或多個虛擬化實例。 每個虛擬化實例在其生命週期中都會經歷四個階段：

  1. 建立
  2. 啟動
  3. 執行階段
  4. Shutdown

請注意，關閉虛擬化實例之後，提供者不需要重新建立它來重複使用它。 它可以直接重新開機。

注意：本節顯示 ProjFS API 的範例。 每個範例都是為了說明基本的 API 使用方式。 如需這些範例中未使用之選項的檔，請參閱 ProjFS API 參考。

建立虛擬化根目錄

提供者必須先建立虛擬化根目錄，提供者才能啟動將專案投影到本機檔案系統的虛擬化實例。 虛擬化根目錄是提供者在其中投影目錄和檔案樹狀目錄的目錄。

若要建立虛擬化根目錄，提供者必須：

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

    PrjStartVirtualizing的 instanceHandle 參數會傳回虛擬化實例的控制碼。 提供者會在呼叫其他 ProjFS API 時使用此控制碼。

虛擬化實例執行時間

一旦呼叫 PrjStartVirtualizing傳回之後，ProjFS 會叫用提供者的回呼常式，以回應虛擬化實例中的檔案系統作業。 如需提供者如何處理各種檔案系統作業的資訊，請參閱下列各節：

關閉虛擬化實例

若要向 ProjFS 表示提供者想要停止接收回呼和提供資料，提供者必須停止虛擬化實例。 若要這樣做，提供者會呼叫 PrjStopVirtualizing，並將控制碼傳遞給從 呼叫 PrjStartVirtualizing收到的虛擬化實例。

PrjStopVirtualizing(instanceHandle);

請注意，在呼叫傳回之前，ProjFS 可能會繼續叫用提供者的回呼常式。