Windows Networking (WNet)

The Win32® API provides the Windows networking (WNet) functions so that you can implement networking capabilities in your application without making allowances for a particular network provider or physical network implementation. This is because the WNet functions are network independent.

  • About Windows Networking
  • Using Windows Networking
  • Windows Networking Reference
Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


About Windows Networking

Applications can use the WNet functions to add and cancel network connections and to retrieve information about the current configuration of the network.

The following figure shows the structure of a typical network.

In the preceding figure, the hierarchy for Microsoft® Windows NT® Server/Windows® 2000 Server resources is given in detail as Network provider #1. Network resources from other providers have different hierarchical systems. An application does not need information about the hierarchy before it begins to work with a network. It can proceed from the network root (that is, the topmost container resource) and retrieve information about the network's resources as the information is required.

Network resources that contain other resources are called containers. Container resources are in boxes in the preceding figure.

Resources that do not contain other resources are called objects. In the preceding figure, Sharepoint #1 and Sharepoint #2 are objects. A sharepoint is an object that is accessible across the network. Examples of sharepoints include printers and shared directories.


WNet Functions

The Windows Networking functions can be grouped as follows:

  • Connection functions
  • Enumeration functions
  • Information functions
  • User functions

Connection Functions

Call the following WNet connection functions to connect a local device to a network resource, and to cancel network connections.

Function | Description
MultinetGetConnectionPerformance | Returns information about the expected performance of a connection to a network resource.
WNetAddConnection | Connects a local device to a network resource. (Provided for compatibility with 16-bit versions of Windows.)
WNetAddConnection2 | Connects a local device to a network resource.
WNetAddConnection3 | Connects a local device to a network resource. This function includes one more parameter than the WNetAddConnection2 function, a handle to a window that the network provider can use as an owner window for dialog boxes.
WNetCancelConnection | Cancels a network connection. (Provided for compatibility with 16-bit versions of Windows.)
WNetCancelConnection2 | Cancels a network connection, providing the ability to update the user profile with information about persistent connections.
WNetConnectionDialog | Starts a general browsing dialog box for connecting to network resources.
WNetConnectionDialog1 | Starts a general browsing dialog box for connecting to network resources, using a CONNECTDLGSTRUCT structure.
WNetDisconnectDialog | Starts a general browsing dialog box for disconnecting from network resources.
WNetDisconnectDialog1 | Starts a general browsing dialog box for disconnecting from network resources, using a DISCDLGSTRUCT structure.
WNetGetConnection | Retrieves the name of the network resource associated with a local device.
WNetGetUniversalName | When given a drive-based path for a network resource, returns a more universal form of the name.
WNetUseConnection | Connects a local device to a network resource; automatically selects an unused local device to redirect to the network resource.

Note The WNetAddConnection and WNetCancelConnection functions are supported for compatibility with Windows for Workgroups. However, new applications should use WNetAddConnection2 or WNetAddConnection3, and WNetCancelConnection2.

Enumeration Functions

Call the following WNet functions to enumerate network resources.

Function | Description
WNetCloseEnum | Ends a network resource enumeration.
WNetEnumResource | Continues an enumeration of network resources started by the WNetOpenEnum function.
WNetOpenEnum | Starts an enumeration of network resources.

Information Functions

Call the following WNet informational and utility functions to retrieve network provider and other information.

Function | Description
WNetGetLastError | Returns the most recent error code set by a WNet function, the one reported by a network provider.
WNetGetNetworkInformation | Returns extended information about a specific network provider.
WNetGetProviderName | Returns the provider name for a specific type of network.
WNetGetResourceInformation | Returns the network provider that owns a resource, and obtains information about the resource type.
WNetGetResourceParent | Returns the parent of a network resource.

User Functions

Call the following WNet function to retrieve the name of the user associated with a local device.

Function | Description
WNetGetUser | Returns the current default user name, or the user name that established the connection.

Many of the WNet functions use a NETRESOURCE structure to store information about a network resource.


Windows Networking Operations

An application can use the WNet functions to browse, add, or cancel network connections anywhere in the network hierarchy.

A persistent connection is a network connection that the system automatically restores when the user logs on. You can call the WNetAddConnection2 (or WNetAddConnection3) and WNetCancelConnection2 functions to control whether a network connection is persistent from one session to the next.

To find the default user name or the user name used to establish a network connection, call the WNetGetUser function.

In addition to calling the WNet functions, a process can also use mailslots and named pipes to communicate with another process. For more information, see Mailslots and Pipes.


Using Windows Networking

The WNet functions enable your application to query and control network connections directly, or to give direct control of the network connections to the user.

The following topics describe how to use the WNet functions in your application on Windows NT/Windows 2000.

  • Using the connections dialog box
  • Enumerating network resources
  • Adding a network connection
  • Assigning a drive to a share
  • Determining the location of a share
  • Retrieving the connection name
  • Retrieving the user name
  • Canceling a network connection
  • Retrieving information about a network resource
  • Retrieving network errors


Using the Connections Dialog Box

Windows NT/Windows 2000

The WNetConnectionDialog function creates a dialog box that allows the user to browse and connect to network resources. You can also call the WNetConnectionDialog1 function to create a connections dialog box. WNetConnectionDialog1 requires a CONNECTDLGSTRUCT structure.

The WNetDisconnectDialog function creates a dialog box that allows the user to disconnect from network resources.

The following code sample demonstrates how to call the WNetConnectionDialog function to create a dialog box that displays disk resources. If the call fails, the sample calls an application-defined error handler.

DWORD dwResult;
//
// Call the WNetConnectionDialog function.
//
dwResult = WNetConnectionDialog(hwnd, RESOURCETYPE_DISK);
//
// Call an application-defined error handler
//  to process errors.
//
if(dwResult != NO_ERROR)
{
    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetConnectionDialog");
    return FALSE;
}

For more information about using an application-defined error handler, see Retrieving Network Errors.


Enumerating Network Resources

Windows NT/Windows 2000

To begin the enumeration of a network container resource, your application should perform the following steps:

  1. Pass the address of a NETRESOURCE structure that represents the resource to the WNetOpenEnum function.
  2. Allocate a buffer large enough to hold the array of NETRESOURCE structures that the WNetEnumResource function returns, plus the strings to which their members point.
  3. Pass the resource handle returned by WNetOpenEnum to the WNetEnumResource function.
  4. Close the resource handle when it is no longer needed by calling the WNetCloseEnum function.

You can continue enumerating a container resource described in the array of NETRESOURCE structures retrieved by WNetEnumResource. If the dwUsage member of the NETRESOURCE structure is equal to RESOURCEUSAGE_CONTAINER, pass the address of the structure to the WNetOpenEnum function to open the container and continue the enumeration. If dwUsage is equal to RESOURCEUSAGE_CONNECTABLE, the application can pass the structure's address to the WNetAddConnection2 function or the WNetAddConnection3 function to connect to the resource.

The following example illustrates an application-defined function (EnumerateFunc) that enumerates all the resources on a network. The sample specifies NULL for the pointer to the NETRESOURCE structure because when WNetOpenEnum receives a NULL pointer, it retrieves a handle to the root of the network.

First the sample calls the WNetOpenEnum function to begin the enumeration. The sample calls the GlobalAlloc function to allocate the required buffer, and the ZeroMemory function to initialize the buffer with zeroes. Then the sample calls the WNetEnumResource function to continue the enumeration. Whenever the dwUsage member of a NETRESOURCE structure retrieved by WNetEnumResource is equal to RESOURCEUSAGE_CONTAINER, the EnumerateFunc function calls itself recursively and uses a pointer to that structure in its call to WNetOpenEnum. Finally, the sample calls the GlobalFree function to free the allocated memory, and the WNetCloseEnum to end the enumeration. EnumerateFunc calls an application-defined error handler to process errors, and the TextOut function for printing.

BOOL WINAPI EnumerateFunc(HWND hwnd,
                          HDC hdc,
                          LPNETRESOURCE lpnr)
{
  DWORD dwResult, dwResultEnum;
  HANDLE hEnum;
  DWORD cbBuffer = 16384;      // 16K is a good size
  DWORD cEntries = -1;         // enumerate all possible entries
  LPNETRESOURCE lpnrLocal;     // pointer to enumerated structures
  DWORD i;
  //
  // Call the WNetOpenEnum function to begin the enumeration.
  //
  dwResult = WNetOpenEnum(RESOURCE_GLOBALNET, // all network resources
                          RESOURCETYPE_ANY,   // all resources
                          0,        // enumerate all resources
                          lpnr,     // NULL first time the function is called
                          &hEnum);  // handle to the resource

  if (dwResult != NO_ERROR)
  {
    //
    // Process errors with an application-defined error handler.
    //
    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetOpenEnum");
    return FALSE;
  }
  //
  // Call the GlobalAlloc function to allocate resources.
  //
  lpnrLocal = (LPNETRESOURCE) GlobalAlloc(GPTR, cbBuffer);

  do
  {
    //
    // Initialize the buffer.
    //
    ZeroMemory(lpnrLocal, cbBuffer);
    //
    // Call the WNetEnumResource function to continue
    //  the enumeration.
    //
    dwResultEnum = WNetEnumResource(hEnum,      // resource handle
                                    &cEntries,  // defined locally as -1
                                    lpnrLocal,  // LPNETRESOURCE
                                    &cbBuffer); // buffer size
    //
    // If the call succeeds, loop through the structures.
    //
    if (dwResultEnum == NO_ERROR)
    {
      for(i = 0; i < cEntries; i++)
      {
        // Call an application-defined function to
        //  display the contents of the NETRESOURCE structures.
        //
        DisplayStruct(hdc, &lpnrLocal[i]);

        // If the NETRESOURCE structure represents a container resource,
        //  call the EnumerateFunc function recursively.

        if(RESOURCEUSAGE_CONTAINER == (lpnrLocal[i].dwUsage
                                       & RESOURCEUSAGE_CONTAINER))
          if(!EnumerateFunc(hwnd, hdc, &lpnrLocal[i]))
            TextOut(hdc, 10, 10, "EnumerateFunc returned FALSE.", 29);
      }
    }
    // Process errors.
    //
    else if (dwResultEnum != ERROR_NO_MORE_ITEMS)
    {
      NetErrorHandler(hwnd, dwResultEnum, (LPSTR)"WNetEnumResource");
      break;
    }
  }
  //
  // End do.
  //
  while(dwResultEnum != ERROR_NO_MORE_ITEMS);
  //
  // Call the GlobalFree function to free the memory.
  //
  GlobalFree((HGLOBAL)lpnrLocal);
  //
  // Call WNetCloseEnum to end the enumeration.
  //
  dwResult = WNetCloseEnum(hEnum);

  if(dwResult != NO_ERROR)
  {
    //
    // Process errors.
    //
    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetCloseEnum");
    return FALSE;
  }

  return TRUE;
}

For more information about using an application-defined error handler, see Retrieving Network Errors.


Adding a Network Connection

Windows NT/Windows 2000

To make a connection to a network resource described by a NETRESOURCE structure, an application can call the WNetAddConnection2, the WNetAddConnection3, or the WNetUseConnection function. The following example demonstrates use of the WNetAddConnection2 function.

The code sample calls the WNetAddConnection2 function, specifying that the system should update the user's profile with the information, creating a "remembered" or persistent connection. The sample calls an application-defined error handler to process errors, and the TextOut function for printing.

DWORD dwResult;
NETRESOURCE nr;
//
// Call the WNetAddConnection2 function to make the connection,
//   specifying a persistent connection.
//
dwResult = WNetAddConnection2(&nr, // NETRESOURCE from enumeration
    (LPSTR) NULL,                  // no password
    (LPSTR) NULL,                  // logged-in user
    CONNECT_UPDATE_PROFILE);       // update profile with connect information

// Process errors.
//  The local device is already connected to a network resource.
//
if (dwResult == ERROR_ALREADY_ASSIGNED)
{
    TextOut(hdc, 10, 10, "Already connected to specified resource.", 40);
    return FALSE;
}

//  An entry for the local device already exists in the user profile.
//
else if (dwResult == ERROR_DEVICE_ALREADY_REMEMBERED)
{
    TextOut(hdc, 10, 10,
        "Attempted reassignment of remembered device.", 44);
    return FALSE;
}
else if(dwResult != NO_ERROR)
{
    //
    // Call an application-defined error handler.
    //
    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetAddConnection2");
    return FALSE;
}

//
// Otherwise, report a successful connection.
//
TextOut(hdc, 10, 10, "Connected to specified resource.", 32);

