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.