Share via


ILockBytes

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This 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 Component Object Model (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.

When to Implement

Most applications will not implement the ILockBytes interface because COM provides implementations for one of the most common situations:

File-based implementation If you call the 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.

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 function, which creates a compound file storage object on top of a caller-provided byte array object.

When to Use

The ILockBytes methods are called by the COM implementations of the IStorage and IStream interfaces 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.

Methods

The following table shows the methods for this interface in alphabetical order.

Method Description

Flush

Ensures that any internal buffers maintained by the byte array object are written out to the backing storage.

LockRegion

Restricts access to a specified range of bytes in the array.

ReadAt

Reads a specified number of bytes starting at a specified offset from the beginning of the array.

SetSize

Changes the size of the byte array.

Stat

Retrieves a STATSTG structure for this byte array object.

UnlockRegion

Removes the access restriction on a range of bytes previously restricted with ILockBytes::LocRegion.

WriteAt

Writes a specified number of bytes to a specified location in the array.

Remarks

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 2.0 and later
Windows Mobile Windows Mobile Version 5.0 and later