The WNetAddConnection function is supported for compatibility with earlier versions of Windows for Workgroups. New applications should call the WNetAddConnection2 function or the WNetAddConnection3 function.

For more information about using an application-defined error handler, see Retrieving Network Errors.


Assigning a Drive to a Share

Windows NT/Windows 2000

The following example demonstrates how to connect a drive letter to a remote server share with a call to the WNetAddConnection2 function. The sample informs the user whether or not the call was successful.

To test the following code sample, perform the following steps:

  1. Change the following lines to valid strings:
    szUserName[32] = "myUserName",
szPassword[32] = "myPassword",
szLocalName[32] = "Q:",
szRemoteName[MAX_PATH] = "\\\\products2\\relsys";
  2. Add the file to a console application called AddConn2.
  3. Link the library MPR.LIB to the compiler list of libraries.
  4. Compile and run the program AddConn2.EXE.
#include <windows.h>
#include <stdio.h>
#include <winnetwk.h>

void main()
{
NETRESOURCE nr;
DWORD res;
TCHAR szUserName[32] = "MyUserName",
    szPassword[32] = "MyPassword",
    szLocalName[32] = "Q:",
    szRemoteName[MAX_PATH] = "\\\\products2\\relsys";
//
// Assign values to the NETRESOURCE structure.
//
nr.dwType = RESOURCETYPE_ANY;
nr.lpLocalName = szLocalName;
nr.lpRemoteName = szRemoteName;
nr.lpProvider = NULL;
//
// Call the WNetAddConnection2 function to assign
//   a drive letter to the share.
//
res = WNetAddConnection2(&nr, szPassword, szUserName, FALSE);
//
// If the call succeeds, inform the user; otherwise,
//  print the error.
//
if(res == NO_ERROR)
  printf("Connection added \n", szRemoteName);
else
  printf("Error: %ld\n", res);
  return;
}


Determining the Location of a Share

Windows NT/Windows 2000

The following example demonstrates how to call the WNetGetUniversalName function to determine the location of a share on a redirected drive.

First the code sample calls the WNetGetUniversalName function, specifying the UNIVERSAL_NAME_INFO information level to retrieve a pointer to a Universal Naming Convention (UNC) name string for the resource. Then the sample calls WNetGetUniversalName a second time, specifying the REMOTE_NAME_INFO information level to retrieve two additional network connection information strings. If the calls are successful, the sample prints the location of the share.

To test the following code sample, perform the following steps:

  1. Name the code sample GetUni.cpp.
  2. Add the sample to a console application called GetUni.
  3. Link the libraries Shell32.lib, Mpr.lib, and NetApi32.lib to the compiler list of libraries.
  4. From the command prompt, change to the GetUni directory.
  5. Compile GetUni.cpp.
  6. Run the file GetUni.exe followed by a drive letter and colon, like this:
    GetUni H:\

#define  STRICT
#include <windows.h>
#include <stdio.h>

#define BUFFSIZE = 1000

void main( int argc, char *argv[] )
{
  DWORD cbBuff = 1000;    // Size of Buffer
  TCHAR szBuff[1000];    // Buffer to receive information
  REMOTE_NAME_INFO  * prni = (REMOTE_NAME_INFO *)   &szBuff;
  // Pointers to head of buffer
  UNIVERSAL_NAME_INFO * puni = (UNIVERSAL_NAME_INFO *) &szBuff;
  DWORD res;

  if((argc < 2) | (lstrcmp(argv[1], "/?") == 0))
  {
    printf("Syntax:  GetUni DrivePathAndFilename\n"
         "Example: GetUni U:\\WINNT\\SYSTEM32\\WSOCK32.DLL\n");
    return;
  }

  // Call the WNetGetUniversalName function specifying the
  //  UNIVERSAL_NAME_INFO_LEVEL option.
  //
  printf("Call WNetGetUniversalName using UNIVERSAL_NAME_INFO_LEVEL.\n");
  if((res = WNetGetUniversalName((LPTSTR)argv[1],
   UNIVERSAL_NAME_INFO_LEVEL,
   //
   //The structure is written to this block of memory.
   //
   (LPVOID) &szBuff,
   &cbBuff)) != NO_ERROR)
    //
    // If the call fails, print the error; otherwise, print
    //  the location of the share,
    //  using the pointer to UNIVERSAL_NAME_INFO_LEVEL.
    //
    printf("Error: %ld\n\n", res);

else
printf("Universal Name: \t%s\n\n",
puni->lpUniversalName);
  //
  // Call the WNetGetUniversalName function,
  //  using the REMOTE_NAME_INFO_LEVEL option.
  //
  printf("Call WNetGetUniversalName using REMOTE_NAME_INFO_LEVEL.\n");
  if((res = WNetGetUniversalName((LPTSTR)argv[1],
     REMOTE_NAME_INFO_LEVEL,
        (LPVOID) &szBuff,    //Structure is written to this block of memory
       &cbBuff)) != NO_ERROR)
    //
    // If the call fails, print the error; otherwise, print
    //  the location of the share, using
    //  the pointer to REMOTE_NAME_INFO_LEVEL.
    //
    printf("Error: %ld\n", res);
  else
    printf("Universal Name: \t%s\n"
         "Connection Name:\t%s\n"
       "Remaining Path: \t%s\n",
          prni->lpUniversalName,
          prni->lpConnectionName,
          prni->lpRemainingPath);
  return;
}


Retrieving the Connection Name

Windows NT/Windows 2000

To retrieve the name of the network resource associated with a local device, an application can call the WNetGetConnection function, as shown in the following example. The sample calls an application-defined error handler to process errors, and the TextOut function for printing.

CHAR szDeviceName[80];
DWORD dwResult, cchBuff = sizeof(szDeviceName);

// Call the WNetGetConnection function.
//
dwResult = WNetGetConnection("z:",
    (LPSTR) szDeviceName,
    &cchBuff);

switch (dwResult)
{
    //
    // Print the connection name or process errors.
    //
    case NO_ERROR:
        TextOut(hdc, 10, 10, (LPSTR) szDeviceName,
            lstrlen((LPSTR) szDeviceName));
        break;
    //
    // The device is not a redirected device.
    //
    case ERROR_NOT_CONNECTED:
        TextOut(hdc, 10, 10, "Device z: not connected.", 24);
    //
    // The device is not currently connected,
    //  but it is a persistent connection.
    //
    case ERROR_CONNECTION_UNAVAIL:
        TextOut(hdc, 10, 10, "Connection unavailable.", 23);
    //
    // Call an application-defined error handler.
    //
    default:
        NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetGetConnection");
        return FALSE;
}

For more information about using an application-defined error handler, see Retrieving Network Errors.


Retrieving the User Name

Windows NT/Windows 2000

To retrieve the name of the user associated either with a local device connected to a network resource or with the name of a network, an application can call the WNetGetUser function. The following example uses the device name to retrieve the name of the user. The sample calls an application-defined error handler to process errors, and the TextOut function for printing.

CHAR szUserName[80];
DWORD dwResult, cchBuff = 80;

// Call the WNetGetUser function.
//
dwResult = WNetGetUser("z:",
    (LPSTR) szUserName,
    &cchBuff);

// If the call succeeds, print the user name.
//
if(dwResult == NO_ERROR)
    TextOut(hdc, 10, 10,
        (LPSTR) szUserName,
        lstrlen((LPSTR) szUserName));

// Call an application-defined error handler.
//
else {
    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetGetUser");
    return FALSE;
}

For more information about using an application-defined error handler, see Retrieving Network Errors.


Canceling a Network Connection

Windows NT/Windows 2000

To cancel a connection to a network resource, an application can call the WNetCancelConnection2 function, as shown in the following example. The call to WNetCancelConnection2 specifies that a network connection should no longer be persistent. The sample calls an application-defined error handler to process errors, and the TextOut function for printing.

DWORD dwResult;

// Call the WNetCancelConnection2 function, specifying
//  that the connection should no longer be a persistent one.
//
dwResult = WNetCancelConnection2("z:",
    CONNECT_UPDATE_PROFILE, // remove connection from profile
    FALSE);                 // fail if open files or jobs

// Process errors.
//  The device is not a local redirected device.
//
if (dwResult == ERROR_NOT_CONNECTED)
{
    TextOut(hdc, 10, 10, "Drive z: not connected.", 23);
    return FALSE;
}

// Call an application-defined error handler.
//
else if(dwResult != NO_ERROR)
{
    NetErrorHandler(hwnd, dwResult, (LPSTR)"WNetCancelConnection2");
    return FALSE;
}
//
// Otherwise, report canceling the connection.
//
TextOut(hdc, 10, 10, "Connection closed for z:.", 25);

The WNetCancelConnection function is supported for compatibility with earlier versions of Windows for Workgroups. For new applications, use WNetCancelConnection2.

For more information about using an application-defined error handler, see Retrieving Network Errors.


Retrieving Information About a Network Resource

Windows NT/Windows 2000

To identify the network provider that owns a resource, an application can call the WNetGetResourceInformation function, as illustrated in the following code sample.

The following sample is a function (CheckServer) that takes a server name as a parameter and returns information about that server. First the function calls the ZeroMemory function to initialize a block of memory to zeroes. Then the sample calls the WNetGetResourceInformation function, specifying a buffer large enough to hold only a NETRESOURCE structure. The routine includes error processing to handle the case when a buffer of this size is insufficient to hold the variable-length strings to which members of the NETRESOURCE structure point. If this error occurs, the sample allocates sufficient memory and calls WNetGetResourceInformation again. Finally, the sample frees the allocated memory.

Note that the sample assumes that the pszServer parameter points to a server name that one of the network providers on the local computer recognizes.

//
// Verify a server on the network.
//
DWORD
CheckServer(
    LPTSTR pszServer
    )
{
    DWORD dwBufferSize = sizeof(NETRESOURCE);
    LPBYTE lpBuffer;                  // buffer
    NETRESOURCE nr;
    LPTSTR pszSystem = NULL;          // variable-length strings
    DWORD dwValue;

    //
    // Fill a block of memory with zeroes; then initialize
    // the NETRESOURCE structure.
    //
    ZeroMemory(nr, sizeof(nr));

    nr.dwScope       = RESOURCE_GLOBALNET;
    nr.dwType        = RESOURCETYPE_ANY;
    nr.lpRemoteName  = pszServer;

    //
    // First call the WNetGetResourceInformation function with
    // memory allocated to hold only a NETRESOURCE structure. This
    // method can succeed if all the NETRESOURCE pointers are NULL.
    // If the call fails because the buffer is too small, allocate
    // a larger buffer.
    //
    lpBuffer = (LPBYTE) malloc( dwBufferSize );

    while ( WNetGetResourceInformation(&nr, lpBuffer, &dwBufferSize,
                &pszSystem) == ERROR_MORE_DATA)
    {
        lpBuffer = (LPBYTE) realloc(lpBuffer, dwBufferSize);
    }

    // Process the contents of the NETRESOURCE structure and the
    // variable-length strings in lpBuffer and set dwValue. When
    // finished, free the memory.

    free(lpBuffer);

    return dwValue;
}


Retrieving Network Errors

Windows NT/Windows 2000

The WNet functions return error codes for compatibility with Windows for Workgroups. For compatibility with the Win32 API, the function also sets the error code value returned by GetLastError.

When one of the WNet functions returns ERROR_EXTENDED_ERROR, an application can call the WNetGetLastError function to retrieve additional information about the error. This information is usually specific to the network provider.

The following example illustrates an application-defined error-handling function (NetErrorHandler). The function takes three arguments: a window handle, the error code returned by one of the WNet functions, and the name of the function that produced the error. If the error code is ERROR_EXTENDED_ERROR, NetErrorHandler calls WNetGetLastError to get extended error information and prints the information. The sample calls the MessageBox function to process messages.

