Network Enumerations

As many plain Win32-API tasks, the network enumeration can be a difficult one. To keep me from implementing such a task over and over again, I wrote a CNetwork class.
The class CNetwork is mainly for enumerating the network and performing different tasks on the resources hit by the enumeration, so the central method of the class is

BOOL  Enumerate(DWORD dwFlags = CNetwork::SEARCHDEFAULT);

This method starts the enumeration of the network resources. The possible values for the <dwFlags> parameter are defined inside CNetwork as follows

#define _BIT(n)  (1<<n)
enum {
	GLOBALNET = _BIT(0),	// search the entire network
	CONNECTED = _BIT(1),	// search only currently connected resources
	REMEMBERED = _BIT(2),	// search only "persistent" connections

	TYPE_ANY = _BIT(3),		// search all types of resources
	TYPE_DISK = _BIT(4),	// search all disk resources
	TYPE_PRINT = _BIT(5),	// search all print resources

	SEARCHDEFAULT = _BIT(0) | _BIT(3)
};
#undef _BIT

Every time the Enumerate() method hits a network-resource, it calls an overridable method called

virtual BOOL OnHitResource( NETRESOURCE & ) = 0;

Note that this is a pure virtual in the base class. You have to derive your own class from CNetwork and to override this method.
The function has to return TRUE, if you want to continue enumeration; FALSE to break off.
For every hit you get a reference to a NETRESOURCE object. Not to make it necessary for you to know of this type, there are many helper functions to deal with a NETRESOURCE:

// NOTE: Only one of these functions can return TRUE with the same NETRESOURCE object.
BOOL	IsServer( NETRESOURCE &) const;		// means "Computer", thus clients too
BOOL	IsDomain( NETRESOURCE &) const;
BOOL	IsShare( NETRESOURCE & ) const;
BOOL	IsGeneric( NETRESOURCE &) const;

// The following functions will simplify the NETRESOURCE access:
LPCTSTR	GetLocalName( NETRESOURCE & ) const;
LPCTSTR	GetRemoteName( NETRESOURCE & ) const;
LPCTSTR	GetComment( NETRESOURCE & ) const;
LPCTSTR	GetProvider( NETRESOURCE & ) const;
BOOL	IsConnectable( NETRESOURCE &) const;

You can perform some actions with such a NETRESOURCE

// Add a connection to the network.
// If you want to connect to a local drive ("H:" for instance),
// you have to fill out the "lpLocalName" of <NetRC> (if this
// member is NULL or empty).
// <dwFlags> can be set to "CONNECT_UPDATE_PROFILE" to make the
// connection persistent (i.e. reconnect when the user logs on).
// if <UserName> is NULL, it defaults to the current user.
// if <Password> is NULL, it defaults to the <Username>'s password.
// See WNetAddConnection2() in the online-help for more details
BOOL	AddConnection(
			NETRESOURCE & NetRC,
			DWORD Flags = 0,		// can be CONNECT_UPDATE_PROFILE for a persistent connection
			LPTSTR UserName = 0,	// defaults to current user
			LPTSTR Password = 0		// defaults to password of current user
		);

// Cancel a network-connection. Returns TRUE on success; FALSE on
// failure. The NetError() method (see below) will be called on
// failure. For further information see WNetCancelConnection2()
// in the online-help.
BOOL	CancelConnection(
			LPTSTR szName,			// local or remote name of the resource
			DWORD dwFlags = CONNECT_UPDATE_PROFILE,
			BOOL ForceDisconnect = FALSE	// force a disconnect even if the resource is in use
		);
BOOL	CancelConnection(
			NETRESOURCE & NetRC,
			DWORD dwFlags = CONNECT_UPDATE_PROFILE,
			BOOL ForceDisconnect = FALSE
		);

As you can see, not many of the WNet*() functions are encapsulated by this class. Remember: this is mainly a network-enumerator! Most of the WNet*() functions are simple enough, so that they don't need a wrapping by this class ...

There is one more virtual method that you might want to override:

virtual BOOL NetError( DWORD dwErrNo, LPCTSTR pszFunction );

Normally, this function will be called from inside the enumeration or one of the operations (Add-/CancelConnection()). The NetError() method will return FALSE, if the occured error is a serious one; otherwise it can return TRUE to indicate a minor error. The default implementation of this method retrieves a human readable error message and stores it in the member

LPTSTR m_pszError;

One can retrieve its content via a call to

LPCTSTR  GetErrorString() const ;

So if you override NetError(), you should call the base-class' implementation too, if you encounter a serious error. The original NetError() returns always FALSE.

Often it is wanted to have a handler for the network-enumeration in another class. For this reason I've derived a template class from CNetwork that does the requiered work. This class is called CNetSearch.
You can use this class as follows:
In the class, where you want to handle the resource hits, insert a member of type CNetSearch<>. For instance:

class CSampleClass {
	// ...
	CNetSearch<CSampleClass>	m_NetWalker;

