windows-nt/Source/XPSP1/NT/admin/netui/common/h/loclheap.hxx

/**********************************************************************/
/**			  Microsoft LAN Manager 		     **/
/**		Copyright(c) Microsoft Corp., 1990, 1991	     **/
/**********************************************************************/

/*

    LOCLHEAP.hxx
    LM 2.1 Unlockable Heap and Element package

    This header file describes the HEAP_HANDLE and ELEMENT_HANDLE
    objects.  These objects can be used to create unlockable memory
    buffers.  In particular, HEAP_HANDLEs can be allocated while the
    shell is still starting up, and ELEMENT_HANDLEs can later be
    allocated within these heaps without any danger of being freed
    when the current application exits.

    Under Windows, a HEAP_HANDLE is a handle to a block of global
    memory to be accessed as a fixed heap, and an ELEMENT_HANDLE is
    a handle to a block of memory within a HEAP_HANDLE heap.
    The same interface is available to DOS/OS2 applications, but all
    operations are stubbed out or mapped to malloc/free.

    When an ELEMENT_HANDLE is locked, that handle and the HEAP_HANDLE
    heap containing it are locked and the pointer may be used freely.
    When an ELEMENT_HANDLE is not locked, its memory is free to float
    within its heap, and if a heap contains no locked elements, the
    heap can also float within global memory.

    These objects is used only by the UserProfile APIs (see uiprof.h),
    and are not recommended for new modules.  The same functionality
    is available from MEM_MASTER (see heap.hxx).  (Exception:  the
    unlockable property is not yet available from MEM_MASTER, but
    can easily be made available.)  The UserProfile APIs will
    probably be converted to MEM_MASTER for future releases, and
    this class will be eliminated.

    USAGE:

	//
	// Do not use these objects without first explicitly calling one
	// or the other form of Init().
	//

	#include <loclheap.hxx>

	HEAP_HANDLE heap;

	if (!heap.Init( 1024 ))
	    error();

	ELEMENT_HANDLE element;

	if (!element.Init( heap, 128 ))
	    error();

	LPSTR lpstr = element.Lock();

	// (... use lpstr ...)

	element.Unlock();
	element.Free();
	heap.Free();


    FILE HISTORY:

	jonn	26-Jan-1991	Created
	jonn	21-Mar-1991	Code review changes from 2/20/91 (attended
				by JonN, RustanL, ?)

*/


#ifndef _LOCLHEAP_HXX_
#define _LOCLHEAP_HXX_

/* forward refs */

DLL_CLASS ELEMENT_HANDLE;
DLL_CLASS HEAP_HANDLE;


/**********************************************************************

 NAME:	    HEAP_HANDLE

 SYNOPSIS:  Heap in which to place ELEMENT_HANDLEs

 INTERFACE:
	    Init()
		Initializes handle to empty status.  Call only on
		uninitialized HEAP_HANDLEs.

	    Init() (BOOL returning, taking args)
		Allocates new heap, by default moveable.  Call
		only on uninitialized or null HEAP_HANDLEs.  wBytes
		specifies the maximum heap size, wFlags specifies
		the Windows memory properties.  This memory
		cannot be accessed directory, it can only be
		parcelled out into memory blocks via ELEMENT_HANDLEs.

	    Free()
		Releases a heap, causing the handle to revert to null
		status.  Call only on initialized HEAP_HANDLEs.
		Release all elements in the heap first.

	    IsNull()
		Determines if a heap handle is null.  Call only
		on initialized HEAP_HANDLEs.

	    operator= ()
		Copies a HEAP_HANDLE (does NOT copy the
		underlying heap).  Do not free a handle twice.

 PARENT:

 USES:	    ELEMENT_HANDLE

 CAVEATS:   HEAP_HANDLEs and ELEMENT_HANDLEs do not have
	    constructors or destructors, and therefore will not
	    automatically initialize or destruct.  They should be
	    treated with the same care as Windows memory handles, e.g.
	    - do not use before initializing
	    - always check whether allocation succeeded
	    - do not lock before allocating
	    - always unlock after locking
	    - leave unlocked when possible to avoid sandbarring memory
	    - always free eventually
	    - only free once
	    Additionally,
	    - always free the component ELEMENT_HANDLEs before freeing
	      the HEAP_HANDLE.
	    - Try to unlock all elements in a HEAP_HANDLE heap between
	      messages, so that the heap can be unlocked and not become
	      a sandbar in global memory.
	    - Zero-length heaps are not allowed.
	    - HEAP_HANDLE heaps cannot be resized.


 NOTES:     We seperate out the Init call so that we can use global
	    HEAP_HANDLE objects without worrying about the
	    constructor-linker.


 HISTORY:   JonN     26-Jan-1991  Created
	    JonN     21-Mar-1991  Code review changes from 2/20/91 (attended
				  by JonN, RustanL, ?)

**********************************************************************/