BOOL WINAPI NetErrorHandler(HWND hwnd,
                            DWORD dwErrorCode,
                            LPSTR lpszFunction)
{
    DWORD dwWNetResult, dwLastError;
    CHAR szError[256];
    CHAR szCaption[256];
    CHAR szDescription[256];
    CHAR szProvider[256];

    // The following code performs standard error-handling.

    if (dwErrorCode != ERROR_EXTENDED_ERROR)
    {
        wsprintf((LPSTR) szError, "%s failed; \nResult is %ld",
            lpszFunction, dwErrorCode);
        wsprintf((LPSTR) szCaption, "%s error", lpszFunction);
        MessageBox(hwnd, (LPSTR) szError, (LPSTR) szCaption, MB_OK);
        return TRUE;
    }

    // The following code performs error-handling when the
    //  ERROR_EXTENDED_ERROR return value indicates that the
    //  WNetGetLastError function can retrieve additional information.

    else
    {
        dwWNetResult = WNetGetLastError(&dwLastError, // error code
            (LPSTR) szDescription,  // buffer for error description
            sizeof(szDescription),  // size of error buffer
            (LPSTR) szProvider,     // buffer for provider name
            sizeof(szProvider));    // size of name buffer

        //
        // Process errors.
        //
        if(dwWNetResult != NO_ERROR) {
            wsprintf((LPSTR) szError,
                "WNetGetLastError failed; error %ld", dwWNetResult);
            MessageBox(hwnd, (LPSTR) szError,
                "WNetGetLastError", MB_OK);
            return FALSE;
        }

        //
        // Otherwise, print the additional error information.
        //
        wsprintf((LPSTR) szError,
            "%s failed with code %ld;\n%s",
            (LPSTR) szProvider, dwLastError, (LPSTR) szDescription);
        wsprintf((LPSTR) szCaption, "%s error", lpszFunction);
        MessageBox(hwnd, (LPSTR) szError, (LPSTR) szCaption, MB_OK);
        return TRUE;
    }
}


Windows Networking Reference

The following elements are used in Windows networking:

  • Windows Networking Functions
  • Windows Networking Structures


Windows Networking Functions

The following functions are used in Windows networking:

MultinetGetConnectionPerformance
WNetAddConnection2
WNetAddConnection3
WNetCancelConnection
WNetCancelConnection2
WNetCloseEnum
WNetConnectionDialog
WNetConnectionDialog1
WNetDisconnectDialog
WNetDisconnectDialog1
WNetEnumResource
WNetGetConnection
WNetGetLastError
WNetGetNetworkInformation
WNetGetProviderName
WNetGetResourceInformation
WNetGetResourceParent
WNetGetUniversalName
WNetGetUser
WNetOpenEnum
WNetUseConnection

Obsolete Functions

The following function is provided only for compatibility with 16-bit versions of Windows:

WNetAddConnection


MultinetGetConnectionPerformance

The MultinetGetConnectionPerformance function returns information about the expected performance of a connection used to access a network resource. The function returns the information in a NETCONNECTINFOSTRUCT structure.

Note that the MultinetGetConnectionPerformance function can be used only to request information for a local device that is redirected to a network resource, or for a network resource to which there is currently a connection.

DWORD MultinetGetConnectionPerformance(
  LPNETRESOURCE lpNetResource,                   // network resource
  LPNETCONNECTINFOSTRUCT lpNetConnectInfoStruct  // data buffer
);

Parameters

lpNetResource
[in] Pointer to a NETRESOURCE structure that specifies the network resource. The following members have specific meanings in this context.
Member | Meaning
lpLocalName Pointer to a buffer that specifies a local device, such as "F:" or "LPT1", that is redirected to a network resource to be queried.

If this member is NULL or an empty string, the network resource is specified in the lpRemoteName member. If this flag specifies a local device, lpRemoteName is ignored.
lpRemoteName | Pointer to a network resource to query. The resource must currently have an established connection. For example, if the resource is a file on a file server, then having the file open will ensure the connection.
lpProvider Usually set to NULL, but can be a pointer to the owner (provider) of the resource if the network on which the resource resides is known.

If the lpProvider member is not NULL, the system attempts to return information only about the named network.

lpNetConnectInfoStruct
[out] Pointer to the NETCONNECTINFOSTRUCT structure that receives the data.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one or more of the following error values.

Value | Meaning
ERROR_NOT_SUPPORTED | The network resource does not supply this information.
ERROR_NOT_CONNECTED | The lpLocalName member does not specify a redirected device, or the lpRemoteName member does not specify the name of a resource that is currently connected.
ERROR_NO_NET_OR_BAD_PATH | The operation could not be completed, either because a network component is not started, or because the specified resource name is not recognized.
ERROR_BAD_DEVICE | The local device specified by the lpLocalName member is invalid.
ERROR_BAD_NET_NAME | The resource specified by the lpRemoteName member was not recognized by any network.
ERROR_INVALID_PARAMETER | Either the lpNetConnectInfoStruct parameter does not point to a NETCONNECTINFOSTRUCT structure in which the cbStructure member is filled with the structure size, or both the lpLocalName and lpRemoteName members are not specified.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call WNetGetLastError.

Remarks

The information returned by the MultinetGetConnectionPerformance function is an estimate only. Network traffic and routing can affect the accuracy of the results returned.

A typical way to use this function would be to open a file on a network server (which would ensure that there is a connection to the file), call this function, and use the results to make decisions about how to manage file I/O. For example, you can decide whether to read the entire file into a temporary file on the client or directly access the file on the server.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, NETCONNECTINFOSTRUCT, NETRESOURCE


WNetAddConnection

The WNetAddConnection function enables the calling application to connect a local device to a network resource. A successful connection is persistent, meaning that the system automatically restores the connection during subsequent logon operations.

Note This function is provided only for compatibility with 16-bit versions of Windows. Win32-based applications should call the WNetAddConnection2 or the WNetAddConnection3 function.

DWORD WNetAddConnection(
  LPCTSTR lpRemoteName, // network device name
  LPCTSTR lpPassword,   // password
  LPCTSTR lpLocalName   // local device name
);

Parameters

lpRemoteName
[in] Pointer to a constant null-terminated string that specifies the network resource to connect to.
lpPassword
[in] Pointer to a constant null-terminated string that specifies the password to be used to make a connection. This parameter is usually the password associated with the current user.

If this parameter is NULL, the default password is used. If the string is empty, no password is used.

Windows 95/98/Me: This parameter must be NULL or an empty string.

lpLocalName
[in] Pointer to a constant null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1". The string is treated in a case-insensitive manner. If the string is NULL, a connection to the network resource is made without redirecting the local device.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | Access is denied.
ERROR_ALREADY_ASSIGNED | The device specified in the lpLocalName parameter is already connected.
ERROR_BAD_DEV_TYPE | The device type and the resource type do not match.
ERROR_BAD_DEVICE | The value specified in the lpLocalName parameter is invalid.
ERROR_BAD_NET_NAME | The value specified in the lpRemoteName parameter is not valid or cannot be located.
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED | An entry for the device specified in the lpLocalName parameter is already in the user profile.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_INVALID_PASSWORD | The specified password is invalid.
ERROR_NO_NET_OR_BAD_PATH | The operation cannot be performed because a network component is not started or because a specified name cannot be used.
ERROR_NO_NETWORK | The network is unavailable.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetAddConnection3, WNetCancelConnection, WNetCancelConnection2, WNetGetConnection


WNetAddConnection2

The WNetAddConnection2 function makes a connection to a network resource. The function can redirect a local device to the network resource.

The WNetAddConnection2 function supersedes the WNetAddConnection function. If you can pass a handle to a window that the provider of network resources can use as an owner window for dialog boxes, call the WNetAddConnection3 function instead.

DWORD WNetAddConnection2(
  LPNETRESOURCE lpNetResource,  // connection details
  LPCTSTR lpPassword,           // password
  LPCTSTR lpUsername,           // user name
  DWORD dwFlags                 // connection options
);

Parameters

lpNetResource
[in] Pointer to a NETRESOURCE structure that specifies details of the proposed connection, such as information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure.
Member | Description
dwType Specifies the type of network resource to connect to.

If the lpLocalName member points to a nonempty string, this member can be equal to RESOURCETYPE_DISK or RESOURCETYPE_PRINT.

If lpLocalName is NULL, or if it points to an empty string, dwType can be equal to RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.

Although this member is required, its information may be ignored by the network service provider.

lpLocalName Points to a null-terminated string that specifies the name of a local device to redirect, such as "F:" or "LPT1". The string is treated in a case-insensitive manner.

If the string is empty, or if lpLocalName is NULL, the function makes a connection to the network resource without redirecting a local device.
lpRemoteName | Points to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length, and must follow the network provider's naming conventions.
lpProvider Points to a null-terminated string that specifies the network provider to connect to.

If lpProvider is NULL, or if it points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by the lpRemoteName member.

If this member is not NULL, the operating system attempts to make a connection only to the named network provider.

You should set this member only if you know the network provider you want to use. Otherwise, let the operating system determine which provider the network name maps to.

The WNetAddConnection2 function ignores the other members of the NETRESOURCE structure.

lpPassword
[in] Pointer to a constant null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by the lpUserName parameter.

If lpPassword points to an empty string, the function does not use a password.

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE value is set in the dwFlags parameter, the function displays a dialog box asking the user to type the password.

Windows 95/98/Me: This parameter must be NULL or an empty string.

lpUsername
[in] Pointer to a constant null-terminated string that specifies a user name for making the connection.

If lpUserName is NULL, the function uses the default user name. (The user context for the process provides the default user name.)

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

Windows 95/98/Me: This parameter must be NULL or an empty string.

dwFlags
[in] Specifies a DWORD value that describes connection options. The following value is currently defined.
Value | Meaning
CONNECT_INTERACTIVE | If this flag is set, the operating system may interact with the user for authentication purposes.
CONNECT_PROMPT | This flag instructs the system not to use any default settings for user names or passwords without offering the user the opportunity to supply an alternative. This flag is ignored unless CONNECT_INTERACTIVE is also set.
CONNECT_REDIRECT This flag forces the redirection of a local device when making the connection.

If the lpLocalName member of NETRESOURCE specifies a local device to redirect, this flag has no effect, because the operating system still attempts to redirect the specified device. When the operating system automatically chooses a local device, the lpAccessName parameter must point to a return buffer and the dwType member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically chosen for redirection only if the network requires a local device to be redirected.
CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on.

The operating system remembers only successful connections that redirect local devices. It does not remember connections that are unsuccessful or deviceless connections. (A deviceless connection occurs when the lpLocalName member is NULL or points to an empty string.)

If this bit flag is clear, the operating system does not automatically restore the connection at logon.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED | The local device specified by the lpLocalName member is already connected to a network resource.
ERROR_BAD_DEV_TYPE | The type of local device and the type of network resource do not match.
ERROR_BAD_DEVICE | The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified by the lpRemoteName member is not acceptable to any network resource provider, either because the resource name is invalid, or because the named resource cannot be located.
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_BAD_PROVIDER | The value specified by the lpProvider member does not match any provider.
ERROR_BUSY | The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED | The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers, or by a called resource.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED | An entry for the device specified by lpLocalName is already in the user profile.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Call the WNetGetLastError function to obtain a description of the error.
ERROR_INVALID_PASSWORD | The specified password is invalid and the CONNECT_INTERACTIVE flag is not set.
ERROR_NO_NET_OR_BAD_PATH | The operation cannot be performed because a network component is not started or because a specified name cannot be used.
ERROR_NO_NETWORK | The network is unavailable.

Remarks

For a code sample that illustrates how to make a connection to a network resource using the WNetAddConnection2 function, see Adding a Network Connection. For an example that demonstrates how to use the WNetAddConnection2 function to connect a drive letter to a remote share on a server, see Assigning a Drive to a Share.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection3, WNetCancelConnection2, WNetGetConnection, NETRESOURCE


WNetAddConnection3

The WNetAddConnection3 function makes a connection to a network resource. The function can redirect a local device to the network resource.

The WNetAddConnection3 function is similar to the WNetAddConnection2 function. The main difference is that WNetAddConnection3 has an additional parameter, a handle to a window that the provider of network resources can use as an owner window for dialog boxes. The WNetAddConnection2 function and the WNetAddConnection3 function supersede the WNetAddConnection function.

DWORD WNetAddConnection3(
  HWND hwndOwner,               // owner window
  LPNETRESOURCE lpNetResource,  // connection details
  LPTSTR lpPassword,            // password string
  LPTSTR lpUserName,            // user name string
  DWORD dwFlags                 // connection options
);

Parameters

hwndOwner
[in] Specifies the handle to a window that the provider of network resources can use as an owner window for dialog boxes. Use this parameter if you set the CONNECT_INTERACTIVE value in the dwFlags parameter.

The hwndOwner parameter can be NULL. If it is, a call to WNetAddConnection3 is equivalent to calling the WNetAddConnection2 function.

lpNetResource
[in] Pointer to a NETRESOURCE structure that specifies details of the proposed connection, such as information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure.
Member | Description
dwType Specifies the type of network resource to connect to.

If the lpLocalName member points to a nonempty string, this member can be equal to RESOURCETYPE_DISK or RESOURCETYPE_PRINT.

If lpLocalName is NULL, or if it points to an empty string, dwType can be equal to RESOURCETYPE_DISK, RESOURCETYPE_PRINT, or RESOURCETYPE_ANY.