	BOOL	OnNetResourceHit(NETRESOURCE &);	// handler function for netresource hits
	// ...
};

In the implementation file of the sample class you have to Create() the CNetSearch<> object:

CSampleClass :: CSampleClass() {
	// ...
	m_NetWalker.Create(this, OnNetResourceHit);
	// ...
}

BOOL CSampleClass :: OnNetResourceHit(NETRESOURCE & NetRC) {
	// This sample handler lists all known computer names in the output window
	// of the debugger.
	if(m_NetWalker. IsServer(NetRC) ) {
		CString str = m_NetWalker.GetRemoteName(NetRC);
		register int i = 0;
		for( ; str[i] == '\\' ; ++i );
		if( i )
			str = str.Mid(i);
		str.MakeLower();
		TRACE1("found computer \"%s\"\n", LPCTSTR(str));
	return TRUE;	// continue enumeration
}

void CSampleClass :: SomeOperation() {
	// ...
	m_NetWalker.Enumerate();	// start the enumeration. This will (hopefully) lead to subsequent calls
								// to OnNetResourceHit() above
	// ...
}

Note that CNetSearch overrides the NetError() method. It filters the errors "ERROR_BAD_NETPATH" (the resource contains more resources, but is not accessible at this time) and "ERROR_NO_NETWORK" (there is no network present) as minor errors. Other errors are passed to the base implementation of that method.

You have to turn on exception handling, if you want to use these classes. In VC++ exception handling is on by default.

CNetwork consists of three files:
Network.h
Network.cpp
NetSearch.h
Download Source 5KB
Download Sample Project 17KB

Article moved from Internet section on January 26 1999



Comments

  • How do i stop a service on the remote computer

    Posted by Legacy on 12/12/2002 12:00am

    Originally posted by: Thanh Tung

    I am now trying tro write an application to access remote control but i get a problem when i stop a service on the remote computer, here i use ControlService function

    Reply
  • This method is too slow.

    Posted by Legacy on 11/08/2002 12:00am

    Originally posted by: hebboy

    I tried it and many other methods. But I found that those method is too slow. You must wait for more than one minute to enum network neighborhoods. If someone has more efficient method, please mail me. Thank you very much.
    My email address : hebboy@163.com

    Reply
  • Shared Directory

    Posted by Legacy on 04/08/2002 12:00am

    Originally posted by: Madhusudana B.S

    How to check whether give local path is shared or not ,(i.e If i have local path "d:\testfolder\sh_fld" how do i check
    whether "d:\testfolder\sh_fld" directory is shared).
    How to get list of shares created on the local paths.

    How to remove all shares on given local path ,if share exist

    Reply
  • Is there a possibility to select ONLY resources from the Network Neighborhood?

    Posted by Legacy on 02/07/2002 12:00am

    Originally posted by: octi

    Even if you can select the resorce name wich to scan in the API function WNetOpenResource call, by setting the lpRemoteName member of the NETRESOURCE structure used as a parameter, is there a possibility to scan only for network resources visibe in the Network Neighborhood? There is no such NETRESOURCE remotename returned by the WNetOpenResorce function ever.
    Regards,
    Octi

    Reply
  • make a typedef

    Posted by Legacy on 11/08/2000 12:00am

    Originally posted by: Fco. J. M�rmol

    well, there is a program line in CNetSearch like:

    typedef BOOL (T::*NsFnc)(NETRESOURCE &);

    I don�t know what mean it.


    thanks

    Reply
  • So where and how do I define which IP address / computername to scan?

    Posted by Legacy on 07/31/2000 12:00am

    Originally posted by: Martijn Hoogendoorn

    The subject says it all I guess...;-)

    Thanks!

    Reply
  • Seems not run well under Win98 SE

    Posted by Legacy on 11/30/1999 12:00am

    Originally posted by: Minh Nguyen

    Hi folks,

    I tested the code (build with VC6), it failed to run on Win98 SE's workgroup. Error code is 50. If I now change the input parameter of Network.Enumerate as CONNECTED, it shows an empty tree, neither root, nor branch- without error message, though. Even the revision with additional code like Zoran's tip did help nothing. Whilst, shell's
    browse thread performs searching well.
    However, enumeration is the better way for automatically detecting network resources than manually (using shell's browse feature). I'll try my way to get around and update soon.


    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Live Event Date: October 29, 2014 @ 11:00 a.m. ET / 8:00 a.m. PT Are you interested in building a cognitive application using the power of IBM Watson? Need a platform that provides speed and ease for rapidly deploying this application? Join Chris Madison, Watson Solution Architect, as he walks through the process of building a Watson powered application on IBM Bluemix. Chris will talk about the new Watson Services just released on IBM bluemix, but more importantly he will do a step by step cognitive …

  • QA teams don't have time to test everything yet they can't afford to ship buggy code. Learn how Coverity can help organizations shrink their testing cycles and reduce regression risk by focusing their manual and automated testing based on the impact of change.

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds