IByteBuffer::LockRegion method

[The LockRegion method is available for use in the operating systems specified in the Requirements section. It is not available for use in Windows Server 2003 with Service Pack 1 (SP1) and later, Windows Vista, Windows Server 2008, and subsequent versions of the operating system. The IStream interface provides similar functionality.]

The LockRegion method restricts access to a specified range of bytes in the buffer object.

Syntax

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

Parameters

libOffset [in]

Integer that specifies the byte offset for the beginning of the range.

cb [in]

Integer that specifies the length of the range, in bytes, to be restricted.

dwLockType [in]

Specifies the restrictions being requested on accessing the range. This can be one of the values in the following table.

Value	Meaning
LOCK_WRITE	The specified range of bytes can be opened and read any number of times, but writing to the locked range is prohibited except for the owner that was granted this lock.
LOCK_EXCLUSIVE	Writing to the specified range of bytes is prohibited except for the owner that was granted this lock.
LOCK_ONLYONCE	If this lock is granted, no other LOCK_ONLYONCE lock can be obtained on the range. Usually this lock type is an alias for some other lock type. Thus, specific implementations can have additional behavior associated with this lock type.

Return value

The return value is an HRESULT. A value of S_OK indicates the call was successful.

Remarks

The byte range can extend past the current end of the stream. Locking beyond the end of a stream is useful as a method of communication between different instances of the stream without changing data that is actually part of the stream.

Three types of locking can be supported: locking to exclude other writers, locking to exclude other readers or writers, and locking that allows only one requester to obtain a lock on the given range, which is usually an alias for one of the other two lock types. A given stream instance might support either of the first two types, or both. The lock type is specified by dwLockType, using a value from the LOCKTYPE enumeration.

Any region locked with LockRegion must later be explicitly unlocked by calling IByteBuffer::UnlockRegion with exactly the same values for the libOffset, cb, and dwLockType parameters. The region must be unlocked before the stream is released. Two adjacent regions cannot be locked separately and then unlocked with a single unlock call.

Examples

The following example shows restricting access to a range of bytes.

HRESULT  hr;

// Lock a region.
hr = pIByteBuff->LockRegion(0, 10, LOCK_EXCLUSIVE);
if (FAILED(hr))
  printf("Failed IByteBuffer::LockRegion\n");

Requirements