Although this member is required, its information may be ignored by the network service provider.

lpLocalName Points to a null-terminated string that specifies the name of a local device to redirect, such as "F:" or "LPT1". The string is treated in a case-insensitive manner.

If the string is empty or if lpLocalName is NULL, the function makes a connection to the network resource without redirecting a local device.
lpRemoteName | Points to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length, and must follow the network provider's naming conventions.
lpProvider Points to a null-terminated string that specifies the network provider to connect to.

If lpProvider is NULL, or if it points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by the lpRemoteName member.

If this member is not NULL, the operating system attempts to make a connection only to the named network provider.

You should set this member only if you know which network provider you want to use. Otherwise, let the operating system determine which network provider the network name maps to.

The WNetAddConnection3 function ignores the other members of the NETRESOURCE structure.

lpPassword
[in] Pointer to a null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by the lpUserName parameter.

If lpPassword points to an empty string, the function does not use a password.

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE value is set in the dwFlags parameter, the function displays a dialog box asking the user to type the password.

Windows 95/98/Me: This parameter must be NULL or an empty string.

lpUserName
[in] Pointer to a null-terminated string that specifies a user name for making the connection.

If lpUserName is NULL, the function uses the default user name. (The user context for the process provides the default user name.)

The lpUserName parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

Windows 95/98/Me: This parameter must be NULL or an empty string.

dwFlags
[in] Specifies a DWORD value that describes connection options. The following value is currently defined.
Value | Meaning
CONNECT_INTERACTIVE | If this flag is set, the operating system may interact with the user for authentication purposes.
CONNECT_PROMPT | This flag instructs the system not to use any default settings for user names or passwords without offering the user the opportunity to supply an alternative. This flag is ignored unless CONNECT_INTERACTIVE is also set.
CONNECT_REDIRECT This flag forces the redirection of a local device when making the connection.

If the lpLocalName member of NETRESOURCE specifies a local device to redirect, this flag has no effect, because the operating system still attempts to redirect the specified device. When the operating system automatically chooses a local device, the lpAccessName parameter must point to a return buffer and the dwType member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically chosen for redirection only if the network requires a local device to be redirected.
CONNECT_UPDATE_PROFILE The network resource connection should be remembered.

If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on.

The operating system remembers only successful connections that redirect local devices. It does not remember connections that are unsuccessful or deviceless connections. (A deviceless connection occurs when the lpLocalName member is NULL or when it points to an empty string.)

If this bit flag is clear, the operating system does not automatically restore the connection at logon.
CONNECT_COMMANDLINE | Whistler: If this flag is set, the operating system prompts the user for authentication using the command line instead of a graphical user interface (GUI). This flag is ignored unless CONNECT_INTERACTIVE is also set.
CONNECT_CMD_SAVECRED | Whistler: If this flag is set, and the operating system prompts for a credential, the credential should be saved by the credential manager. If the credential manager is disabled for the caller's logon session, or if the network provider does not support saving credentials, this flag is ignored. This flag is also ignored unless you set the CONNECT_COMMANDLINE flag.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED | The local device specified by the lpLocalName member is already connected to a network resource.
ERROR_BAD_DEV_TYPE | The type of local device and the type of network resource do not match.
ERROR_BAD_DEVICE | The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified by the lpRemoteName member is not acceptable to any network resource provider, either because the resource name is invalid, or because the named resource cannot be located.
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_BAD_PROVIDER | The value specified by the lpProvider member does not match any provider.
ERROR_BUSY | The router or provider is busy, possibly initializing. The caller should retry.
ERROR_CANCELLED | The attempt to make the connection was cancelled by the user through a dialog box from one of the network resource providers, or by a called resource.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_ALREADY_REMEMBERED | An entry for the device specified by the lpLocalName member is already in the user profile.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Call the WNetGetLastError function to obtain a description of the error.
ERROR_INVALID_PASSWORD | The specified password is invalid and the CONNECT_INTERACTIVE flag is not set.
ERROR_NO_NET_OR_BAD_PATH | The operation cannot be performed because a network component is not started or because a specified name cannot be used.
ERROR_NO_NETWORK | The network is unavailable.

The WNetUseConnection function is similar to the WNetAddConnection3 function. The main difference is that WNetUseConnection can automatically select an unused local device to redirect to the network resource.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, NETRESOURCE, WNetAddConnection2, WNetCancelConnection2, WNetUseConnection, WNetGetConnection


WNetCancelConnection

The WNetCancelConnection function cancels an existing network connection.

The WNetCancelConnection function is provided for compatibility with 16-bit versions of Windows. Win32-based applications should call the WNetCancelConnection2 function.

DWORD WNetCancelConnection(
  LPCTSTR lpName,  // resource name
  BOOL fForce      // unconditional disconnect option
);

Parameters

lpName
[in] Pointer to a constant null-terminated string that specifies the name of either the redirected local device or the remote network resource to disconnect from.

When this parameter specifies a redirected local device, the function cancels only the specified device redirection. If the parameter specifies a remote network resource, only the connections to remote networks without devices are canceled.

fForce
[in] Specifies whether or not the disconnection should occur if there are open files or jobs on the connection. If this parameter is FALSE, the function fails if there are open files or jobs.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_IN_USE | The device is in use by an active process and cannot be disconnected.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_NOT_CONNECTED | The name specified by the lpName parameter is not a redirected device, or the system is not currently connected to the device specified by the parameter.
ERROR_OPEN_FILES | There are open files, and the fForce parameter is FALSE.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection, WNetAddConnection2, WNetCancelConnection2, WNetGetConnection


WNetCancelConnection2

The WNetCancelConnection2 function cancels an existing network connection. You can also call the function to remove remembered network connections that are not currently connected.

The WNetCancelConnection2 function supersedes the WNetCancelConnection function.

DWORD WNetCancelConnection2(
  LPCTSTR lpName,  // resource name
  DWORD dwFlags,   // connection type
  BOOL fForce      // unconditional disconnect option
);

Parameters

lpName
[in] Pointer to a constant null-terminated string that specifies the name of either the redirected local device or the remote network resource to disconnect from.

If this parameter specifies a redirected local resource, the function cancels only the specified redirection; otherwise, the function cancels all connections to the remote network resource.

dwFlags
[in] Specifies a DWORD value that describes the connection type. The following values are defined.
Value Meaning
0 The system does not update information about the connection.

If the connection was marked as persistent in the registry, the system continues to restore the connection at the next logon. If the connection was not marked as persistent, the function ignores the setting of the CONNECT_UPDATE_PROFILE flag.
CONNECT_UPDATE_PROFILE The system updates the user profile with the information that the connection is no longer a persistent one.

The system will not restore this connection during subsequent logon operations. (Disconnecting resources using remote names has no effect on persistent connections.)

fForce
[in] Specifies a Boolean value that indicates whether the disconnection should occur if there are open files or jobs on the connection. If this parameter is FALSE, the function fails if there are open files or jobs.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BAD_PROFILE | The user profile is in an incorrect format.
ERROR_CANNOT_OPEN_PROFILE | The system is unable to open the user profile to process persistent connections.
ERROR_DEVICE_IN_USE | The device is in use by an active process and cannot be disconnected.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_NOT_CONNECTED | The name specified by the lpName parameter is not a redirected device, or the system is not currently connected to the device specified by the parameter.
ERROR_OPEN_FILES | There are open files, and the fForce parameter is FALSE.

Remarks

For a code sample that illustrates how to cancel a connection to a network resource with a call to the WNetCancelConnection2 function, see Canceling a Network Connection.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetAddConnection3, WNetGetConnection


WNetCloseEnum

The WNetCloseEnum function ends a network resource enumeration started by a call to the WNetOpenEnum function.

DWORD WNetCloseEnum(
  HANDLE hEnum   // handle to enumeration
);

Parameters

hEnum
[in] Specifies a handle that identifies an enumeration instance. This handle must be returned by the WNetOpenEnum function.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_NO_NETWORK | The network is unavailable. (This condition is tested before the handle specified in the hEnum parameter is tested for validity.)
ERROR_INVALID_HANDLE | The hEnum parameter does not specifiy a valid handle.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.

Remarks

For a code sample that illustrates an application-defined function that enumerates all the resources on a network, see Enumerating Network Resources.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetEnumResource, WNetOpenEnum


WNetConnectionDialog

The WNetConnectionDialog function starts a general browsing dialog box for connecting to network resources. The function requires a handle to the owner window for the dialog box.

DWORD WNetConnectionDialog(
  HWND hwnd,     // handle to window owning dialog box
  DWORD dwType   // resource type
);

Parameters

hwnd
[in] Specifies a handle to the owner window for the dialog box.
dwType
[in] Specifies the resource type to allow connections to. This parameter can be the following value.
Value | Meaning
RESOURCETYPE_DISK | Connections to disk resources.

Return Values

If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog box, the function returns –1.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_INVALID_PASSWORD | The specified password is invalid.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to start the dialog box.

Remarks

If the user clicks OK in the dialog box, the requested network connection will have been made when the WNetConnectionDialog function returns.

If the function attempts to make a connection and the network provider returns the message ERROR_INVALID_PASSWORD, the system prompts the user to enter a password. The system uses the new password in another attempt to make the connection.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection3, WNetCancelConnection2, WNetDisconnectDialog


WNetConnectionDialog1

The WNetConnectionDialog1 function brings up a general browsing dialog for connecting to network resources. The function requires a CONNECTDLGSTRUCT to establish the dialog box parameters.

DWORD WNetConnectionDialog1(
  LPCONNECTDLGSTRUCT lpConnDlgStruct // data buffer
);

Parameters

lpConnDlgStruct
[in/out] Pointer to a CONNECTDLGSTRUCT structure. The structure establishes the browsing dialog parameters.

Return Values

If the user cancels the dialog box, the function returns –1. If the function is successful, it returns NO_ERROR. Also, if the call is successful, the dwDevNum member of the CONNECTDLGSTRUCT structure contains the number of the connected device.

Typically this dialog returns an error only if the user cannot enter a dialog session. This is because errors that occur after a dialog session are reported to the user directly. If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | Both the CONNDLG_RO_PATH and the CONNDLG_USE_MRU dialog box options are set. (Dialog box options are specified by the dwFlags member of the CONNECTDLGSTRUCT structure.) -or- Both the CONNDLG_PERSIST and the CONNDLG_NOT_PERSIST dialog box options are set. -or- The CONNDLG_RO_PATH dialog box option is set and the lpRemoteName member of the NETRESOURCE structure does not point to a remote network. (The CONNECTDLGSTRUCT structure points to a NETRESOURCE structure.)
ERROR_BAD_DEV_TYPE | The dwType member of the NETRESOURCE structure is not set to RESOURCETYPE_DISK.
ERROR_BUSY | The network provider is busy (possibly initializing). The caller should retry.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to display the dialog box.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Call WNetGetLastError to obtain a description of the error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, CONNECTDLGSTRUCT, NETRESOURCE, WNetConnectionDialog, WNetDisconnectDialog


WNetDisconnectDialog

The WNetDisconnectDialog function starts a general browsing dialog box for disconnecting from network resources. The function requires a handle to the owner window for the dialog box.

DWORD WNetDisconnectDialog(
  HWND hwnd,     // handle to window owning dialog box
  DWORD dwType   // resource type
);

Parameters

hwnd
[in] Specifies a handle to the owner window for the dialog box.
dwType
[in] Specifies the resource type to disconnect from. This parameter can have the following value.
Value | Meaning
RESOURCETYPE_DISK | Disconnects from disk resources.

Return Values

If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog box, the return value is –1.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to start the dialog box.

Remarks

If the user chooses OK in the dialog box, the requested network disconnection will have been made when the WNetDisconnectDialog function returns.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetCancelConnection2, WNetConnectionDialog, WNetConnectionDialog1


WNetDisconnectDialog1

The WNetDisconnectDialog1 function attempts to disconnect a network resource. If the underlying network returns ERROR_OPEN_FILES, the function prompts the user for confirmation. If there is any error, the function informs the user. The function requires a DISCDLGSTRUCT to specify the parameters for the disconnect attempt.

DWORD WNetDisconnectDialog1(
  LPDISCDLGSTRUCT lpConnDlgStruct  // data buffer
);

Parameters

lpConnDlgStruct
[in] Pointer to a DISCDLGSTRUCT structure. The structure specifies the behavior for the disconnect attempt.

Return Values

