ILockBytes::LockRegion メソッド (objidl.h)

[アーティクル]
08/25/2023

LockRegion メソッドは、バイト配列内の指定されたバイト範囲へのアクセスを制限します。

構文

HRESULT LockRegion(
  [in] ULARGE_INTEGER libOffset,
  [in] ULARGE_INTEGER cb,
  [in] DWORD          dwLockType
);

パラメーター

[in] libOffset

範囲の先頭のバイトオフセットを指定します。

[in] cb

制限する範囲の長さをバイト単位で指定します。

[in] dwLockType

範囲へのアクセスで要求される制限の種類を指定します。このパラメーターは、LOCKTYPE 列挙の値の 1 つを使用します。

戻り値

このメソッドは、これらの値のいずれかを返すことができます。

リターンコード	説明
S_OK	指定したバイト範囲がロックされました。
STG_E_INVALIDFUNCTION	ロックはまったくサポートされていないか、要求された特定の種類のロックがサポートされていません。
STG_E_ACCESSDENIED	呼び出し元に十分なアクセス許可がないため、または別の呼び出し元がファイルを開いてロックしているため、アクセスが拒否されました。
STG_E_LOCKVIOLATION	別の呼び出し元がファイルを開いてロックしているため、アクセスが拒否されました。
STG_E_INVALIDHANDLE	基になるファイルが途中で閉じられたか、正しいフロッピーディスクが無効なフロッピーディスクに置き換えられました。

注釈

ILockBytes::LockRegion は、指定されたバイト範囲へのアクセスを制限します。リージョンがロックされると、他のユーザーが制限された範囲にアクセスしようとすると、STG_E_ACCESSDENIED エラーで失敗する必要があります。

バイト範囲は、バイト配列の現在の末尾を超えて拡張できます。配列の末尾を超えてロックすることは、実際にはバイト配列の一部であるデータを変更することなく、バイト配列オブジェクトの異なるインスタンス間の通信方法として役立ちます。たとえば、複合ファイルの ILockBytes の実装では、アクセス制御の手段として、特定のロックされた領域を使用して現在付与されているアクセス許可を示す、配列の現在の末尾を超えるロックに依存する可能性があります。

dwLockType パラメーターは、LOCKTYPE 列挙の値を使用して、3 種類のロックのいずれかを指定します。型は次のとおりです。他のライターを除外するためのロック、他のリーダーまたはライターを除外するためのロック、および 1 人の要求者のみが特定の範囲のロックを取得できるようにするロック。通常、この 3 番目の種類のロックは、他の 2 つのロックの種類の 1 つのエイリアスであり、実装者が他の動作も追加できます。特定のバイト配列は、最初の 2 つの型のいずれか、またはその両方をサポートする場合があります。

特定の ILockBytes 実装でサポートされているロックの種類を確認するには、ILockBytes::Stat の呼び出しによって返される STATSTG 構造体の grfLocksSupported メンバーを調べることができます。

ILockBytes::LockRegion でロックされているリージョンは、後で libOffset、cb、dwLockType パラメーターとまったく同じ値で ILockBytes::UnlockRegion を呼び出すことによって、明示的にロック解除する必要があります。ストリームが解放される前に、リージョンのロックを解除する必要があります。隣接する 2 つのリージョンを個別にロックしてから、1 回のロック解除呼び出しでロックを解除することはできません。

呼び出し元へのメモ

サポートされているロックの種類は省略可能であり、 ILockBytes の実装によって異なる場合があるため、STG_E_INVALIDFUNCTION エラーを処理するコードを指定する必要があります。

実装者へのメモ

このメソッドのサポートは、 ILockBytes 実装の上に構築されたストレージオブジェクトの使用方法によって異なります。バイト配列の基になるストレージデバイスでいつでも 1 つのストレージオブジェクトのみを開くことができることがわかっている場合、 ILockBytes の実装ではロックをサポートする必要はありません。ただし、ストレージオブジェクトの複数の同時オープンが可能な場合は、それらを調整するためにリージョンロックが必要です。

LockRegion 実装では、ロックの種類のすべて、一部、またはなしをサポートすることを選択できます。サポートされていないロックの種類の場合、実装は STG_E_INVALIDFUNCTIONを返す必要があります。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリ \|UWP アプリ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリ \|UWP アプリ]
対象プラットフォーム	Windows
ヘッダー	objidl.h
Library	Uuid.lib
[DLL]	Ole32.dll