CNetService

Overview
Methods
Data Members
Examples
Availability
Installing the Class
Copyright and Use Agreement

Overview

The Microsoft Win32® API provides Windows networking (WNet) functions, providing networking capabilities for applications. The WNet functions are network independent, enabling an application to query and control network connections directly without knowledge of the underlying network transports. CNetService is an MFC class which wraps methods around each of the WNet functions, providing an object-oriented interface to these functions, grouping common variables and structures in a single class object. This allows focusing on the network project rather than the structures required by WNet.

The following WNet functions are used in CNetService:

    WNetAddConnection3
    WNetGetConnection
    WNetCancelConnection2

    WNetEnumResource
    WNetCloseEnum
    WNetOpenEnum

    WNetGetNetworkInformation
    WNetGetProviderName
    WNetGetResourceInformation
    WNetGetUniversalName
    WNetGetUser
    WNetGetLastError

The CNetService class can be extended (sub-classed) to provide access to specific keys and values, and to enhace its capabilities. Refer to the Microsoft Platform SDK: Windows Networking (WNet) documentation from the MSDN (support.microsoft.com).

Methods

Constructor

    CNetService (DWORD p_MemSize);
      Parameters:
        p_MemSize
        The amount of memory to allocate to the class for enumeration buffering. If not provided, the default configured for the class will be used.
      Remarks:
        Initializes the class. If p_MemSize is not provided, the default size configured in the class will be used.
        g_ServiceError will be set to NETSERVICE_HEAP_ALLOC if a memory allocation error occurs.

GetMem

    LPVOID GetMem (DWORD p_MemSize);
      Return Value:
        Pointer to allocated memory or NULL if error.
      Parameters:
        p_pMem
          Size of memory, in bytes, to allocate.
      Remarks:
        GetMem calls HeapAlloc to allocate memory on the processes global heap.

FreeMem

    FreeMem (void);
      Return Value:
        None.
      Parameters:
        p_pMem
          pointer to memory to deallocate
      Remarks:
        Deallocates memory allocated by GetMem.

OpenEnum

    bool OpenEnum (DWORD p_Scope,
        DWORD p_Type,
        DWORD p_Usage,
        NETRESOURCE * p_pNetResource);
    Return Value:
      true if successful, else false.
    Parameters:
      p_Scope
        Specifies the scope of the enumeration:
          RESOURCE_CONNECTED
          RESOURCE_CONTEXT
          RESOURCE_GLOBALNET
          RESOURCE_REMEMBERED
      p_Type
        Specifies the resource types to enumerate:
          RESOURCETYPE_ANY
          RESOURCETYPE_DISK
          RESOURCETYPE_PRINT
      p_Usage
        Specifies the resource usage type to enumerate:
          0 = ALL resources
          RESOURCEUSAGE_CONNECTABLE
          RESOURCEUSAGE_CONTAINER
          RESOURCEUSAGE_ATTACHED
          RESOURCEUSAGE_ALL
      p_pNetResource
        Pointer to an optional NETRESOURCE structure to apply the open to.
    Remarks:
      Refer to WNetOpenEnum for discussion of the purpose and usage.

EnumerateResource
    bool EnumerateResource (DWORD p_Count);
      Return Value:
        true if successful.
      Parameters:
        p_Count
          The number of enumerations to fetch to the default EnumBuffer.

          Set to -1 to retrieve as many as will fit in EnumBuffer.

      Remarks:
        Fetches another resource enumeration buffer to continue an enumeration of network resources that was started by a call to OpenEnum.

        Refer to WNetEnumResource for discussion of the purpose and usage.

EnumerateNext

    NETRESOURCE * EnumerateNext(void);
      Return Value:
        Pointer to the next NETRESOURCE structure in the enumeration buffer, or NULL if at the end of the buffer (not necessarily the end of the enumeration).
      Parameters:
        None.
      Remarks:
        Returns a pointer to the next NETRESOURCE structure in the resource enumeration buffer.

        Refer to WNetEnumResource for discussion of the purpose and usage.

CloseEnum

    void CloseEnum (void);
      Return Value:
        None.
      Parameters:
        None.
      Remarks:
        Closes the current enumeration handle.

        Refer to WNetCloseEnum for discussion of the purpose and usage.