If the function succeeds, the return value is NO_ERROR. If the user cancels the dialog box, the return value is –1.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_CANCELLED | When the system prompted the user for a decision about disconnecting, the user elected not to disconnect.
ERROR_OPEN_FILES | Unable to disconnect because the user is actively using the connection.
ERROR_BUSY | The network provider is busy (possibly initializing). The caller should retry.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_NOT_ENOUGH_MEMORY | There is insufficient memory to start the dialog box.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Call the WNetGetLastError function to obtain a description of the error.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetConnectionDialog, WNetConnectionDialog1, DISCDLGSTRUCT, WNetDisconnectDialog


WNetEnumResource

The WNetEnumResource function continues an enumeration of network resources that was started by a call to the WNetOpenEnum function.

DWORD WNetEnumResource(
  HANDLE hEnum,          // handle to enumeration
  LPDWORD lpcCount,      // entries to list
  LPVOID lpBuffer,       // buffer
  LPDWORD lpBufferSize   // buffer size
);

Parameters

hEnum
[in] Specifies a handle that identifies an enumeration instance. This handle must be returned by the WNetOpenEnum function.
lpcCount
[in/out] Pointer to a variable specifying the number of entries requested. If the number requested is –1, the function returns as many entries as possible.

If the function succeeds, on return the variable pointed to by this parameter contains the number of entries actually read.

lpBuffer
[out] Pointer to the buffer that receives the enumeration results. The results are returned as an array of NETRESOURCE structures. Note that the buffer you allocate must be large enough to hold the structures, plus the strings to which their members point. For more information, see the following Remarks section.

The buffer is valid until the next call using the handle specified by the hEnum parameter. The order of NETRESOURCE structures in the array is not predictable.

lpBufferSize
[in/out] Pointer to a variable that specifies the size, in bytes, of the lpBuffer parameter. If the buffer is too small to receive even one entry, this parameter receives the required size of the buffer.

Return Values

If the function succeeds, the return value is one of the following values.

Value | Meaning
NO_ERROR | The enumeration succeeded, and the buffer contains the requested data. The calling application can continue to call WNetEnumResource to complete the enumeration.
ERROR_NO_MORE_ITEMS | There are no more entries. The buffer contents are undefined.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_INVALID_HANDLE | The handle specified by the hEnum parameter is not valid.
ERROR_NO_NETWORK | The network is unavailable. (This condition is tested before hEnum is tested for validity.)
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.

Remarks

The WNetEnumResource function does not enumerate users connected to a share; you can call the NetConnectionEnum function to accomplish this task. To enumerate hidden shares, call the NetShareEnum function.

An application cannot set the lpBuffer parameter to NULL and retrieve the required buffer size from the lpBufferSize parameter. Instead, the application should allocate a buffer of a reasonable size — 16 kilobytes (K) is typical — and use the value of lpBufferSize for error detection.

For a code sample that illustrates an application-defined function that enumerates all the resources on a network, see Enumerating Network Resources.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, NETRESOURCE, WNetCloseEnum, WNetOpenEnum


WNetGetConnection

The WNetGetConnection function retrieves the name of the network resource associated with a local device.

DWORD WNetGetConnection(
  LPCTSTR lpLocalName,  // local name
  LPTSTR lpRemoteName,  // buffer for remote name
  LPDWORD lpnLength     // buffer size
);

Parameters

lpLocalName
[in] Pointer to a constant null-terminated string that specifies the name of the local device to get the network name for.
lpRemoteName
[out] Pointer to a buffer that receives the null-terminated remote name used to make the connection.
lpnLength
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpRemoteName parameter. If the function fails because the buffer is not large enough, this parameter returns the required buffer size.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BAD_DEVICE | The string pointed to by the lpLocalName parameter is invalid.
ERROR_NOT_CONNECTED | The device specified by lpLocalName is not a redirected device. For more information, see the following Remarks section.
ERROR_MORE_DATA | The buffer is too small. The lpnLength parameter points to a variable that contains the required buffer size. More entries are available with subsequent calls.
ERROR_CONNECTION_UNAVAIL | The device is not currently connected, but it is a persistent connection. For more information, see the following Remarks section.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_NO_NET_OR_BAD_PATH | None of the providers recognize the local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.

Remarks

Windows NT/Windows 2000 or later: If the network connection was made using the Microsoft LAN Manager network, and the calling application is running in a different logon session than the application that made the connection, a call to the WNetGetConnection function for the associated local device will fail. The function fails with ERROR_NOT_CONNECTED or ERROR_CONNECTION_UNAVAIL. This is because a connection made using Microsoft LAN Manager is visible only to applications running in the same logon session as the application that made the connection. (To prevent the call to WNetGetConnection from failing it is not sufficient for the application to be running in the user account that created the connection.)

For a code sample that illustrates how to use the WNetGetConnection function to retrieve the name of the network resource associated with a local device, see Retrieving the Connection Name.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetAddConnection3, WNetGetUser


WNetGetLastError

The WNetGetLastError function retrieves the most recent extended error code set by a WNet function. The network provider reported this error code; it will not generally be one of the errors included in the SDK header file WinError.h.

DWORD WNetGetLastError(
  LPDWORD lpError,     // error code
  LPTSTR lpErrorBuf,   // error description buffer
  DWORD nErrorBufSize, // size of description buffer
  LPTSTR lpNameBuf,    // buffer for provider name
  DWORD nNameBufSize   // size of provider name buffer
);

Parameters

lpError
[out] Pointer to the variable that receives the error code reported by the network provider. The error code is specific to the network provider.
lpErrorBuf
[out] Pointer to the buffer that receives the null-terminated string describing the error.
nErrorBufSize
[in] Specifies the size, in characters, of the buffer pointed to by the lpErrorBuf parameter. If the buffer is too small for the error string, the string is truncated but still null-terminated. A buffer of at least 256 characters is recommended.
lpNameBuf
[out] Pointer to the buffer that receives the null-terminated string identifying the network provider that raised the error.
nNameBufSize
[in] Specifies the size, in characters, of the buffer pointed to by the lpNameBuf parameter. If the buffer is too small for the error string, the string is truncated but still null-terminated.

Return Values

If the function succeeds, and it obtains the last error that the network provider reported, the return value is NO_ERROR.

If the caller supplies an invalid buffer, the return value is ERROR_INVALID_ADDRESS.

Remarks

The WNetGetLastError function retrieves errors that are specific to a network provider. You can call WNetGetLastError when a WNet function returns ERROR_EXTENDED_ERROR.

Like the GetLastError function, WNetGetLastError returns extended error information, which is maintained on a per-thread basis. Unlike GetLastError, the WNetGetLastError function can return a string for reporting errors that are not described by any existing error code in WinError.h.

For more information about using an application-defined error handler that calls the WNetGetLastError function, see Retrieving Network Errors.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions


WNetGetNetworkInformation

The WNetGetNetworkInformation function returns extended information about a specific network provider whose name was returned by a previous network enumeration.

DWORD WNetGetNetworkInformation(
  LPCTSTR lpProvider,              // provider name
  LPNETINFOSTRUCT lpNetInfoStruct  // network information
);

Parameters

lpProvider
[in] Pointer to a constant null-terminated string that contains the name of the network provider for which information is required.
lpNetInfoStruct
[out] Pointer to a NETINFOSTRUCT structure. The structure describes characteristics of the network.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BAD_PROVIDER | The lpProvider parameter does not match any running network provider.
ERROR_BAD_VALUE | The cbStructure member of the NETINFOSTRUCT structure does not contain a valid structure size.

Remarks

For a code sample that illustrates an application-defined function that enumerates all the resources on a network, see Enumerating Network Resources.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetProviderName, NETINFOSTRUCT, NETRESOURCE, WNetOpenEnum, WNetEnumResource


WNetGetProviderName

The WNetGetProviderName function obtains the provider name for a specific type of network.

DWORD WNetGetProviderName(
  DWORD dwNetType,       // network type
  LPTSTR lpProviderName, // provider name buffer
  LPDWORD lpBufferSize   // size of buffer
);

Parameters

dwNetType
[in] Specifies the network type that is unique to the network. If two networks claim the same type, the function returns the name of the provider loaded first. Only the high word of the network type is used. If a network reports a subtype in the low word, it is ignored.

You can find a complete list of network types in the header file WinNetwk.h.

lpProviderName
[out] Pointer to a buffer in which to return the network provider name.
lpBufferSize
[in/out] Specifies the size, in characters, of the buffer passed to the function. If the return value is ERROR_MORE_DATA, lpBufferSize returns the buffer size required (in characters) to hold the provider name.

Windows 95/98/Me: The size of the buffer is in bytes, not characters. Also, the buffer must be at least 1 byte long.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_MORE_DATA | The buffer is too small to hold the network provider name.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_INVALID_ADDRESS | The lpProviderName parameter or the lpBufferSize parameter is invalid.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetResourceInformation, WNetGetNetworkInformation, WNetGetUniversalName


WNetGetResourceInformation

When provided with a remote path to a network resource, the WNetGetResourceInformation function identifies the network provider that owns the resource and obtains information about the type of the resource. The function is typically used in conjunction with the WNetGetResourceParent function to parse and interpret a network path typed in by a user.

DWORD WNetGetResourceInformation (
  LPNETRESOURCE lpNetResource, // network resource
  LPVOID lpBuffer,             // information buffer
  LPDWORD lpcbBuffer,          // size of information buffer
  LPTSTR *lplpSystem           // string
);

Parameters

lpNetResource
[in] Pointer to a NETRESOURCE structure that specifies the network resource for which information is required.

The lpRemoteName member of the structure should specify the remote path name of the resource, typically one typed in by a user. The lpProvider and dwType members should also be filled in if known, because this operation can be memory intensive, especially if you do not specify the dwType member. If you do not know the values for these members, you should set them to NULL. All other members of the NETRESOURCE structure are ignored.

lpBuffer
[out] Pointer to the buffer to receive the result. On successful return, the first portion of the buffer is a NETRESOURCE structure representing that portion of the input resource path that is accessed through the WNet functions, rather than through system functions specific to the input resource type. (The remainder of the buffer contains the variable-length strings to which the members of the NETRESOURCE structure point.)

For example, if the input remote resource path is \\server\share\dir1\dir2, then the output NETRESOURCE structure contains information about the resource \\server\share. The \dir1\dir2 portion of the path is accessed through the file I/O functions. The lpRemoteName, lpProvider, dwType, dwDisplayType, and dwUsage members of NETRESOURCE are returned, with all other members set to NULL.

The lpRemoteName member is returned in the same syntax as the one returned from an enumeration by the WNetEnumResource function. This allows the caller to perform a string comparison to determine whether the resource passed to WNetGetResourceInformation is the same as the resource returned by a separate call to WNetEnumResource.

lpcbBuffer
[in/out] Pointer to a location that, on entry, specifies the size, in bytes, of the buffer pointed to by lpBuffer. The buffer you allocate must be large enough to hold the NETRESOURCE structure, plus the strings to which its members point. If the buffer is too small for the result, this location receives the required buffer size, and the function returns ERROR_MORE_DATA.
lplpSystem
[out] If the function returns successfully, this parameter points to a string in the output buffer that specifies the part of the resource that is accessed through system functions. (This applies only to functions specific to the resource type rather than the WNet functions.)

For example, if the input remote resource name is \\server\share\dir1\dir2, the lpRemoteName member of the output NETRESOURCE structure points to \\server\share. Also, the lplpSystem parameter points to \dir1\dir2. Both strings are stored in the buffer pointed to by the lpBuffer parameter.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_BAD_NET_NAME | The input lpRemoteName member is not an existing network resource for any network.
ERROR_BAD_DEV_TYPE | The input dwType member does not match the type of resource specified by the lpRemoteName member.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Call WNetGetLastError to obtain a description of the error.
ERROR_MORE_DATA | The buffer pointed to by the lpBuffer parameter is too small.
ERROR_NO_NETWORK | The network is unavailable.

Remarks

For a code sample that illustrates how to use the WNetGetResourceInformation function, see Retrieving Information About a Network Resource.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetResourceParent, WNetGetProviderName, WNetGetNetworkInformation WNetGetUniversalName


WNetGetResourceParent

The WNetGetResourceParent function returns the parent of a network resource in the network browse hierarchy. Browsing begins at the location of the specified network resource.

Call the WNetGetResourceInformation and WNetGetResourceParent functions to move up the network hierarchy. Call the WNetOpenEnum function to move down the hierarchy.

DWORD WNetGetResourceParent(
  LPNETRESOURCE lpNetResource,  // network resource
  LPVOID lpBuffer,              // buffer
  LPDWORD lpcbBuffer            // buffer size
);

Parameters

