The ILockBytes interface is implemented on a byte array object that is backed by some physical storage, such as a disk file, global memory, or a database. It is used by a COM compound file storage object to give its root storage access to the physical device, while isolating the root storage from the details of accessing the physical storage.
Most applications will not implement the ILockBytes interface because COM provides implementations for the two most common situations:
File-based implementation — If you call StgCreateDocfile function to create a compound file storage object, it contains an implementation of ILockBytes that is associated with a byte array stored in a physical disk file. The compound file storage object calls the ILockBytes methods—you do not call them directly in this implementation.
Memory-based implementation — COM also provides a byte array object based on global memory that supports an implementation of ILockBytes. You can get a pointer through a call to the CreateILockBytesOnHGlobal function). Then, to create a compound file storage object on top of that byte array object, call the StgCreateDocfileOnILockBytes function. The compound file storage object calls the ILockBytes methods — you do not call them directly in this implementation.
There are situations in which it would be useful for an application to provide its own ILockBytes implementation. For example, a database application could implement ILockBytes to create a byte array object backed by the storage of its relational tables. However, it is strongly recommended that you use the COM-provided implementations. For a discussion of the advantages of using the COM implementations rather than creating your own, see the StgCreateDocfileOnILockBytes API function, which creates a compound file storage object on top of a caller-provided byte array object.
If you choose to implement your own ILockBytes interface, you should consider providing custom marshaling by implementing the IMarshal interface as part of your byte array object. The reason for this is that when the COM-provided implementations of IStorage and IStream are marshaled to another process, their ILockBytes interface pointers are also marshaled to the other process. The default marshaling mechanism creates a proxy byte array object (on which is the ILockBytes interface) that transmits method calls back to the original byte array object. Custom marshaling can improve efficiency by creating a remote byte array object that can access the byte array directly.
The ILockBytes methods are called by the COM implementations of IStorage and IStream on the compound file object. Unless you are implementing IStorage and IStream, you would not need to call ILockBytes methods directly. If you write your own ILockBytes implementation, you can use the StgCreateDocfileOnILockBytes function to create a compound file storage object backed by your implementation of ILockBytes.
| IUnknown Methods | Description |
|---|---|
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| ILockBytes Methods | Description |
|---|---|
| ReadAt | Reads a specified number of bytes starting at a specified offset from the beginning of the byte array. |
| WriteAt | Writes a specified number of bytes to a specified location in the byte array. |
| Flush | Ensures that any internal buffers maintained by the byte array object are written out to the backing storage. |
| SetSize | Changes the size of the byte array. |
| LockRegion | Restricts access to a specified range of bytes in the byte array. |
| UnlockRegion | Removes the access restriction on a range of bytes previously restricted with ILockBytes::LockRegion. |
| Stat | Retrieves a STATSTG structure for this byte array object. |
Windows NT: Use version 3.1 or later.
Windows: Use Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in objidl.h.