GetUNC

    bool GetUNCInfo(CString p_LocalPath);
      Return Value:
        true if successful
      Parameters:
        p_LocalPath
          Path to a local device to query.
        p_InfoLevel
          Type of information to retrieve:
            UNIVERSAL_NAME_INFO_LEVEL
            REMOTE_NAME_INFO_LEVEL
      Remarks:
        Retrieves UNC (Universal Naming Convention) information representing the specified network share.

        The following Methods expose the contents returned by this Method:

          UniversalName
          UNCRemoteServer
          UNCRemotePath

UNCRemoteServer

    CString UNCRemoteServer(void);
      Return Value:
        Return the connection name from the last GetUNC call.
      Parameters:
        None.
      Remarks:
        No test is made to ensure the UNC buffer exists or is valid.

UNCRemotePath

    CString UNCRemotePath(void);
      Return Value:
        Return the remote share path from the last GetUNC call.
      Parameters:
        None.
      Remarks:
        No test is made to ensure the UNC buffer exists or is valid.

UniversalName

    CString UniversalName(void);
      Return Value:
        Return the UNC for the connection.
      Parameters:
        None.
      Remarks:
        No test is made to ensure the UNC buffer exists or is valid.

GetProviderName

    CString GetProviderName(DWORD p_NetType);
      Return Value:
        A string containing the provider name associated with a specified network type.
      Parameters:
        p_NetType
          Type of network (e.g. Novell, Banyan, etc.) to query
      Remarks:
        The network transport provider name is returned.

AddConnection

    bool AddConnection
      (HWND p_hWnd,
      NETRESOURCE * p_pNetResource,
      CString p_UserName,
      CString p_Password,
      bool p_Persistent);
    bool AddConnection
      (NETRESOURCE * p_pNetResource,
      CString p_UserName,
      CString p_Password,
      bool p_Persistent);

    Return Value:

      true if successful.
    Parameters:
      p_pNetResource
        Pointer to a NETRESOURCE structure for this request
      p_UserName
        User name to connect to the network share with, or NULL for current name.
      p_Password
        Password to qualify p_UserName with, if p_UserName is not NULL.
      p_Persistent
        True to create a persistent connection,
        False for temporary connection.
    Remarks:
      Creates the specified network connection.
      Refer to WNetAddConnection3 for specifics.

NetConnect

    bool NetConnect(HWND p_hWnd,
          DWORD p_NetDevice,
          CString p_Local,
          CString p_Remote,
          CString p_NetStack,
          CString p_UserName,
          CString p_Password,
          bool p_Persistent);
    bool NetConnect(DWORD p_NetDevice,
          CString p_Local,
          CString p_Remote,
          CString p_NetStack,
          CString p_UserName,
          CString p_Password,
          bool p_Persistent);
      Return Value:
        true if successful
      Parameters:
        p_hWnd
          Handle to a window for the network routine to use to dispatch error message boxes and request further input. If not provided, it will be set to NULL, and the caller must provide the necessary information prior to calling this method.
        p_NetDevice
          Network device type requested:
            RESOURCETYPE_DISK
            RESOURCETYPE_PRINT
        p_Local
          Specifies the name of a local device NULL for no local device
        p_Remote
          Specifies the remote network name for new connection, or network name associated with the name pointed to by p_LocalName for current/persistent connection.
        p_NetStack
          The name of the provider that owns the resource, or NULL to let the system assign.
        p_UserName
          User name to connect to the network share with, or NULL for current name.
        p_Password
          Password to qualify p_UserName with, if p_UserName is not NULL.
        p_Persistent
          True to create a persistent connection,
          False for temporary connection.
      Remarks:
        Creates the specified network connection.

NetDisconnect

    bool NetDisconnect(CString p_Local,
          DWORD p_DisconnectType,
          bool p_ForceDisconnect);
      Return Value:
        true if successful.
      Parameters:
        p_Local
          specifies the name of either the redirected local device or the remote network resource to disconnect from
        p_DisconnectType
          describes the connection type
        p_ForceDisconnect
          if true, disconnects even if files are open.
      Remarks:
        Refer to WNetCancelConnection2 for specifics.