lpNetResource
[in] Pointer to a NETRESOURCE structure that specifies the network resource for which the parent name is required.

Specify the members of the input NETRESOURCE structure as follows. The caller typically knows the values to provide for the lpProvider and dwType members after previous calls to WNetGetResourceInformation or WNetGetResourceParent.
Member | Description
dwType | This member should be filled in if known; otherwise, it should be set to NULL.
lpRemoteName | This member should specify the remote name of the network resource whose parent is required.
lpProvider | This member should specify the network provider that owns the resource. This member is required; otherwise, the function could produce incorrect results.

All other members of the NETRESOURCE structure are ignored.

lpBuffer
[out] Pointer to a buffer to receive a single NETRESOURCE structure that represents the parent resource. The function returns the lpRemoteName, lpProvider, dwType, dwDisplayType, and dwUsage members of the structure; all other members are set to NULL.

The lpRemoteName member points to the remote name for the parent resource. This name uses the same syntax as the one returned from an enumeration by the WNetEnumResource function. The caller can perform a string comparison to determine whether the WNetGetResourceParent resource is the same as that returned by WNetEnumResource. If the input resource has no parent on any of the networks, the lpRemoteName member is returned as NULL.

The presence of the RESOURCEUSAGE_CONNECTABLE bit in the dwUsage member indicates that you can connect to the parent resource, but only when it is available on the network.

lpcbBuffer
[in/out] Pointer to a location that, on entry, specifies the size, in bytes, of the buffer pointed to by the lpBuffer parameter. If the buffer is too small to hold the result, this location receives the required buffer size, and the function returns ERROR_MORE_DATA.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user is authenticated to the network, but does not have sufficient permissions (access rights) to perform the operation.
ERROR_BAD_NET_NAME | The input lpRemoteName member is not an existing network resource for any network.
ERROR_BAD_PROVIDER | The input lpProvider member does not match any installed network provider.
ERROR_MORE_DATA | The buffer pointed to by the lpBuffer parameter is too small.
ERROR_NOT_AUTHENTICATED | The caller does not have the necessary permissions to obtain the name of the parent.

Remarks

The WNetGetResourceParent function is typically used in conjunction with the WNetGetResourceInformation function to parse and interpret a network path typed in by a user.

Unlike the WNetGetResourceInformation function, if the resource includes a parent in its syntax, the WNetGetResourceParent function returns the parent, whether or not the resource actually exists. WNetGetResourceParent should typically be used only by applications that display network resources to the user in a hierarchical fashion. The Windows Explorer and the File Open dialog box are two well-known examples of this type of application. Note that no assumptions should be made about the type of resource that will be returned.

You can call the WNetEnumResource, WNetGetResourceInformation, or WNetGetResourceParent function to return information from the NETRESOURCE structure. You can also construct network resource information using the members of the NETRESOURCE structure.

An example of an inappropriate use of WNetGetResourceParent is to determine the name of the domain to which a specified server belongs. The function may happen to return the correct domain name for some networks in which domains appear directly above servers in the browse hierarchy.The function will return incorrect results for other networks.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetResourceInformation, WNetGetProviderName, WNetGetNetworkInformation, WNetGetUniversalName


WNetGetUniversalName

The WNetGetUniversalName function takes a drive-based path for a network resource and returns an information structure that contains a more universal form of the name.

DWORD WNetGetUniversalName(
  LPCTSTR lpLocalPath,  // path for network resource
  DWORD dwInfoLevel,    // level of information
  LPVOID lpBuffer,      // name buffer
  LPDWORD lpBufferSize  // size of buffer
);

Parameters

lpLocalPath
[in] Pointer to a constant null-terminated string that is a drive-based path for a network resource.

For example, if drive H has been mapped to a network drive share, and the network resource of interest is a file named SAMPLE.DOC in the directory \WIN32\EXAMPLES on that share, the drive-based path is H:\WIN32\EXAMPLES\SAMPLE.DOC.

dwInfoLevel
[in] Specifies the type of structure that the function stores in the buffer pointed to by the lpBuffer parameter. This parameter can be one of the following values.
Value | Meaning
UNIVERSAL_NAME_INFO_LEVEL | The function stores a UNIVERSAL_NAME_INFO structure in the buffer.
REMOTE_NAME_INFO_LEVEL | The function stores a REMOTE_NAME_INFO structure in the buffer.

The UNIVERSAL_NAME_INFO structure points to a Universal Naming Convention (UNC) name string.

The REMOTE_NAME_INFO structure points to a UNC name string and two additional connection information strings. For more information, see the following Remarks section.

lpBuffer
[out] Pointer to a buffer that receives the structure specified by the dwInfoLevel parameter.
lpBufferSize
[in/out] Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpBuffer parameter.

If the function succeeds, it sets the variable pointed to by lpBufferSize to the number of bytes stored in the buffer. If the function fails because the buffer is too small, this location receives the required buffer size, and the function returns ERROR_MORE_DATA.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_BAD_DEVICE | The string pointed to by the lpLocalPath parameter is invalid.
ERROR_CONNECTION_UNAVAIL | There is no current connection to the remote device, but there is a remembered (persistent) connection to it.
ERROR_EXTENDED_ERROR | A network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error.
ERROR_MORE_DATA | The buffer pointed to by the lpBuffer parameter is too small. The function sets the variable pointed to by the lpBufferSize parameter to the required buffer size. More entries are available with subsequent calls.
ERROR_NOT_SUPPORTED | The dwInfoLevel parameter is set to UNIVERSAL_NAME_INFO_LEVEL, but the network provider does not support UNC names. (None of the network providers support this function.)
ERROR_NO_NET_OR_BAD_PATH | None of the network providers recognize the local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_NOT_CONNECTED | The device specified by the lpLocalPath parameter is not redirected.

Remarks

A universal form of a local drive-based path identifies a network resource in an unambiguous, computer-independent manner. The name can then be passed to processes on other computers, allowing those processes to obtain access to the resource.

The WNetGetUniversalName function currently supports one universal name form: universal naming convention (UNC) names, which look like the following:

\\servername\sharename\path\file

Using the example from the preceding description of the lpLocalPath parameter, if the shared network drive is on a server named COOLSERVER, and the share name is HOTSHARE, the UNC name for the network resource whose drive-based name is H:\WIN32\EXAMPLES\SAMPLE.DOC would be

\\coolserver\hotshare\win32\examples\sample.doc

The UNIVERSAL_NAME_INFO structure contains a pointer to a UNC name string. The REMOTE_NAME_INFO structure also contains a pointer to a UNC name string as well as pointers to two other useful strings. For example, a process can pass the REMOTE_NAME_INFO structure's lpszConnectionInfo member to the WNetAddConnection2 function to connect a local device to the network resource. Then the process can append the string pointed to by the lpszRemainingPath member to the local device string. The resulting string can be passed to Win32 functions that require a drive-based path.

For an example that demonstrates how to use the WNetGetUniversalName function to determine the location of a share on a redirected drive, see Determining the Location of a Share.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, REMOTE_NAME_INFO, UNIVERSAL_NAME_INFO, WNetAddConnection2


WNetGetUser

The WNetGetUser function retrieves the current default user name, or the user name used to establish a network connection.

DWORD WNetGetUser(
  LPCTSTR lpName,     // device or resource name
  LPTSTR lpUserName,  // name buffer
  LPDWORD lpnLength   // buffer size
);

Parameters

lpName
[in] Pointer to a constant null-terminated string that specifies either the name of a local device that has been redirected to a network resource, or the remote name of a network resource to which a connection has been made without redirecting a local device.

If this parameter is NULL, the system returns the name of the current user for the process.

lpUserName
[out] Pointer to a buffer that receives the null-terminated user name.
lpnLength
[in/out] Pointer to a variable that specifies the size, in characters, of the buffer pointed to by the lpUserName parameter. If the call fails because the buffer is not large enough, this variable contains the required buffer size.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_NOT_CONNECTED | The device specified by the lpName parameter is not a redirected device or a connected network name.
ERROR_MORE_DATA | More entries are available with subsequent calls.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_NO_NET_OR_BAD_PATH | None of the providers recognize the local name as having a connection. However, the network is not available for at least one provider to whom the connection may belong.

Remarks

For a code sample that illustrates how to use the WNetGetUser function to retrieve the name of the user associated with a local device, see Retrieving the User Name.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetGetConnection


WNetOpenEnum

The WNetOpenEnum function starts an enumeration of network resources or existing connections. You can continue the enumeration by calling the WNetEnumResource function.

DWORD WNetOpenEnum(
  DWORD dwScope,                // scope of enumeration
  DWORD dwType,                 // resource types to list
  DWORD dwUsage,                // resource usage to list
  LPNETRESOURCE lpNetResource,  // resource structure
  LPHANDLE lphEnum              // enumeration handle buffer
);

Parameters

dwScope
[in] Specifies the scope of the enumeration. This parameter can be one of the following values.
Value | Meaning
RESOURCE_CONNECTED | Enumerate all currently connected resources. The function ignores the dwUsage parameter. For more information, see the following Remarks section.
RESOURCE_CONTEXT | Enumerate only resources in the network context of the caller. Specify this value for a Network Neighborhood view. The function ignores the dwUsage parameter.
RESOURCE_GLOBALNET | Enumerate all resources on the network.
RESOURCE_REMEMBERED | Enumerate all remembered (persistent) connections. The function ignores the dwUsage parameter.

dwType
[in] Specifies the resource types to enumerate. This parameter can be a combination of the following values.
Value | Meaning
RESOURCETYPE_ANY | All resources. This value cannot be combined with RESOURCETYPE_DISK or RESOURCETYPE_PRINT.
RESOURCETYPE_DISK | All disk resources.
RESOURCETYPE_PRINT | All print resources.

If a network provider cannot distinguish between print and disk resources, it can enumerate all resources.

dwUsage
[in] Specifies the resource usage type to enumerate. This parameter can be a combination of the following values.
Value | Meaning
0 | All resources.
RESOURCEUSAGE_CONNECTABLE | All connectable resources.
RESOURCEUSAGE_CONTAINER | All container resources.
RESOURCEUSAGE_ATTACHED | Setting this value forces WNetOpenEnum to fail if the user is not authenticated. The function fails even if the network allows enumeration without authentication.
RESOURCEUSAGE_ALL | Setting this value is equivalent to setting RESOURCEUSAGE_CONNECTABLE, RESOURCEUSAGE_CONTAINER, and RESOURCEUSAGE_ATTACHED.

This parameter is ignored unless the dwScope parameter is equal to RESOURCE_GLOBALNET. For more information, see the following Remarks section.

lpNetResource
[in] Pointer to a NETRESOURCE structure that specifies the container to enumerate. If the dwScope parameter is not RESOURCE_GLOBALNET, this parameter must be NULL.

If this parameter is NULL, the root of the network is assumed. (The system organizes a network as a hierarchy; the root is the topmost container in the network.)

If this parameter is not NULL, it must point to a NETRESOURCE structure. This structure can be filled in by the application or it can be returned by a call to the WNetEnumResource function. The NETRESOURCE structure must specify a container resource; that is, the RESOURCEUSAGE_CONTAINER value must be specified in the dwUsage parameter.

To enumerate all network resources, an application can begin the enumeration by calling WNetOpenEnum with the lpNetResource parameter set to NULL, and then use the returned handle to call WNetEnumResource to enumerate resources. If one of the resources in the NETRESOURCE array returned by the WNetEnumResource function is a container resource, you can call WNetOpenEnum to open the resource for further enumeration.

lphEnum
[out] Pointer to an enumeration handle that can be used in a subsequent call to WNetEnumResource.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_NOT_CONTAINER | The lpNetResource parameter does not point to a container.
ERROR_INVALID_PARAMETER | Either the dwScope or the dwType parameter is invalid, or there is an invalid combination of parameters.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.

Remarks

Windows NT/Windows 2000 or later: If the dwScope parameter is equal to RESOURCE_CONNECTED, a network connection made using the Microsoft LAN Manager network is omitted from the enumeration if the connection was made by an application running in a different logon session than the application calling the WNetOpenEnum function. This is because connections made using Microsoft LAN Manager are visible only to applications running in the same logon session as the application that made the connection. (To include the connection in the enumeration, it is not sufficient for the application to be running in the user account that created the connection.)

The exact interpretation of RESOURCE_CONTEXT in the dwScope parameter depends on the networks installed on the machine.

The WNetOpenEnum function is used to begin enumeration of the resources in a single container. The following examples show the hierarchical structure of a Microsoft LAN Manager network and a Novell Netware network and identify the containers.

