WNetGetResourceParent

[This is preliminary documentation and subject to change.]

The WNetGetResourceParent function determines the parent of a network resource in the network browse hierarchy. Browsing begins at the location of the specified network resource. Use the WNetOpenEnum function to move down the browse hierarchy. Conversely, use the WNetGetResourceInformation and WNetGetResourceParent functions to move up the tree.

DWORD WNetGetResourceParent(
  LPNETRESOURCE lpNetResource,  // Specifies a network resource 
                                // for the parent name
  LPVOID lpBuffer,              // Specifies a pointer containing 
                                // the parent source
  LPDWORD lpBufferSize,         // Specifies size of location 
                                // pointed to by lpbuffer
  );

Parameters

lpNetResource
Specifies the network resource for which the parent name is required. Use the WNetEnumResource, WNetGetResourceInformation or WNetGetResourceParent functions to return information from the NETRESOURCE structure. You can also construct network resource information using the parameters in the NETRESOURCE structure.

The lpRemoteName parameter specifies the remote name of the network resource whose parent is required. The lpProvider parameter specifies the network provider that owns the resource. This must be supplied; otherwise, the function could produce incorrect results. The dwType field should be filled in if known; otherwise, it should be set to NULL.

Note that the caller typically knows the values for lpProvider and dwType after previous calls to WNetGetResourceInformation or WNetGetResourceParent. All other parameters in the NETRESOURCE structure are ignored.

lpBuffer
Pointer to a buffer to receive the result, which is a single NETRESOURCE structure representing the parent resource.

The lpRemoteName, lpProvider, dwType, dwDisplayType, and dwUsage parameters of NETRESOURCE are returned; all other fields are set to NULL.

The lpRemoteName parameter points to the remote name for the parent resource. This name uses the same syntax as that returned from an enumeration by WNetEnumResource. 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 parameter is returned as NULL. The lpProvider parameter is always returned when the function call is successful. In the dwUsage parameter, the presence of the RESOURCEUSAGE_CONNECTABLE bit means that the parent resource can be connected to, but only when it is available on the network.

lpBufferSize
Points to a location that specifies the size, in bytes, of the buffer pointed to by lpBuffer. If the buffer is too small for the result, the function places the required buffer size at this location and 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).
ERROR_BAD_NET_NAME The lpRemoteName parameter is not an existing network resource for any network.
ERROR_BAD_PROVIDER The lpProvider parameter does not match any installed network provider.
ERROR_MORE_DATA The buffer pointed to by lpBuffer is too small.
ERROR_NOT_AUTHENTICATED The caller does not have the necessary permissions to obtain the name of the parent.

Remarks

Unlike WNetGetResourceInformation, if the resource includes a parent in its syntax, WNetGetResourceParent returns the parent, whether or not the resource actually exists. The WNetGetResourceParent function 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 such applications. No assumptions should be made about the type of resource that will be returned. 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, but it will give wrong results for other networks.

QuickInfo

  Windows NT: Use version 3.5 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Use version 2.0 or later.
  Header: Declared in winnetwk.h.
  Import Library: Use mpr.lib.

See Also

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