/**********************************************************************/ /** 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_