LanMan (container, in this case the provider)
  ACCOUNTING (container, in this case the domain)
    \\ACCTSPAY (container, in this case the server)
      PAYFILES (disk)
      LASERJET (print)

Netware (container, in this case the provider)
  MARKETING (container, in this case the server)
    SYS (disk, first one on any Netware server)
    ANOTHERVOLUME (disk)
    LASERJET (print)

For a code sample that illustrates an application-defined function that enumerates all the resources on a network, see Enumerating Network Resources.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, NETRESOURCE, WNetCloseEnum, WNetEnumResource


WNetUseConnection

The WNetUseConnection function makes a connection to a network resource. The function can redirect a local device to a network resource.

The WNetUseConnection function is similar to the WNetAddConnection3 function. The main difference is that WNetUseConnection can automatically select an unused local device to redirect to the network resource.

Windows NT/2000 or later: The parameter order is as follows.

DWORD WNetUseConnection(
  HWND hwndOwner,              // owner window
  LPNETRESOURCE lpNetResource, // connection details
  LPCTSTR lpUserID,            // user
  LPCTSTR lpPassword,          // password
  DWORD dwFlags,               // connection options
  LPTSTR lpAccessName,         // buffer for system requests
  LPDWORD lpBufferSize,        // buffer size
  LPDWORD lpResult             // receives connection information
);

Windows 95/98/Me: The lpUserID and lpPassword parameters are in reverse order from the order used on Windows NT/Windows 2000. Therefore, the parameter order is as follows.

DWORD WNetUseConnection(
  HWND hwndOwner,
  LPNETRESOURCE lpNetResource,
  LPCTSTR lpPassword,
  LPCTSTR lpUserID,
  DWORD dwFlags,
  LPTSTR lpAccessName,
  LPDWORD lpBufferSize,
  LPDWORD lpResult
);

Parameters

hwndOwner
[in] Specifies the handle to a window that the provider of network resources can use as an owner window for dialog boxes. Use this parameter if you set the CONNECT_INTERACTIVE value in the dwFlags parameter.
lpNetResource
[in] Pointer to a NETRESOURCE structure that specifies details of the proposed connection. The structure contains information about the network resource, the local device, and the network resource provider.

You must specify the following members of the NETRESOURCE structure.
Member | Description
dwType Specifies the type of resource to connect to.

It is most efficient to specify a resource type in this member, such as RESOURCETYPE_DISK or RESOURCETYPE_PRINT. However, if the lpLocalName member is NULL, or if it points to an empty string and CONNECT_REDIRECT is not set, dwType can be RESOURCETYPE_ANY.

This method works only if the function does not automatically choose a device to redirect to the network resource.

Although this member is required, its information may be ignored by the network service provider.

lpLocalName Pointer to a null-terminated string that specifies the name of a local device to be redirected, such as "F:" or "LPT1". The string is treated in a case-insensitive manner.

If the string is empty, or if lpLocalName is NULL, a connection to the network occurs without redirection.

If the CONNECT_REDIRECT value is set in the dwFlags parameter, or if the network requires a redirected local device, the function chooses a local device to redirect and returns the name of the device in the lpAccessName parameter.

lpRemoteName | Pointer to a null-terminated string that specifies the network resource to connect to. The string can be up to MAX_PATH characters in length, and it must follow the network provider's naming conventions.
lpProvider Pointer to a null-terminated string that specifies the network provider to connect to. If lpProvider is NULL, or if it points to an empty string, the operating system attempts to determine the correct provider by parsing the string pointed to by the lpRemoteName member.

If this member is not NULL, the operating system attempts to make a connection only to the named network provider.

You should set this member only if you know the network provider you want to use. Otherwise, let the operating system determine which provider the network name maps to.

The WNetUseConnection function ignores the other members of the NETRESOURCE structure. For more information, see the descriptions following for the dwFlags parameter.

lpUserID
[in] Pointer to a constant null-terminated string that specifies a user name for making the connection.

If lpUserID is NULL, the function uses the default user name. (The user context for the process provides the default user name.)

The lpUserID parameter is specified when users want to connect to a network resource for which they have been assigned a user name or account other than the default user name or account.

The user-name string represents a security context. It may be specific to a network provider.

lpPassword
[in] Pointer to a constant null-terminated string that specifies a password to be used in making the network connection.

If lpPassword is NULL, the function uses the current default password associated with the user specified by lpUserID.

If lpPassword points to an empty string, the function does not use a password.

If the connection fails because of an invalid password and the CONNECT_INTERACTIVE value is set in the dwFlags parameter, the function displays a dialog box asking the user to type the password.

dwFlags
[in] Specifies a DWORD value that contains a set of bit flags describing the connection. This parameter can be any combination of the following values.
Value | Meaning
CONNECT_INTERACTIVE | If this flag is set, the operating system may interact with the user for authentication purposes.
CONNECT_PROMPT | This flag instructs the system not to use any default settings for user names or passwords without offering the user the opportunity to supply an alternative. This flag is ignored unless CONNECT_INTERACTIVE is also set.
CONNECT_REDIRECT This flag forces the redirection of a local device when making the connection.

If the lpLocalName member of NETRESOURCE specifies a local device to redirect, this flag has no effect, because the operating system still attempts to redirect the specified device. When the operating system automatically chooses a local device, the lpAccessName parameter must point to a return buffer and the dwType member must not be equal to RESOURCETYPE_ANY.

If this flag is not set, a local device is automatically chosen for redirection only if the network requires a local device to be redirected.
CONNECT_UPDATE_PROFILE This flag instructs the operating system to store the network resource connection.

If this bit flag is set, the operating system automatically attempts to restore the connection when the user logs on. The system remembers only successful connections that redirect local devices. It does not remember connections that are unsuccessful or deviceless connections. (A deviceless connection occurs when lpLocalName is NULL or when it points to an empty string.)

If this bit flag is clear, the operating system does not automatically restore the connection at logon.
CONNECT_COMMANDLINE | Whistler: If this flag is set, the operating system prompts the user for authentication using the command line instead of a graphical user interface (GUI). This flag is ignored unless CONNECT_INTERACTIVE is also set.
CONNECT_CMD_SAVECRED | Whistler: If this flag is set, and the operating system prompts for a credential, the credential should be saved by the credential manager. If the credential manager is disabled for the caller's logon session, or if the network provider does not support saving credentials, this flag is ignored. This flag is also ignored unless you set the CONNECT_COMMANDLINE flag.

lpAccessName
[out] Pointer to a buffer that receives system requests on the connection.

If the lpLocalName member of the NETRESOURCE structure specifies a local device, this buffer is optional, and will have the local device name copied into it. If lpLocalName does not specify a device and the network requires a local device redirection, or if the CONNECT_REDIRECT value is set, this buffer is required and the name of the redirected local device is returned here.

Otherwise, the name copied into the buffer is that of a remote resource. If specified, this buffer must be at least as large as the string pointed to by the lpRemoteName member.

lpBufferSize
[in/out] Pointer to a variable that specifies the size, in characters, of the lpAccessName buffer. If the call fails because the buffer is not large enough, the function returns the required buffer size in this location.
lpResult
[out] Pointer to a variable that receives additional information about the connection. This parameter can be the following value.
Value | Meaning
CONNECT_LOCALDRIVE | If this flag is set, the connection was made using a local device redirection. If the lpAccessName parameter points to a buffer, the local device name is copied to the buffer.

Return Values

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | Access to the network resource was denied.
ERROR_ALREADY_ASSIGNED | The local device specified by the lpLocalName member is already connected to a network resource.
ERROR_BAD_DEVICE | The value specified by lpLocalName is invalid.
ERROR_BAD_NET_NAME | The value specified by the lpRemoteName member is not acceptable to any network resource provider because the resource name is invalid, or because the named resource cannot be located.
ERROR_BAD_PROVIDER | The value specified by the lpProvider member does not match any provider.
ERROR_CANCELLED | The attempt to make the connection was canceled by the user through a dialog box from one of the network resource providers, or by a called resource.
ERROR_EXTENDED_ERROR | A network-specific error occurred. To obtain a description of the error, call the WNetGetLastError function.
ERROR_INVALID_ADDRESS | The caller passed in a pointer to a buffer that could not be accessed.
ERROR_INVALID_PARAMETER This error is a result of one of the following conditions:
  1. The lpRemoteName member is NULL. In addition, lpAccessName is not NULL, but lpBufferSize is either NULL or points to zero.
  2. The dwType member is neither RESOURCETYPE_DISK nor RESOURCETYPE_PRINT. In addition, either CONNECT_REDIRECT is set in dwFlags and lpLocalName is NULL, or the connection is to a network that requires the redirecting of a local device.
ERROR_INVALID_PASSWORD | The specified password is invalid and the CONNECT_INTERACTIVE flag is not set.
ERROR_MORE_DATA The lpAccessName buffer is too small.

If a local device is redirected, the buffer needs to be large enough to contain the local device name. Otherwise, the buffer needs to be large enough to contain either the string pointed to by lpRemoteName, or the name of the connectable resource whose alias is pointed to by lpRemoteName. If this error is returned, then no connection has been made.
ERROR_NO_MORE_ITEMS | The operating system cannot automatically choose a local redirection because all the valid local devices are in use.
ERROR_NO_NET_OR_BAD_PATH | The operation could not be completed, either because a network component is not started, or because the specified resource name is not recognized.
ERROR_NO_NETWORK | The network is unavailable.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Library: Use Mpr.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Windows Networking (WNet) Overview, Windows Networking Functions, WNetAddConnection2, WNetAddConnection3, WnetCancelConnection, WNetGetConnection


Windows Networking Structures

The following structures are used in Windows networking:

CONNECTDLGSTRUCT
DISCDLGSTRUCT
NETCONNECTINFOSTRUCT
NETINFOSTRUCT
NETRESOURCE
REMOTE_NAME_INFO
UNIVERSAL_NAME_INFO


CONNECTDLGSTRUCT

The CONNECTDLGSTRUCT structure is used by the WNetConnectionDialog1 function to establish browsing dialog box parameters.

typedef struct {
  DWORD cbStructure;
  HWND hwndOwner;
  LPNETRESOURCE lpConnRes;
  DWORD dwFlags;
  DWORD dwDevNum;
} CONNECTDLGSTRUCT, *LPCONNECTDLGSTRUCT;

Members

cbStructure
Specifies, in bytes, the size of the CONNECTDLGSTRUCT structure. The caller must supply this value.
hwndOwner
Specifies a handle to the owner window for the dialog box.
lpConnRes
Pointer to a NETRESOURCE structure.

If the lpRemoteName member of NETRESOURCE is specified, it will be entered into the path field of the dialog box. With the exception of the dwType member, all other members of the NETRESOURCE structure must be set to NULL. The dwType member must be equal to RESOURCETYPE_DISK.
Windows NT/2000 or later: The system does not support the RESOURCETYPE_PRINT flag for browsing and connecting to print resources.

dwFlags
Specifies a DWORD value that contains a set of bit flags describing variations in the dialog box display. This member can be a combination of the following values.
Value | Meaning
SidTypeUser | The account is a user account.
CONNDLG_RO_PATH Display a read-only path instead of allowing the user to type in a path.

This flag should be set only if the lpRemoteName member of the NETRESOURCE structure pointed to by lpConnRes is not NULL (or an empty string), and the CONNDLG_USE_MRU flag is not set.

CONNDLG_CONN_POINT | Internal flag. Do not use.
CONNDLG_USE_MRU | Enter the most recently used paths into the combination box. Set this value to simulate the WNetConnectionDialog function.
CONNDLG_HIDE_BOX | Show the check box allowing the user to restore the connection at logon.
CONNDLG_PERSIST | Restore the connection at logon.
CONNDLG_NOT_PERSIST | Do not restore the connection at logon.

For more information, see the following Remarks section.

dwDevNum
If the call to the WNetConnectionDialog1 function is successful, this member returns the number of the connected device. The value is 1 for A:, 2 for B:, 3 for C:, and so on. If the user made a deviceless connection, the value is –1.

Remarks

If neither the CONNDLG_RO_PATH nor the CONNDLG_USE_MRU flag is set, and the lpRemoteName member of the NETRESOURCE structure does not specify a remote path, the request defaults to the CONNDLG_RO_PATH dialog display type.

The CONNDLG_PERSIST and CONNDLG_NOT_PERSIST values cannot both be set. If neither is set, the dialog box defaults to the last option that was selected in this dialog box for the particular type of device connection.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, NETRESOURCE, WNetConnectionDialog1


DISCDLGSTRUCT

