/*****************************************************************/
/** Microsoft LAN Manager **/
/** Copyright(c) Microsoft Corp., 1991 **/
/*****************************************************************/
/*
* History:
* RustanL 03-Jan-1991 Wrote initial implementation in shell\util
* RustanL 10-Jan-1991 Added iterators, simplified usage and
* the adding of subclasses. Moved into
* LMOBJ.
* ChuckC 24-Mar-1991 Added VAlidateName()
* gregj 23-May-1991 Added LOCATION support
* rustanl 18-Jul-1991 Added ( const LOCATION & ) constructor
* rustanl 19-Jul-1991 Inherit from BASE; Removed ValidateName
* rustanl 20-Aug-1991 Changed QuerySize to QueryCount
* rustanl 21-Aug-1991 Introduced the ENUM_CALLER class
* KeithMo 07-Oct-1991 Win32 Conversion.
* KeithMo 23-Oct-1991 Added forward references.
*
*/
/*
* LM_ENUM system overview
* -----------------------
*
* The LM_ENUM system consists of the LM_ENUM, LOC_LM_ENUM, LM_ENUM_ITER, and
* ENUM_OBJ_BASE hierarchies.
*
* The LM_ENUM hierarchy offers a simple interface for calling the LAN Man
* enumeration APIs.
*
* The LM_ENUM_ITER hierarchy work in conjunction with the LM_ENUM hierarchy
* to return pointers to the different objects.
*
* LM_ENUM_ITER actually returns a pointer to a class derived from
* ENUM_OBJ_BASE. Client applications then invoke QueryXxx() methods
* from this returned object.
*
*
* To subclass LM_ENUM or LOC_LM_ENUM, replace the constructor, destructor
* (optionally) and CallAPI methods.
*
* To subclass LM_ENUM_ITER, use the DECLARE_LM_ENUM_ITER macro in the
* header file, and DEFINE_LM_ENUM_ITER macro in your source file.
*
* To subclass ENUM_OBJ_BASE, replace the QueryBufferPtr() method with
* one that casts the buffer pointer to a proper LanMan structure
* pointer. Also, provide QueryXxx() methods which parallel the
* corresponding LMOBJ object.
*
* See the other lmoe*.?xx files for code examples.
*
*
* Here follows an example of the use a LM_ENUM subclass, say SERVER1_ENUM,
* and its iterator.
*
* extern "C"
* {
* #include <server.h>
* }
* #include <lmoesrv.hxx>
*
* APIERR f( const TCHAR * pszServer )
* {
* SERVER1_ENUM se1( pszServer );
*
* APIERR err = se1.GetInfo();
* if ( err != NERR_Success )
* {
* return err;
* }
*
* SERVER1_ENUM_ITER sei1( se1 );
* const SERVER1_ENUM_OBJ * psi1;
*
* while ( ( psi1 = sei1()) != NULL )
* {
* printf( "%s\t%s\n", psi1->QueryName(), psi1->QueryComment() );
* }
*
* return NERR_Success;
*
* } // f
*
*
*/
#ifndef _LMOENUM_HXX_
#define _LMOENUM_HXX_
#include "uibuffer.hxx"
#include "lmoloc.hxx"
//
// Forward references.
//
DLL_CLASS ENUM_CALLER;
DLL_CLASS LM_ENUM_ITER;
DLL_CLASS LM_ENUM;
DLL_CLASS ENUM_OBJ_BASE;
/*************************************************************************
NAME: ENUM_CALLER
SYNOPSIS: Does the work of calling an enumeration API
INTERFACE: ENUM_CALLER() - constructor (guaranteed to succeed;
see source for more details)
QueryCount() - returns the number of enumerated
items
W_GetInfo() - Does the work of calling the
enumeration API until the buffer
is large enough. (The purpose of
this class.)
CallAPI() - Virtual method which calls the
enumeration API, using the given
parameters.
EC_QueryBufferPtr() - virtual returning a pointer to a
buffer to be used for the API
call
EC_SetBufferPtr() - virtual which sets the buffer
pointer.
PARENT:
NOTES: This class is inherited from by LM_ENUM and ENUM_CALLER_LM_OBJ,
both of which need the behavior of W_GetInfo. This way
the two classes can share code.
The virtual buffer methods all have the EC_ (for ENUM_CALLER)
prefix so as to not conflict with those of the NEW_LM_OBJ
class.
CODEWORK. CallAPI could be renamed I_CallAPI
CODEWORK. QueryCount should return a UINT
HISTORY:
rustanl 21-Aug-1991 Created from LM_ENUM
KeithMo 07-Oct-1991 Changed all USHORT to UINT.
**************************************************************************/
DLL_CLASS ENUM_CALLER
{
private:
UINT _cEntriesRead;
virtual BYTE * EC_QueryBufferPtr() const = 0;
virtual APIERR EC_SetBufferPtr( BYTE * pBuffer ) = 0;
protected:
APIERR W_GetInfo();
virtual APIERR CallAPI( BYTE ** ppBuffer,
UINT * pcEntriesRead ) = 0;
// This method should be used with caution: the calling
// subclass is responsible for updating the buffer if this
// method is called.
VOID SetCount( UINT c )
{ _cEntriesRead = c; }
public:
ENUM_CALLER();
UINT QueryCount( VOID ) const
{ return _cEntriesRead; }
}; // class ENUM_CALLER
/*************************************************************************
NAME: LM_ENUM
SYNOPSIS: Abstract base for designing enumeration classes.
INTERFACE: LM_ENUM - Class constructor.
~LM_ENUM - Class destructor.
QueryServer - Query server name.
QueryInfoLevel - Query infomation level.
GetInfo - get information.
PARENT: BASE
ENUM_CALLER
USES: LOCATION
BUFFER
HISTORY:
RustanL 03-Jan-1991 Wrote initial implementation in shell\util
RustanL 10-Jan-1991 Added iterators, simplified usage and
the adding of subclasses. Moved into
LMOBJ.
gregj 23-May-1991 Added LOCATION support.
rustanl 18-Jul-1991 Added ( const LOCATION & ) constructor
rustanl 21-Aug-1991 Inherit from ENUM_CALLER
KeithMo 07-Oct-1991 Changed all USHORT to UINT, fixed
comment block.
Thomaspa 21-Feb-1992 Moved LOCATION support to LOC_LM_ENUM
**************************************************************************/
DLL_CLASS LM_ENUM : public BASE, public ENUM_CALLER
{
friend class LM_ENUM_ITER;
private:
UINT _uLevel;
BYTE * _pBuffer;
UINT _cIterRef;
// This method calls the LAN Man API. The server name and info level
// can be retrieved through the QueryServer and QueryInfoLevel methods.
virtual APIERR CallAPI( BYTE ** ppBuffer,
UINT * pcEntriesRead ) = 0;
// This following two methods are private, and are intended to be
// called by the LM_ENUM_ITER friend class.
//
// 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
// Replacements for virtuals in ENUM_CALLER class
virtual BYTE * EC_QueryBufferPtr() const;
virtual APIERR EC_SetBufferPtr( BYTE * pBuffer );
protected:
LM_ENUM( UINT uLevel );
// Returns pointer to buffer, or NULL on error or if there are no entires.
BYTE * QueryPtr( VOID ) const
{ return _pBuffer; }
public:
~LM_ENUM();
UINT QueryInfoLevel( VOID ) const
{ return _uLevel; }
APIERR GetInfo( VOID );
}; // class LM_ENUM
/*************************************************************************
NAME: LOC_LM_ENUM
SYNOPSIS: LM_ENUM with LOCATION object
INTERFACE: LOC_LM_ENUM - Class constructor.
~LOC_LM_ENUM - Class destructor.
QueryServer - Query server name.
PARENT: LM_ENUM
USES: LOCATION
HISTORY:
thomaspa 21-Feb-1992 Split off from LM_ENUM
**************************************************************************/
DLL_CLASS LOC_LM_ENUM : public LM_ENUM
{
private:
LOCATION _loc;
virtual APIERR CallAPI( BYTE ** ppBuffer,
UINT * pcEntriesRead ) = 0;
protected:
LOC_LM_ENUM( const TCHAR * pszServer, UINT uLevel );
LOC_LM_ENUM( LOCATION_TYPE locType, UINT uLevel );
LOC_LM_ENUM( const LOCATION & loc, UINT uLevel );
public:
~LOC_LM_ENUM();
const TCHAR * QueryServer( VOID ) const;
}; // class LOC_LM_ENUM
/*************************************************************************
NAME: LM_ENUM_ITER
SYNOPSIS: Abstract base for designing iterator classes which
interface with classes derived from the LM_ENUM
enumerator class.
INTERFACE: LM_ENUM_ITER - Class constructor, takes a
reference to an LM_ENUM.
~LM_ENUM_ITER - Class destructor.
QueryBasePtr - Returns a pointer to the
LM_ENUM's enumeration buffer.
QueryCount - Returns the number of items
in the LM_ENUM's enumeration
buffer.
USES: LM_ENUM
HISTORY:
RustanL 03-Jan-1991 Wrote initial implementation in shell\util
RustanL 10-Jan-1991 Added iterators, simplified usage and
the adding of subclasses. Moved into
LMOBJ.
KeithMo 07-Oct-1991 Changed all USHORT to UINT, fixed
comment block.
**************************************************************************/
DLL_CLASS LM_ENUM_ITER
{
private:
UINT _cItems;
LM_ENUM * _plmenum;
protected:
LM_ENUM_ITER( LM_ENUM & lmenum );
~LM_ENUM_ITER();
BYTE * QueryBasePtr() const
{ return _plmenum->QueryPtr(); }
UINT QueryCount( VOID ) const
{ return _cItems; }
}; // class LM_ENUM_ITER
/*************************************************************************
NAME: ENUM_OBJ_BASE
SYNOPSIS: Abstract class from which classes returned by LM_ENUM_ITER
are derived from.
INTERFACE: ENUM_OBJ_BASE - Class constructor.
~ENUM_OBJ_BASE - Class destructor.
SetBufferPtr - Sets this object's buffer pointer.
QueryBufferPtr - Returns this object's buffer
pointer.
PARENT: BASE
HISTORY:
KeithMo 07-Oct-1991 Created.
**************************************************************************/
DLL_CLASS ENUM_OBJ_BASE : public BASE
{
//
// We declare the LM_ENUM_ITER class to be a friend so that it
// (and classes derived from it) can invoke the Query/SetBufferPtr()
// methods.
//
friend class LM_ENUM_ITER;
private:
//
// This is the pointer to this object's buffer. Note that this
// class does not do any actual buffer manipulation. This class
// is designed to receive its buffer from an LM_ENUM_ITER object
// via the SetBufferPtr() method.
//
const BYTE * _pBuffer;
protected:
//
// The constructor/destructor pair are protected, since ENUM_OBJ_BASE
// will never be directly instantiated.
//
ENUM_OBJ_BASE( VOID )
{ SetBufferPtr( NULL ); }
~ENUM_OBJ_BASE( VOID )
{ SetBufferPtr( NULL ); }
//
// Query/Set the buffer pointer.
//
const BYTE * QueryBufferPtr( VOID ) const
{ return _pBuffer; }
VOID SetBufferPtr( const BYTE * pBuffer )
{ _pBuffer = pBuffer; }
}; // class ENUM_OBJ_BASE
/*
* define convenient macros for creating iterators,
* for example:
* DECLARE_LM_ENUM_ITER_OF( SERVER1, struct server_info_1 );
* DEFINE_LM_ENUM_ITER_OF( SERVER1, struct server_info_1 );
* first arg is LMOBJ class, second is a class which the
* iterator returns pointers to.
*
* Backup returns TRUE if successful, FALSE otherwise. Backs up one in the
* iteration (i.e., is the inverse of operator()).
*/
#define DECLARE_LM_ENUM_ITER_OF( enum_name, type ) \
\
class enum_name##_ENUM_ITER : public LM_ENUM_ITER \
{ \
private: \
enum_name##_ENUM_OBJ _enumobj; \
type * _p; \
UINT _i; \
\
public: \
enum_name##_ENUM_ITER( enum_name##_ENUM & e ); \
\
const enum_name##_ENUM_OBJ * operator()( VOID ); \
BOOL Backup( VOID ); \
\
}; /* class enum_name##_ENUM_ITER */
#define DEFINE_LM_ENUM_ITER_OF( enum_name, type ) \
\
enum_name##_ENUM_ITER::enum_name##_ENUM_ITER( enum_name##_ENUM & e ) \
: LM_ENUM_ITER( e ), \
_enumobj(), \
_p( (type *)QueryBasePtr() ), \
_i( 0 ) \
{ \
; \
\
} /* enum_name##_ENUM_ITER::enum_name##_ENUM_ITER */ \
\
\
const enum_name##_ENUM_OBJ * enum_name##_ENUM_ITER::operator()( VOID ) \
{ \
if ( _i < QueryCount()) \
{ \
_i++; \
_enumobj.SetBufferPtr( _p++ ); \
return &_enumobj; \
} \
\
return NULL; \
\
} /* enum_name##_ENUM_ITER::operator() */ \
\
BOOL enum_name##_ENUM_ITER::Backup( VOID ) \
{ \
BOOL fRet = FALSE ; \
if ( _i > 0 ) \
{ \
_i--; \
_enumobj.SetBufferPtr( _p-- ); \
fRet = TRUE ; \
} \
\
return fRet ; \
\
} /* enum_name##_ENUM_ITER::Backup() */
#define DECLARE_ENUM_BUFFER_METHODS( type ) \
const type * QueryBufferPtr( VOID ) const \
{ return (const type *)ENUM_OBJ_BASE :: QueryBufferPtr(); } \
\
VOID SetBufferPtr( const type * pBuffer ) \
{ ENUM_OBJ_BASE :: SetBufferPtr( (const BYTE *)pBuffer ); }
#define DECLARE_ENUM_ACCESSOR( name, type, field ) \
type name( VOID ) const \
{ return (type)(QueryBufferPtr()->field); }
#endif // _LMOENUM_HXX_