Microsoft KB Archive/189515

SAMPLE: WNetCOM Uses COM Object to Access WNet Functions from VB

Q189515

The information in this article applies to:

Microsoft Win32 Software Development Kit (SDK), on platform(s):
- Microsoft Windows 98
- Microsoft Windows 95
- the operating system: Microsoft Windows NT 4.0
- the operating system: Microsoft Windows 2000

SUMMARY

WNetCOM.exe is a sample that contains the WNet COM object. The WNet COM object demonstrates how to access complicated networking features from Visual Basic using COM. The object was created using the ATL COM Wizard in Visual C++ 5. This COM object is implemented as a DLL. Once the skeleton code is generated, click Insert and then click New Class to create a WNet class. This new class is defined as a Custom interface with just 1 interface. The new class contains the code to implement the various WNet features. From the Class View, you may add methods by right-clicking the interface and selecting Add Method.

From there, you can add the methods that you want to implement in the COM object. The sample code provided in this article is meant to be used as a tutorial for implementing your own controls that wrap up complex APIs. It is not meant to be used as production code.

MORE INFORMATION

The following file is available for download from the Microsoft Download Center:

WNetCOM.exe

For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. Once posted, the file is housed on secure servers that prevent any unauthorized changes to the file.

OR Release Date: Jul-15-1998

For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. Once posted, the file is housed on secure servers that prevent any unauthorized changes to the file.

Installation and Use

After you have extracted the files into a directory, start Visual C++ and load the project. On the Build menu, click Rebuild All. This will compile the project and install the control into the system. In Visual Basic, you can now add the object to your project by going to the Project menu and clicking References. The COM object is listed as "NetwkObj 1.0 Type Library." While still in Visual Basic, you may use either early or late binding to instantiate these types of objects. The object (type) name is NetwkObj and the interface is WNet. Following is an example of early binding in Visual Basic:

Dim x as NetwkObj.WNet

Following is an example of late binding:

   Dim x as Object

   Set x = CreateObject("NetwkObj.WNet")

Source Files

This file is associated with the WNet COM object.

Following are the files associated with this application:

NetwkObj.mak

The Visual C++ project makefile for building the WNet COM object.

NetwkObj.h

This file is generated by the MIDL compiler when run against the .idl file. It contains C declarations of any special types declared for the interface. This is required if you have a unique type that you want to use as a parameter to a method.

NetwkObj.cpp

This is the main source file that contains code for DLL initialization, termination, and other bookkeeping.

NetwkObj.rc

This is a listing of the Microsoft Windows resources that the project uses. You can directly edit this file with the Visual C++ resource editor.

NetwkObj.def

This file contains information about the WNet COM object DLL that must be provided to run with Microsoft Windows.

NetwkObj.idl

This file contains the Interface Description Language source code for the type library of the object. This is where type definitions need to go if you want to see them in Visual Basic.

WNet.h

This file contains the declaration of the WNet C++ class. This includes the definition of the COM object's methods.

WNet.cpp

This file contains the implementation of the WNet C++ class.

WNet.rgs

This file contains the information necessary to register the COM object with the system so Visual Basic can use it.

Stdafx.h and Stdafx.cpp

These files are used to build a precompiled header (PCH) file named stdafx.pch and a precompiled types (PCT) file named stdafx.obj.

Resource.h

This is the standard header file, which defines new resource IDs. The Visual C++ resource editor reads and updates this file.

Properties, Methods, and Events

The WNet COM object has the following methods:

AddConnection(RemoteName, LocalName, UserName, Password)

This method maps a remote resource to the local machine. Only the RemoteName is required. All other parameters are optional. This will work with both share drives and printers. When you leave UserName and Password out of zero length strings, the users current credentials are used for checking permission on the remote share.
DelConnection(Name, Flags, Force)

This method unmaps a remote resource that has been redirected locally. Name can either be the UNC remote resource or the local drive letter. If it is the UNC name, all instances of that remote resource that are mapped locally are unmapped. If it is a drive letter, only that drive letter is unmapped. Flags can specify whether to update the users profile or not to.
```
      Flag Value                    Meaning
      ------------------------------------------------------------------

      WNetNoFlag                     No value.

      WNetUpdateProfile              Updates user profile to reflect
                                     removal of remote resource mapping. 
```
Force is a boolean value that tells the API to forcefully disconnect, even if the user has open files on the remote resource.
GetUser()

This method retrieves the username of the user who is currently logged on.
OpenEnumeration(ResourceType, Name)

This method is the initial call to enumerate a particular network resource. The first parameter is an enumeration type that specifies one of four resources to enumerate. The available views are:
```
      Enumeration Type               Resource Viewed
      ----------------------------------------------------------------

      WNetResNeighborhood          Network neighborhood view.

      WNetResLocalShares           Remote resources mapped locally.

      WNetResRemoteShares          Remote resources available for mapping.

      WNetResEnumDomain            Machines in a domain. 
```
The Name parameter is optional for the first two enumeration types, but it is required for WNetResRemoteShares and WNetResEnumDomain. In those cases, Name refers to the remote computer or domain name, respectively.
EnumResources()

This method is called continuously, and it returns a resource string. When NULL or vbNullString is returned, there are no more resources left to enumerate.
CloseEnumeration()

This method closes an enumeration that is already open. This should always be paired with an OpenEnumeration call. In addition, this method can be called at any point in the enumeration process, after OpenEnumeration.
GetConnection(LocalName)

This method returns the UNC name of the remote resource that is mapped to LocalName.
GetErrorText()

This method returns the text error message.

Support Files

Along with the source code for the WNet COM object is a Visual Basic project that illustrates how to use the WNet COM object for network programming. The Visual Basic project consists of the following files:

Form1.frm

Project1.vbp

Project1.vbw

This application is very simple. There is one section devoted to each of the WNet functions. The following five frames are on the form:

   Frame                Resource Viewed
   ------------------------------------------------------------------------

   Map Drive            Fill in the appropriate text boxes that
                        correspond to the function parameters, and
                        click Map It!

   Unmap Resource       Fill in the resource name, either local or
                        Remote, and click Unmap!

   Current User         Click Get Current User to fill in the text box with
                        the current user.

   Enumerate Resource   Select one of the four views, and enter a name,
                        if necessary. Click Enumerate, and the list box
                        will be populated with the results.

   Connection Info      Fill in the Local Name of the resource, and
                        click Get Info. The remote name will be filled with
                        the UNC name of the resource it is mapped to.

Each subroutine that calls a method on the WNet COM object has an "On Error" handler. Within the handler there is a simple MsgBox that calls the GetErrorText() method to retrieve an error string. You can implement more advanced error handling in the COM object relatively easily.

Additional query words:

Keywords : kbfile kbnetwork kbAPI kbOSWinNT400 kbSDKPlatform kbOSWin95 kbOSWin98 kbWNet kbGrpDSNet
Issue type :
Technology : kbWin32SDKSearch kbAudDeveloper kbSDKSearch kbWin32sSearch