The DISCDLGSTRUCT structure is used in the WNetDisconnectDialog1 function. The structure contains required information for the disconnect attempt.

typedef struct _DISCDLGSTRUCT{
  DWORD cbStructure;
  HWND hwndOwner;
  LPTSTR lpLocalName;
  LPTSTR lpRemoteName;
  DWORD dwFlags;
} DISCDLGSTRUCT, *LPDISCDLGSTRUCT;

Members

cbStructure
Specifies the size, in bytes, of the DISCDLGSTRUCT structure. The caller must supply this value.
hwndOwner
Specifies a handle to the owner window of the dialog box.
lpLocalName
Pointer to a null-terminated character string that specifies the local device name that is redirected to the network resource, such as "F:" or "LPT1".
lpRemoteName
Pointer to a null-terminated character string that specifies the name of the network resource to disconnect. This member can be NULL if the lpLocalName member is specified. When lpLocalName is specified, the connection to the network resource redirected from lpLocalName is disconnected.
dwFlags
Specifies a DWORD value that contains a set of bit flags describing the connection. This member can be a combination of the following values.
Value | Meaning
DISC_UPDATE_PROFILE | If this value is set, the specified connection is no longer a persistent one (automatically restored every time the user logs on). This flag is valid only if the lpLocalName member specifies a local device.
DISC_NO_FORCE If this value is not set, the system applies force when attempting to disconnect from the network resource.

This situation typically occurs when the user has files open over the connection. This value means that the user will be informed if there are open files on the connection, and asked if he or she still wants to disconnect. If the user wants to proceed, the disconnect procedure re-attempts with additional force.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetDisconnectDialog1


NETCONNECTINFOSTRUCT

The NETCONNECTINFOSTRUCT structure contains information about the expected performance of a connection used to access a network resource. The structure is used in the MultinetGetConnectionPerformance function.

typedef struct _NETCONNECTINFOSTRUCT{
  DWORD cbStructure;
  DWORD dwFlags;
  DWORD dwSpeed;
  DWORD dwDelay;
  DWORD dwOptDataSize;
} NETCONNECTINFOSTRUCT, *LPNETCONNECTINFOSTRUCT;

Members

cbStructure
Specifies the size, in bytes, of the NETCONNECTINFOSTRUCT structure. The caller must supply this value.
dwFlags
Specifies a DWORD value that contains a set of bit flags describing the connection. This member can be one or more of the following values.
Value | Meaning
WNCON_FORNETCARD In the absence of information about the actual connection, the information returned applies to the performance of the network card.

If this flag is not set, information is being returned for the current connection with the resource, with any routing degradation taken into consideration.
WNCON_NOTROUTED The connection is not being routed.

If this flag is not set, the connection may be going through routers that limit performance. Consequently, if WNCON_FORNETCARD is set, actual performance may be much less than the information returned.

WNCON_SLOWLINK | The connection is over a medium that is typically slow (for example, over a modem using a normal quality phone line). You should not set the WNCON_SLOWLINK bit if the dwSpeed member is set to a nonzero value.
WNCON_DYNAMIC | Some of the information returned is calculated dynamically, so reissuing this request may return different (and more current) information.

dwSpeed
Specifies a DWORD value that contains the speed of the media to the network resource in units of 100 bits per second (bps).

For example, a 1200 baud point-to-point link returns 12. A value of zero indicates that no information is available. A value of one indicates that the actual value is greater than the maximum that can be represented by the member.

dwDelay
Specifies a DWORD value that contains the one-way delay time, in milliseconds, that the network introduces when sending information. (The delay is the time between when the network begins sending data and the time that the data starts being received.) This delay is in addition to any latency incorporated in the calculation of the dwSpeed member; therefore the value of this member is zero for most resources.

A value of zero indicates that no information is available. A value of one indicates that the actual value is greater than the maximum that can be represented by the member.

dwOptDataSize
Specifies a DWORD value that contains a recommendation for the size of data, in bytes, that an application should use when making a single request to the network resource.

For example, for a disk network resource, this value might be 2048 or 512 when writing a block of data. A value of zero indicates that no information is available.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, MultinetGetConnectionPerformance


NETINFOSTRUCT

The NETINFOSTRUCT structure is used in the WNetGetNetworkInformation function. The structure contains information describing the network, such as the version of the network provider software and the network's current status.

typedef struct _NETINFOSTRUCT{
  DWORD cbStructure;
  DWORD dwProviderVersion;
  DWORD dwStatus;
  DWORD dwCharacteristics;
  ULONG_PTR dwHandle;
  WORD wNetType;
  DWORD dwPrinters;
  DWORD dwDrives;
} NETINFOSTRUCT, *LPNETINFOSTRUCT;

Members

cbStructure
Specifies the size, in bytes, of the NETINFOSTRUCT structure. The caller must supply this value to indicate the size of the structure passed in. Upon return, it has the size of the structure filled in.
dwProviderVersion
Specifies a DWORD value that contains the version number of the network provider software.
dwStatus
Specifies a DWORD value that contains the current status of the network provider software. This member can be one of the following values.
Value | Meaning
NO_ERROR | The network is running.
ERROR_NO_NETWORK | The network is unavailable.
ERROR_BUSY | The network is not currently able to service requests, but it should become available shortly. (This value typically indicates that the network is starting up.)

dwCharacteristics
Specifies a DWORD value that contains characteristics of the network provider software.

Windows NT/2000 or later: This value is always set to zero.

Windows 95/98/Me: This member can be one or more of the following values.
Value | Meaning
NETINFO_DLL16 | The network provider is running as a 16-bit Windows network driver.
NETINFO_DISKRED | The network provider requires a redirected local disk drive device to access server file systems.
NETINFO_PRINTERRED | The network provider requires a redirected local printer port to access server file systems.

dwHandle
Specifies an instance handle for the network provider or for the 16-bit Windows network driver.
wNetType
Specifies a network type unique to the running network. This value associates resources with a specific network when the resources are persistent or stored in links. You can find a complete list of network types in the header file WinNetwk.h.
dwPrinters
Specifies a DWORD value that contains a set of bit flags indicating the valid print numbers for redirecting local printer devices, with the low-order bit corresponding to LPT1.

Windows 95/98/Me: This value is always set to –1.

dwDrives
Specifies a DWORD value that contains a set of bit flags indicating the valid local disk devices for redirecting disk drives, with the low-order bit corresponding to A: .

Windows 95/98/Me: This value is always set to –1.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetGetNetworkInformation


NETRESOURCE

The NETRESOURCE structure contains information about a network resource. The structure is returned during enumeration of network resources. NETRESOURCE is also specified when making or querying a network connection with calls to various Windows Networking functions.

typedef struct _NETRESOURCE {
  DWORD  dwScope;
  DWORD  dwType;
  DWORD  dwDisplayType;
  DWORD  dwUsage;
  LPTSTR lpLocalName;
  LPTSTR lpRemoteName;
  LPTSTR lpComment;
  LPTSTR lpProvider;
} NETRESOURCE;

Members

dwScope
Specifies a DWORD value that contains the scope of the enumeration. This member can be one of the following values.
Value | Meaning
RESOURCE_CONNECTED | Enumerate currently connected resources. The dwUsage member cannot be specified.
RESOURCE_GLOBALNET | Enumerate all resources on the network. The dwUsage member is specified.
RESOURCE_REMEMBERED | Enumerate remembered (persistent) connections. The dwUsage member cannot be specified.

dwType
Specifies a DWORD value that contains a set of bit flags identifying the type of resource. This member can be one of the following values.
Value | Meaning
RESOURCETYPE_ANY | All resources
RESOURCETYPE_DISK | Disk resources
RESOURCETYPE_PRINT | Print resources

The WNetEnumResource function can also return the value RESOURCETYPE_UNKNOWN if a resource is neither a disk nor a print resource.

dwDisplayType
Specifies a DWORD value that indicates how the network object should be displayed in a network browsing user interface. This member can be one of the following values.
Value | Meaning
RESOURCEDISPLAYTYPE_DOMAIN | The object should be displayed as a domain.
RESOURCEDISPLAYTYPE_SERVER | The object should be displayed as a server.
RESOURCEDISPLAYTYPE_SHARE | The object should be displayed as a share.
RESOURCEDISPLAYTYPE_GENERIC | The method used to display the object does not matter.

dwUsage
Specifies a DWORD value that contains a set of bit flags describing how the resource can be used.

Note that this member can be specified only if the dwScope member is equal to RESOURCE_GLOBALNET. This member can be one of the following values.
Value | Meaning
RESOURCEUSAGE_CONNECTABLE | The resource is a connectable resource; the name pointed to by the lpRemoteName member can be passed to the WNetAddConnection function to make a network connection.
RESOURCEUSAGE_CONTAINER | The resource is a container resource; the name pointed to by the lpRemoteName member can be passed to the WNetOpenEnum function to enumerate the resources in the container.

lpLocalName
If the dwScope member is equal to RESOURCE_CONNECTED or RESOURCE_REMEMBERED, this member is a pointer to a null-terminated character string that specifies the name of a local device. This member is NULL if the connection does not use a device.
lpRemoteName
If the entry is a network resource, this member is a pointer to a null-terminated character string that specifies the remote network name.

If the entry is a current or persistent connection, lpRemoteName points to the network name associated with the name pointed to by the lpLocalName member.

The string can be MAX_PATH characters in length, and it must follow the network provider's naming conventions.

lpComment
Pointer to a null-terminated character string that contains a comment supplied by the network provider.
lpProvider
Pointer to a null-terminated character string that contains the name of the provider that owns the resource. This member can be NULL if the provider name is unknown. To retrieve the provider name, you can call the WNetGetProviderName function.

Remarks

For more information about setting the values of the dwType, lpLocalName, lpRemoteName, and lpProvider members, see MultinetGetConnectionPerformance, WNetAddConnection2, WNetAddConnection3, WNetGetResourceInformation, WNetGetResourceParent, and WNetUseConnection.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, MultinetGetConnectionPerformance, WNetAddConnection2, WNetAddConnection3, WNetUseConnection, WNetCloseEnum, WNetEnumResource, WNetGetProviderName, WNetGetResourceInformation, WNetGetResourceParent, WNetOpenEnum


REMOTE_NAME_INFO

The REMOTE_NAME_INFO structure contains path and name information for a network resource. The structure contains a member that points to a Universal Naming Convention (UNC) name string for the resource, and two members that point to additional network connection information strings.

typedef struct _REMOTE_NAME_INFO {
  LPTSTR  lpUniversalName;
  LPTSTR  lpConnectionName;
  LPTSTR  lpRemainingPath;
} REMOTE_NAME_INFO;

Members

lpUniversalName
Pointer to the null-terminated UNC name string that identifies a network resource.
lpConnectionName
Pointer to a null-terminated string that is the name of a network connection. For more information, see the following Remarks section.
lpRemainingPath
Pointer to a null-terminated name string. For more information, see the following Remarks section.

Remarks

The REMOTE_NAME_INFO structure contains a pointer to a Universal Naming Convention (UNC) name string. A UNC path identifies a network resource in an unambiguous, computer-independent manner. You can pass the path to processes on other computers, allowing those processes to obtain access to the network resource.

UNC names look like this:

\\servername\sharename\path\file

In addition, if you pass the value of the lpConnectionName member to the WNetAddConnection2 function, it enables you to connect a local device to a network resource. You can do this by passing the value of lpConnectionName in the lpRemoteName member of the NETRESOURCE structure pointed to by the function's lpNetResource parameter.

If you append the string pointed to by the lpRemainingPath member of REMOTE_NAME_INFO to the local device string, you can pass the resulting string to Win32 functions that require a drive-based path.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetAddConnection2, NETRESOURCE, UNIVERSAL_NAME_INFO


UNIVERSAL_NAME_INFO

The UNIVERSAL_NAME_INFO structure contains a pointer to a Universal Naming Convention (UNC) name string for a network resource.

typedef struct _UNIVERSAL_NAME_INFO {
  LPTSTR  lpUniversalName;
} UNIVERSAL_NAME_INFO;

Members

lpUniversalName
Pointer to the null-terminated UNC name string that identifies a network resource.

Remarks

A UNC path identifies a network resource in an unambiguous, computer-independent manner. You can pass the path to processes on other computers, allowing those processes to obtain access to the network resource.

Universal Naming Convention (UNC) names look like this:

\\servername\sharename\path\file

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Winnetwk.h.
Unicode: Declared as Unicode and ANSI structures.

See Also

Windows Networking (WNet) Overview, Windows Networking Structures, WNetGetUniversalName, REMOTE_NAME_INFO


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.