#ifdef WINDOWS
#define HEAP_HANDLE_default	GMEM_MOVEABLE
#define ELEMENT_HANDLE_default	LMEM_MOVEABLE
#else
#define HEAP_HANDLE_default	0
#define ELEMENT_HANDLE_default	0
#endif	// WINDOWS


DLL_CLASS HEAP_HANDLE
{
friend ELEMENT_HANDLE;

private:

    HANDLE _handle;


public:

    VOID Init();

    BOOL Init(WORD wBytes, WORD wFlags = HEAP_HANDLE_default);

    VOID Free();

    BOOL IsNull();

    // copies handle, not heap
    void operator=( const HEAP_HANDLE& source );
};



/**********************************************************************

 NAME:	    ELEMENT_HANDLE

 SYNOPSIS:  Handles to memory blocks within a HEAP_HANDLE heap

 INTERFACE: Init()
		Initializes handle to empty status.  Call only on
		uninitialized handles.

	    Init() (BOOL returning, taking args)
		Allocates new memory block within a HEAP_HANDLE
		heap, by default moveable.  Call only on
		uninitialized or null ELEMENT_HANDLEs.  wBytes
		specifies the memory block size, wFlags specifies
		the Windows memory properties.

	    Free()
		Releases an memory block, causing the handle to revert
		to null status.  Call only on initialized handles.

	    Lock()
		Lock a memory block.  Returns a far pointer to the
		memory block.

	    Unlock()
		Unlock a memory block.  Do not use the pointer
		returned from Lock() after the memory block is
		unlocked.

	    IsNull()
		Determines if a handle is null.  Call only
		on initialized handles.

	    operator= ()
		Copies an ELEMENT_HANDLE.  Do not free a handle twice.


 PARENT:

 USES:

 CAVEATS:   Zero-length memory blocks are not allowed (cannot pass
	    Localinit API).
	    Memory blocks cannot be resized.

 NOTES:

 HISTORY:   JonN     26-Jan-1991  Created
	    JonN     21-Mar-1991  Code review changes from 2/20/91 (attended
				  by JonN, RustanL, ?)

**********************************************************************/

DLL_CLASS ELEMENT_HANDLE
{
private:

//
// This anonymous union is similar to that used in uibuffer.hxx.
//
#ifdef WINDOWS
#define ELEMENT_HANDLE_win	_win
#define ELEMENT_HANDLE_os2	_very_obscure_name
#else
#define ELEMENT_HANDLE_win	_very_obscure_name
#define ELEMENT_HANDLE_os2	_os2
#endif	// WINDOWS
    union
    {
	struct {
            HANDLE _globalHandle;
            HANDLE _localHandle;
	    } ELEMENT_HANDLE_win;
	struct {
	    LPSTR _lpstr;
	    } ELEMENT_HANDLE_os2;
    };

public:

    VOID Init();

    BOOL Init(const HEAP_HANDLE &heap, WORD wBytes, WORD wFlags = ELEMENT_HANDLE_default);

    VOID Free();

    LPSTR Lock();

    VOID Unlock();

    BOOL IsNull();

    // copies handle, not element
    void operator=( const ELEMENT_HANDLE& source );
};


#endif // _LOCLHEAP_HXX_