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
ライターが Freeze イベント通知を受信するアプリケーション レベルを示すVSS_APPLICATION_LEVEL列挙値。
このパラメーターの既定値はVSS_APP_FRONT_ENDです。
[in] dwTimeoutFreeze
ライターが Freeze イベント通知を受信してから 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 がセーフ モードであったか、または設定されていたため、非アクティブでした。 |
|
呼び出し元は管理者ではありません。 |
|
パラメーター値の 1 つが無効です。 |
|
呼び出し元がメモリやその他のシステム リソースを使い切れている。 |
|
予期しないエラー。 エラー コードは、エラー ログ ファイルに記録されます。 詳細については、「 VSS でのイベントとエラーの処理」を参照してください。
Windows Server 2008、Windows Vista、Windows Server 2003、Windows XP: この値は、Windows Server 2008 R2 と Windows 7 まではサポートされません。 代わりに E_UNEXPECTED が使用されます。 |
注釈
InitializeEx メソッドは、dwMajorVersion パラメーターと dwMinorVersion パラメーターを除き、Initialize メソッドと同じです。 ライターが InitializeEx の代わりに Initialize を使用している場合、ライター バージョンは IVssExamineWriterMetadataEx2::GetVersion メソッドによって 0.0 (メジャー バージョン = 0、マイナー バージョン = 0) として報告されます。
dwMajorVersion パラメーターと dwMinorVersion パラメーターは、次の VSS 規則に従ってライターのメジャー バージョン番号とマイナー バージョン番号を指定するために使用されます。
- ライターが Windows XP 以降に変更された場合、または Windows Vista の新しい場合は、バージョン番号に 1.0 以上を指定する必要があります。
- ライターのマイナー バージョン番号は、ライターのリリース バージョンに、ライターと要求元との対話に影響を与える軽微な変更が含まれるたびに 1 ずつインクリメントする必要があります。 たとえば、ライター QFE または Service Pack のファイル仕様を修正すると、マイナー バージョン番号のインクリメントが正当化されます。 ただし、ライターのベータ版またはリリース候補バージョン間の変更は、マイナー バージョン番号の変更を正当化しません。
- ライターのメジャー バージョン番号は、リリースされたバージョンのライターに大幅な変更が含まれるたびに 1 ずつインクリメントする必要があります。 たとえば、新しいバージョンのライターでバックアップされたデータを以前のバージョンのライターを使用して復元できない場合は、新しいライターのメジャー バージョン番号をインクリメントする必要があります。
- メジャー バージョン番号がインクリメントされるたびに、マイナー バージョン番号を 0 にリセットする必要があります。
VSS は、ライター アプリケーションの各インスタンスに一意のライター インスタンス ID を割り当てます。 システム上に複数のインスタンスが同時に存在する場合 (たとえば、システム上で複数の SQL サーバーが実行されている場合)、各ライターは、ライター クラス ID とそのライター インスタンス ID の組み合わせによって一意に識別されます。
wszWriterInstanceName パラメーターを使用すると、マルチインスタンス ライターは、各ライター インスタンスの永続的な名前を人間が読み取り可能な文字列として指定できます。 この名前は、システム上のライターのすべてのインスタンスで一意である必要があります。 ライターに複数のインスタンスがあり、復元イベントが必要な場合は、このパラメーターに NULL 以外の文字列を指定する必要があります。 VSS はインスタンス名を使用して、マルチインスタンス ライターを正しく復元します。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | vswriter.h (Vss.h、VsWriter.h を含む) |
| Library | VssApi.lib |