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

609 lines
20 KiB
C++
Raw Permalink Normal View History

2020-09-26 03:20:57 -05:00
/**********************************************************************/
/** Microsoft Windows NT **/
/** Copyright(c) Microsoft Corp., 1992 **/
/**********************************************************************/
/*
lmoersm.hxx
This file contains the class declarations for the LM_RESUME_ENUM
and LM_RESUME_ENUM_ITER classes.
LM_RESUME_ENUM is a generic enumeration class for resumeable
API. LM_RESUME_ENUM_ITER is an iterator for iterating objects
created from the LM_RESUME_ENUM class.
NOTE: All classes contained in this file were derived from
RustanL's LM_ENUM/LM_ENUM_ITER classes.
FILE HISTORY:
KeithMo 29-May-1991 Created for the Server Manager.
KeithMo 13-Aug-1991 Cleanup, added LOCATION support.
KeithMo 19-Aug-1991 Code review revisions (code review
attended by ChuckC, Hui-LiCh, JimH,
JonN, KevinL).
KeithMo 04-Sep-1991 Added a new control flag to the method
LM_RESUME_ENUM_ITER::operator() which
allows the client to optionally suspend
an iteration after the current enumeration
buffer is exhausted.
KeithMo 07-Oct-1991 Win32 Conversion.
KeithMo 23-Oct-1991 Added forward references.
JonN 30-Jan-1992 Split LOC_LM_RESUME_ENUM from LM_RESUME_ENUM
KeithMo 18-Mar-1992 Added optional constructor parameter to
force enumerator to keep all buffers.
KeithMo 31-Mar-1992 Code review revisions (code review
attended by JimH, JohnL, JonN, and ThomasPa).
*/
#ifndef _LMOERSM_HXX_
#define _LMOERSM_HXX_
//
// NOTE: Since this header file uses the ASSERT() macro, we include
// UIASSERT.HXX for its definition. However, you will experience
// much less "DGROUP bloat" if you use the _FILENAME_DEFINED_ONCE
// trick *before* including this header file.
//
#include "uiassert.hxx"
#include "lmoloc.hxx"
#include "lmoenum.hxx"
#include "slist.hxx"
//
// Forward references.
//
DLL_CLASS LM_RESUME_BUFFER;
DLL_CLASS LM_RESUME_ENUM;
DLL_CLASS LM_RESUME_ENUM_ITER;
/*************************************************************************
NAME: LM_RESUME_BUFFER
SYNOPSIS: LM_RESUME_BUFFER is used to keep track of the buffers
allocated by the resumeable enumerator. An SLIST of these
nodes is maintained by LM_RESUME_ENUM2.
INTERFACE: LM_RESUME_BUFFER - Class constructor.
~LM_RESUME_BUFFER - Class destructor.
QueryItemCount - Returns the number of enumeration
items stored in the buffer
associated with this node.
QueryBufferPtr - Returns the buffer pointer
associated with this node.
PARENT: BASE
HISTORY:
KeithMo 15-Mar-1992 Created for the Server Manager.
**************************************************************************/
DLL_CLASS LM_RESUME_BUFFER : public BASE
{
private:
LM_RESUME_ENUM * _penum;
UINT _cItems;
BYTE * _pbBuffer;
public:
LM_RESUME_BUFFER( LM_RESUME_ENUM * penum,
UINT cItems,
BYTE * pbBuffer );
~LM_RESUME_BUFFER( VOID );
UINT QueryItemCount( VOID ) const
{ return _cItems; }
const BYTE * QueryBufferPtr( VOID ) const
{ return _pbBuffer; }
}; // class LM_RESUME_BUFFER
DECL_SLIST_OF( LM_RESUME_BUFFER, DLL_BASED );
/*************************************************************************
NAME: LM_RESUME_ENUM
SYNOPSIS: LM_RESUME_ENUM is a generic enumeration class
for resumeable LanMan enumeration API.
INTERFACE: LM_RESUME_ENUM() - Class constructor.
~LM_RESUME_ENUM() - Class destructor.
QueryInfoLevel() - Query the information level.
GetInfo() - Retrieves enumeration info.
PARENT: BASE
HISTORY:
KeithMo 29-May-1991 Created for the Server Manager.
KeithMo 13-Aug-1991 Cleanup.
JonN 30-Jan-1992 Split off LOC_LM_RESUME_ENUM
**************************************************************************/
DLL_CLASS LM_RESUME_ENUM : public BASE
{
//
// Declare LM_RESUME_ENUM_ITER as a friend class so that it
// can access our private data members & methods.
//
friend class LM_RESUME_ENUM_ITER;
friend class LM_RESUME_BUFFER;
private:
//
// The current info level.
//
UINT _uLevel;
//
// This flag is set to TRUE if GetInfo() is to
// repeatedly invoke CallAPI() until the enumeration
// is exhausted, keeping all of the returned buffers
// in a private SLIST.
//
// Otherwise, each GetInfo() call will invoke CallAPI()
// only once, and "old" API buffers are not kept around.
//
BOOL _fKeepBuffers;
//
// The following data items are only useful if
// _fKeepBuffers is FALSE.
//
// _pbBuffer is a pointer to the buffer returned by CallAPI().
//
// _cEntriesRead is the number of data items returned by
// CallAPI().
//
// _fMoreData is set to TRUE if there is more enumeration data
// to be gleaned by subsequent CallAPI() invocations.
//
BYTE * _pbBuffer;
UINT _cEntriesRead;
BOOL _fMoreData;
//
// The following data items are only useful if
// _fKeepBuffers is TRUE.
//
// _BufferList is an SLIST of LM_RESUME_BUFFERs. This
// is used to keep track of the enumeration buffers
// returned by CallAPI().
//
UINT _cAllItems;
SLIST_OF( LM_RESUME_BUFFER ) _BufferList;
//
// This is the number of iterators which have "bound" to this
// enumerator.
//
// NOTE: if _fKeepBuffers is FALSE, then only iterator may
// be bound to the enumerator at any one time, since any call
// to the iterator's Next method may potentially invalidate
// all previous data returned by the iterator.
//
UINT _cIterRef;
//
// This method calls the enumeration API. The info level can be
// retrieved through the QueryInfoLevel() method.
//
// It is assumed that any necessary resume key(s) are private data
// members of the derived class.
//
virtual APIERR CallAPI( BOOL fRestartEnum,
BYTE ** ppbBuffer,
UINT * pcEntriesRead ) = 0;
//
// Register an iterator "binding" to this enumerator.
//
VOID _RegisterIter( VOID );
VOID RegisterIter( VOID )
#ifdef DEBUG
{ _RegisterIter() ; }
#else
{}
#endif
//
// Deregister an iterator "unbinding" from this enumerator.
//
VOID _DeregisterIter( VOID );
VOID DeregisterIter( VOID )
#ifdef DEBUG
{ _DeregisterIter() ; }
#else
{}
#endif
APIERR GetInfoSingle( BOOL fRestartEnum );
APIERR GetInfoMulti( VOID );
protected:
//
// The class constructor is protected so that this
// class can only be instantiated by derived subclasses.
//
LM_RESUME_ENUM( UINT uLevel, BOOL fKeepBuffers = FALSE );
//
// This method is invoked to free an enumeration buffer.
//
virtual VOID FreeBuffer( BYTE ** ppbBuffer ) = 0;
//
// This method deletes the buffer(s) maintained by this
// enumerator.
//
// THIS METHOD **MUST** BE CALLED FROM THE DESTRUCTOR
// OF ANY DERIVED SUBCLASS THAT OVERRIDES THE FreeBuffer()
// VIRTUAL!!!
//
VOID NukeBuffers( VOID );
public:
//
// Class destructor.
//
~LM_RESUME_ENUM();
//
// This method returns the LanMan API info level.
//
UINT QueryInfoLevel( VOID ) const
{ return _uLevel; }
//
// This method performs the initial CallAPI invocation(s).
//
APIERR GetInfo( BOOL fRestartEnum = TRUE );
//
// Query the current value of the _fKeepBuffers flag.
//
BOOL DoesKeepBuffers( VOID ) const
{ return _fKeepBuffers; }
//
// This method is only useful if _fKeepBuffers is TRUE.
//
UINT QueryTotalItemCount( VOID ) const
{ ASSERT( DoesKeepBuffers() ); return _cAllItems; }
}; // class LM_RESUME_ENUM
/*************************************************************************
NAME: LOC_LM_RESUME_ENUM
SYNOPSIS: LOC_LM_RESUME_ENUM adds a LOCATION object to the
generic resumable enumeration class.
INTERFACE: LOC_LM_RESUME_ENUM() - Class constructor.
~LOC_LM_RESUME_ENUM() - Class destructor.
QueryServer() - Query the target server name.
PARENT: LM_RESUME_ENUM
USES: LOCATION
HISTORY:
JonN 30-Jan-1992 Split from LM_RESUME_ENUM
**************************************************************************/
DLL_CLASS LOC_LM_RESUME_ENUM : public LM_RESUME_ENUM
{
//
// Declare LM_RESUME_ENUM_ITER as a friend class so that it
// can access our private data members & methods.
//
friend class LM_RESUME_ENUM_ITER;
private:
//
// This represents the target server.
//
LOCATION _loc;
//
// This method calls the enumeration API. The server name and
// info level can be retrieved through the
// LOC_LM_RESUME_ENUM::QueryServer() and QueryInfoLevel() methods.
//
// It is assumed that any necessary resume key(s) are private data
// members of the derived class.
//
virtual APIERR CallAPI( BOOL fRestartEnum,
BYTE ** ppbBuffer,
UINT * pcEntriesRead ) = 0;
protected:
//
// The class constructors are protected so that this
// class can only be instantiated by derived subclasses.
//
LOC_LM_RESUME_ENUM( const TCHAR * pszServerName,
UINT uLevel,
BOOL fKeepBuffers = FALSE );
LOC_LM_RESUME_ENUM( LOCATION_TYPE locType,
UINT uLevel,
BOOL fKeepBuffers = FALSE );
LOC_LM_RESUME_ENUM( const LOCATION & loc,
UINT uLevel,
BOOL fKeepBuffers = FALSE );
//
// This method is invoked to free an enumeration buffer.
//
virtual VOID FreeBuffer( BYTE ** ppbBuffer );
public:
//
// Class destructor.
//
~LOC_LM_RESUME_ENUM();
//
// This method returns the target server name.
//
const TCHAR * QueryServer( VOID ) const
{ return _loc.QueryServer(); }
}; // class LOC_LM_RESUME_ENUM
/*************************************************************************
NAME: LM_RESUME_ENUM_ITER
SYNOPSIS: LM_RESUME_ENUM_ITER is a generic iterator for
LM_RESUME_ENUM objects.
INTERFACE: LM_RESUME_ENUM_ITER() - Class constructor.
~LM_RESUME_ENUM_ITER() - Class destructor.
QueryBasePtr() - Returns a pointer to the
enumeration buffer.
QueryCount() - Queries the number of objects in
the current enumeration buffer.
HasMoreData() - Returns TRUE if further calls
to the enumerator API must be
made.
NextGetInfo() - Invoke the enumerator API
to refill the buffer.
PARENT: BASE
USES: LM_RESUME_ENUM
HISTORY:
KeithMo 29-May-1991 Created for the Server Manager.
KeithMo 13-Aug-1991 Cleanup.
**************************************************************************/
DLL_CLASS LM_RESUME_ENUM_ITER : public BASE
{
private:
//
// This points to the enumerator the current iterator is "bound" to.
//
LM_RESUME_ENUM * _plmenum;
//
// This field is only used if the bound enumerator has the
// _fKeepBuffers field set to TRUE. This iterator is used
// to iterate through the API buffer list.
//
ITER_SL_OF( LM_RESUME_BUFFER ) _iterBuffer;
LM_RESUME_BUFFER * _plmbuffer;
protected:
//
// Usual constructor/destructor goodies.
//
LM_RESUME_ENUM_ITER( LM_RESUME_ENUM & lmenum );
~LM_RESUME_ENUM_ITER();
//
// This method returns a pointer to the enumerators data buffer.
//
const BYTE * QueryBasePtr() const ;
//
// This method returns a count of the number of objects in the
// current enumerator buffer.
//
UINT QueryCount( VOID ) const ;
//
// This method returns TRUE if there is more data available
// from the enumeration API.
//
BOOL HasMoreData( VOID ) const ;
//
// This method is called to refill the enumerator buffer
// after the current buffer has been exhausted.
//
APIERR NextGetInfo( VOID );
}; // class LM_RESUME_ENUM_ITER
//
// Define a convenient macro for creating iterators.
//
// To use:
//
// DECLARE_LM_RESUME_ENUM_ITER_OF( FILE3, struct file_info_3 );
//
// The first argument is an LMOBJ class. The second argument
// is a structure which the iterator returns pointers to.
//
#define DECLARE_LM_RESUME_ENUM_ITER_OF( enum_name, type ) \
\
class enum_name##_ENUM_ITER : public LM_RESUME_ENUM_ITER \
{ \
private: \
UINT _i; \
enum_name##_ENUM_OBJ _enumobj; \
const type * _p; \
BOOL _fStopped; \
\
public: \
enum_name##_ENUM_ITER( enum_name##_ENUM & e ); \
\
const enum_name##_ENUM_OBJ * Next( APIERR * perr, \
BOOL fStop = FALSE ); \
\
const enum_name##_ENUM_OBJ * operator()( APIERR * perr, \
BOOL fStop = FALSE ) \
{ return Next( perr, fStop ); } \
\
}; /* class enum_name##_ENUM_ITER */
#define DEFINE_LM_RESUME_ENUM_ITER_OF( enum_name, type ) \
\
enum_name##_ENUM_ITER::enum_name##_ENUM_ITER( enum_name##_ENUM & e ) \
: LM_RESUME_ENUM_ITER( e ), \
_enumobj(), \
_p( (type *)QueryBasePtr() ), \
_i( 0 ), \
_fStopped( FALSE ) \
{ \
; \
\
} /* enum_name##_ENUM_ITER :: enum_name##_ENUM_ITER */ \
\
const enum_name##_ENUM_OBJ * enum_name##_ENUM_ITER::Next( APIERR * perr, \
BOOL fStop ) \
{ \
*perr = NERR_Success; \
\
if( _p == NULL ) \
{ \
return NULL; \
} \
\
if( _i >= QueryCount() ) \
{ \
if( HasMoreData() ) \
{ \
if( !_fStopped && fStop ) \
{ \
_fStopped = TRUE; \
*perr = ERROR_MORE_DATA; \
return NULL; \
} \
\
_fStopped = FALSE; \
\
APIERR err = NextGetInfo(); \
\
if( err != NERR_Success ) \
{ \
*perr = err; \
_p = NULL; \
return NULL; \
} \
\
_p = (type *)QueryBasePtr(); \
_i = 0; \
} \
} \
\
if( _i < QueryCount() ) \
{ \
_i++; \
_enumobj.SetBufferPtr( _p++ ); \
return &_enumobj; \
} \
\
_p = NULL; \
return NULL; \
\
} /* enum_name##_ENUM_ITER :: operator() */
#endif // _LMOERSM_HXX_