CVssWriterEx::InitializeEx 方法 (vswriter.h)
初始化 CVssWriterEx 物件,並允許寫入器應用程式與 VSS 互動。 不同於 Initialize 方法,InitializeEx 方法可讓呼叫端指定寫入器版本資訊。
InitializeEx 是由 CVssWriterEx 基類實作的公用方法。
寫入器必須呼叫 Initialize 或 InitializeEx,但不能同時呼叫兩者。
語法
HRESULT InitializeEx(
[in] VSS_ID WriterId,
[in] LPCWSTR wszWriterName,
[in] DWORD dwMajorVersion,
[in] DWORD dwMinorVersion,
[in] VSS_USAGE_TYPE ut,
[in] VSS_SOURCE_TYPE st,
[in] VSS_APPLICATION_LEVEL nLevel,
[in] DWORD dwTimeoutFreeze,
[in] VSS_ALTERNATE_WRITER_STATE aws,
[in] bool bIOThrottlingOnly,
[in] LPCWSTR wszWriterInstanceName
);
參數
[in] WriterId
寫入器類別的全域唯一標識碼 (GUID) 。
[in] wszWriterName
包含寫入器名稱的 Null 終止寬字元字串。 此字串未當地語系化。
[in] dwMajorVersion
寫入器應用程式的主要版本。 如需詳細資訊,請參閱<備註>一節。
[in] dwMinorVersion
寫入器應用程式的次要版本。 如需詳細資訊,請參閱<備註>一節。
[in] ut
VSS_USAGE_TYPE列舉值,指出寫入器所管理的數據如何在主系統上使用。
[in] st
VSS_SOURCE_TYPE列舉值,指出寫入器所管理之數據類型。
[in] nLevel
VSS_APPLICATION_LEVEL列舉值,指出寫入器接收Freeze事件通知的應用程式層級。
此參數的預設值為 VSS_APP_FRONT_END。
[in] dwTimeoutFreeze
寫入器接收 凍結 事件通知和從 VSS 收到相符 的 Thaw 事件通知之間的允許時間上限,以毫秒為單位。 逾時到期之後,會自動呼叫寫入器的 OnAbort 方法。
此參數的預設值為 60000。
[in] aws
VSS_ALTERNATE_WRITER_STATE列舉值,指出寫入器是否有相關聯的替代寫入器。
此參數的預設值為 VSS_AWS_NO_ALTERNATE_WRITER。 呼叫端不應該覆寫這個預設值。 這個參數保留給未來使用。
[in] bIOThrottlingOnly
如果啟用 I/O 節流方法,請將此參數設定為 true ,否則為 false 。
此參數的預設值為 false。 呼叫端不應該覆寫這個預設值。 這個參數保留給未來使用。
[in] wszWriterInstanceName
包含寫入器實例名稱的 Null 終止寬字元字串。
此參數的預設值為 NULL。 如果寫入器有多個實例,而且需要還原事件,則此參數是必要的,而且不能是 NULL。 如需詳細資訊,請參閱接下來的<備註>一節。
傳回值
以下是此方法的有效傳回碼。
值 | 意義 |
---|---|
|
寫入器物件已成功初始化。 |
|
無法初始化寫入器物件;VSS 寫入器基礎結構處於非使用中狀態,因為 Windows 處於安全模式或設定中。 |
|
呼叫端不是系統管理員。 |
|
其中一個參數值無效。 |
|
呼叫端記憶體不足或其他系統資源。 |
|
非預期的錯誤。 錯誤碼會記錄在錯誤記錄檔中。 如需詳細資訊,請參閱 VSS 下的事件和錯誤處理。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP: 在 Windows Server 2008 R2 和 Windows 7 之前,不支援此值。 改用E_UNEXPECTED。 |
備註
InitializeEx 方法與 Initialize 方法相同,但 dwMajorVersion 和 dwMinorVersion 參數除外。 如果寫入器使用 Initialize 而不是 InitializeEx,則寫入器版本會回報為 0.0 (主要版本 = 0,次要版本 = 0) IVssExriterMetadataEx2::GetVersion 方法。
dwMajorVersion 和 dwMinorVersion 參數是用來根據下列 VSS 慣例來指定寫入器主要和次要版本號碼:
- 如果寫入器自 Windows XP 之後變更,或為 Windows Vista 的新功能,它應該為其版本號碼指定 1.0 或更高版本。
- 每當發行的寫入器版本包含影響寫入器與要求者的互動時,寫入器的次要版本號碼應該遞增一個。 例如,寫入器 QFE 或 Service Pack 中檔案規格的修正會證明遞增次要版本號碼。 不過,在 Beta 版或發行候選版的寫入器版本之間變更,並不會證明變更次要版本號碼。
- 每當發行的寫入器版本包含重大變更時,寫入器的主要版本號碼應該遞增一個。 例如,如果使用舊版寫入器還原以新版寫入器備份的數據,則新寫入器的主要版本號碼應該遞增。
- 每當主要版本號碼遞增時,次要版本號碼應該重設為零。
VSS 會將唯一的寫入器實例識別碼指派給寫入器應用程式的每個實例。 例如,如果系統上同時存在多個實例, (例如,如果多個SQL 伺服器在系統) 上執行,則每個寫入器都會以寫入器類別標識碼及其寫入器實例標識符的組合來唯一識別。
wszWriterInstanceName 參數可讓多實例寫入器將每個寫入器實例的持續性名稱指定為人類可讀取的字串。 在系統上寫入器的所有實例中,此名稱必須是唯一的。 如果寫入器有多個實例,而且需要還原事件,則必須指定此參數的非 NULL 字串。 VSS 會使用實例名稱來正確還原多實例寫入器。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows Vista [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2008 [僅限傳統型應用程式] |
目標平台 | Windows |
標頭 | vswriter.h (包括 Vss.h、VsWriter.h) |
程式庫 | VssApi.lib |