NetUser

    CString NetUser(CString p_Remote);
      Return Value:
        A CString value containing the user name associated with the network device.
      Parameters:
        p_Remote
          Specifies the network share to query.
      Remarks:
        Returns the name of the owner of the network share. Sets g_UserName to return value.

        Refer to WNetGetUser for specifics.

ResourceDisplayType

    DWORD ResourceDisplayType(void);
      Return Value:
        Resource Display Type from the most recent NETRESOURCE structure.
      Parameters:
        None.
      Remarks:
        Refer to NETRESOURCE structure for specifics.

GetNetError

    bool GetNetError(int p_ServiceError);

    Return Value:

      false
    Parameters:
      NetService error number to store.
    Remarks:
      Sets g_Error to GetLastError and, if available, sets g_NetError and g_NetErrorMessage to the last network error supplied from the network service provider.

      The value in p_ServiceError is stored in g_ServiceError. This private method is used to store the supplied value in g_ServiceError and to store the value returned from GetLastError and, if available, the value(s) returned from WNetGetLastError.

NetError

    DWORD NetError(void);
      Return Value:
        Returns g_NetError
      Parameters:
        None.
      Remarks:
        Return the value in WNetGetLastError.

NetErrorMessage

    CString NetErrorMessage(void);
      Return Value:
        Returns g_NetErrorMessage
      Parameters:
        None.
      Remarks:
        Returns a CString containing the last decoded network level error message.

NetErrorProvider

    CString NetErrorProvider(void);
      Return Value:
        g_NetErrorProvider
      Parameters:
        None.
      Remarks:
        Returns the name of the network service provider reporting an error.

Result

    long Result(void)
      Return Value:
        Returns g_Result, the result of the last network operation.
      Parameters:
        None.
      Remarks:
        Returns the result from the last system function call which returned a result.

Error

    DWORD Error(void);
      Return Value:
        A DWORD value indicating the last error received.
      Parameters:
        None.
      Remarks:
        g_Error contains the latest GetLastError value. The returned value can be used as a parameter to ErrorMessage.

ErrorMessage

    CString ErrorMessage(DWORD p_Error);
      Return Value:
        Returns a string representing the value in p_Error
      Parameters:
        p_Error
          System error setting to lookup
      Remarks:

ServiceError

    DWORD ServiceError(void);
      Return Value:
        Returns g_ServiceError
      Parameters:
        None.
      Remarks:
        g_ServiceErrror is set by NetServices to indicate the type of exception detected.

ServiceErrorMessage

    CString ServiceErrorMessage(DWORD p_Error);
      Return Value:
        A string representing the setting of p_Error
      Parameters:
        p_ServiceError
          Result of last NetServices operation.
      Remarks:
        g_ServiceErrror is set by NetServices to indicate the type of exception detected. This routine will return a printable string containing the ServiceError message.

OSVersion

    int OSVersion(void);
      Return Value:
        Returns a value indicating the operating system currently running on the host system:
          WIN_UNKNOWN Unable to determine
          WIN32_S Windows 3.1 (Win32S)
          WIN32_NT_PRO WindowsNT 4 Workstation
          WIN32_NT_SERVER WindowsNT 4 Server
          WIN32_2000_PRO Windows 2000 Workstation
          WIN32_2000_SERVER Windows 2000 Server
          WIN32_WINDOWS_95 Windows 95
          WIN32_WINDOWS_98 Windows 98
      Parameters:
        None.
      Remarks:
         

OpenState

    bool OpenState(void);
      Return Value:
        Returns true if an enumeration object is open, false if it is closed.
      Parameters:
        None.
      Remarks:
        Returns true if an enumeration object is open, false if

NetworkInformation

    bool NetworkInformation(CString p_ProviderName);
    bool NetworkInformation(CString p_ProviderName,
          NETINFOSTRUCT * p_pNetInfoStruct)
      Return Value:
        Returns true if successful.
      Parameters:
      p_ProviderName
      Name of a network provider (as returned from GetProvider).
      p_pNetInfoStruct
      A pointer to a NETINFOSTRUCT to use for the query.
      Remarks:
        This method fetches a NETINFOSTRUC structure containing information about the requested provider.

        If form 1 is used (no NETINFOSTRUCT pointer provided), the resultant information may be retrieved using one of the GetNetInfo methods. These methods may not be used with form 2, as no local copy of the NETINFOSTRUCT is maintained.

