BeginAccess

Called by the DCI Client prior to each access to the surface specified by the lpSurface parameter. It is provided for the DCI provider in order to perform any tasks which may be required prior to access of the surface.

DCIRVAL CALLBACK _loadds BeginAccess(lpSurface, lpRdst)

LPVOID	*lpSurface*;
LPRECT	*lpRdst*;

INPUT PARAMETERS

lpSurface	Specifies a far pointer to a DCISURFACEINFO structure that was previously obtained via a DCICREATEPRIMARYSURFACE, DCICREATEOFFSCREENSURFACE, or DCICREATEOVERLAYSURFACE escape.
lpRDst	Specifies a far pointer to a RECT structure in screen coordinates which represents the area of the display screen in which the DCI Client wishes to make information visible.

RETURNS

Returns DCI_OK on success, an error code on failure, or a DCI_STATUS code specifying that all or part of the surface information has changed. DCI error and status codes are listed in Chapter 2 of the DCI Specification. A failure returned by BeginAccess indicates that the error pertains to the specific surface and implies that continued access to that surface is not possible.

COMMENTS

BeginAccess and EndAccess are called as a framework around every set of accesses to the display buffer. The DCI Client must not access surface memory before a BeginAccess or after an EndAccess. At BeginAccess, the DCI Provider must ensure that valid access is available to the memory range specified by the wSelSurface:dwOffSurface pointer.

The DCI Provider may change any and all fields in the DCIPRIMARY structure at BeginAccess. If any changes are made to the DCIPRIMARY structure the DCI Provider must return a suitable status code. No notification need be returned when callback addresses are changed; the DCI Client cannot assume that these addresses will remain unchanged.

The DCI Client is encouraged to minimize processing time between BeginAccess/EndAccess. Similarly the DCI Provider is encouraged to optimize the speed of these calls so that the DCI Client does not incur a stiff penalty on each direct access of a surface. It is valid to return NULL pointers if no action need be taken by the DCI Provider.

Note It is valid to return NULL pointers if no action need be taken by the DCI Provider.

The DCI Provider must manage the mouse cursor during surface accesses. The DCI Client will provide the bounding rectangle of the area that will be accessed. The DCI Provider must exclude the cursor at BeginAccess, if the mouse cursor is within this area. At EndAccess, the DCI Provider must turn the mouse back on, if it was previously excluded.