GetNetInfo

    NETINFOSTRUCT * GetNetInfo(void);
      Return Value:
        A pointer to the local NETINFOSTRUCT.
      Parameters:
        None
      Remarks:
        Returns a pointer to the local NETINFOSTRUCT used in a NetworkInformation method.

GetNetInfoDrives

    DWORD GetNetInfoDrives();
      Return Value:
        A DWORD bit vector indicating the valid local disk devices for redirection.
      Parameters:
        None.
      Remarks:
        Requires a call to NetworkInformation to setup the local NETINFOSTRUCT variable.

GetNetInfoPrinters

    DWORD GetNetInfoPrinters();
      Return Value:
        A DWORD bit vector indicating the valid local print devices for redirection.
      Parameters:
        None.
      Remarks:
        Requires a call to NetworkInformation to setup the local NETINFOSTRUCT variable.

GetNetType

    WORD GetNetType();
      Return Value:
        A WORD value indicating the network type.
      Parameters:
        None.
      Remarks:
        Requires a call to NetworkInformation to setup the local NETINFOSTRUCT variable.

GetNetStatus

    DWORD GetNetStatus();
      Return Value:
        A DWORD value indicating the network status:
          NO_ERROR  Network is running.
          ERROR_NO_NETWORK  Network is not running.
          ERROR_BUSY  Network is initializing.
      Parameters:
        None.
      Remarks:
        Requires a call to NetworkInformation to setup the local NETINFOSTRUCT variable.

Data Members

Variable Name Type Usage
g_ConnectionName CString  
g_Count DWORD Number of entries in g_EnumBuffer, when valid.
g_EnumBufferSize DWORD Size of returned data in enumeration buffer.
g_EnumIndex DWORD Index into the enumeration buffer for the next item to fetch.
g_EnumMemSize DWORD Size of enumeration buffer.
g_Error DWORD Value returned by GetLastError.
g_hEnum HANDLE Handle for open enumeration. NULL when not open.
g_hMem HANDLE Handle for global process heap allocation. NULL if invalid.
g_MemSize DWORD Initial size of global heap allocation.
g_NetError DWORD Value returned by WNetGetLastError.
g_NetErrorMessage CString Error message associated with g_NetError.
g_NetErrorProvider CString Message from network provider associated with g_NetError.
g_NetInfoStruct NETINFOSTRUCT Local storage for network information query.
g_Open bool true if an open enumeration exists. Set to false when closed.
g_pEnumBuffer char * Pointer to the enumeration buffer.
g_pNetResource NETRESOURCE * Pointer to a NETRESOURCE structure (in enumeration buffer).
g_ProviderName CString Last provider name requested. Empty if never requested.
g_RemainingPath CString UNC path to a network share (set by GetUNC).
g_Result long Result code returned from last operation, where appropriate.
g_ServiceError int NetService error code from last operation/request.
g_UserName CString User of the specified share (see GetUser).
g_UniversalName CString UNC name of the network share.
g_WindowsType int Code indicating the type of Windows operating system.

Example

A VisualC++ 6 workspace containing several sample projects are included with the CNetService download:

    NetConnect
    A Windows console program which connects to a local drive to a network resource.
    NetEnum
    A Windows console program which enumerates current network resources to a console window.
    WNetEnum
    A Windows dialog which enumerates current network resources in a graphical manner.

Availability

CNetService can be downloaded here

Installing the Class

To use this class,

  1. Copy CNetService.cpp and CNetService.h to the same directory as your project or class libraries;
  2. Include CNetService.cpp and CNetService.h in your project;
  3. Add CNetService.h to any modules which make reference to CNetService or one of its' methods or variables. This will normally take the form of
      #include "CNetService.h"
    in the header files in which the CNetService object is declared.
  4. Include mpr.lib in the linker. In VisualC++, this is accomplished by adding mpr.lib to your project settings dialog, link tab, object/library modules entry.

Copyright and Use Agreement

CNetService is copyright © 2000. EarthWalk Software.

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

(www.fsf.org).

A local copy of the GNU Lesser General Public License is available here.

 

   Direct all quiries to Technical Support
   © 2000. EarthWalk Software. All rights reserved.