WNetGetUniversalNameA function (winnetwk.h)

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.

Syntax

DWORD WNetGetUniversalNameA(
  [in]      LPCSTR  lpLocalPath,
  [in]      DWORD   dwInfoLevel,
  [out]     LPVOID  lpBuffer,
  [in, out] LPDWORD lpBufferSize
);

Parameters

[in] lpLocalPath

A 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.

[in] dwInfoLevel

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 defined in the Winnetwk.h header file.

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.

[out] lpBuffer

A pointer to a buffer that receives the structure specified by the dwInfoLevel parameter.

[in, out] lpBufferSize

A 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 value

If the function succeeds, the return value is NO_ERROR.

If the function fails, the return value is a system error code, such as one of the following values.

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 the following:

\\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 functions that require a drive-based path.

The lpLocalPath parameter does not have to specify a path or resource that is already present on a remote resource. For example, the lpLocalPath parameter could specify and folder, a hierarchy of folders, or a file that does not currently exist. The WNetGetUniversalName function returns a more universal form of the name in these cases.

The size of the buffer pointed to by the lpBuffer parameter and specified in the lpBufferSize parameter must be much larger than the size of the REMOTE_NAME_INFO or UNIVERSAL_NAME_INFO structures. The buffer pointed to by the lpBuffer parameter must be large enough to store the UNC strings pointed to by the members in the REMOTE_NAME_INFO or UNIVERSAL_NAME_INFO structures. If the buffer size is too small, then the function fails with ERROR_MORE_DATA and the variable pointed to by the lpBufferSize parameter indicates the required buffer size.

Windows Server 2003 and Windows XP:  This function queries the MS-DOS device namespaces associated with a logon session because MS-DOS devices are identified by AuthenticationID. (An AuthenticationID is the locally unique identifier, or LUID, associated with a logon session.) This can affect applications that call one of the WNet functions to create a network drive letter under one user logon, but query for existing network drive letters under a different user logon. An example of this situation could be when a user's second logon is created within a logon session, for example, by calling the CreateProcessAsUser function, and the second logon runs an application that calls the GetLogicalDrives function. GetLogicalDrives does not return network drive letters created by a WNet function under the first logon. Note that in the preceding example the first logon session still exists, and the example could apply to any logon session, including a Terminal Services session. For more information, see Defining an MS-DOS Device Name.

Examples

The following code sample illustrates how to use the WNetGetUniversalName function to retrieve the universal UNC name strings associated with drive-based path for a network resource.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")

#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>

int wmain(int argc, wchar_t * argv[])
{
    DWORD dwRetVal;

    WCHAR Buffer[1024];
    DWORD dwBufferLength = 1024;
       
    UNIVERSAL_NAME_INFO * unameinfo;
    REMOTE_NAME_INFO *remotenameinfo;
    
    wprintf(L"Calling WNetGetUniversalName with Local Path = %s\n", argv[1]);

    unameinfo = (UNIVERSAL_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], UNIVERSAL_NAME_INFO_LEVEL, (LPVOID) unameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", unameinfo->lpUniversalName);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=UNIVERSAL_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }


    remotenameinfo = (REMOTE_NAME_INFO *) &Buffer;
    dwRetVal = WNetGetUniversalName(argv[1], REMOTE_NAME_INFO_LEVEL, 
        (LPVOID) remotenameinfo, &dwBufferLength );
    //
    // If the call succeeds, print the user information.
    //
    if (dwRetVal == NO_ERROR) {

        wprintf(L"WNetGetUniversalName returned success for InfoLevel=REMOTE_NAME_INFO_LEVEL\n");
        wprintf(L"\tUniversal name = %s\n", remotenameinfo->lpUniversalName);
        wprintf(L"\tConnection name = %s\n", remotenameinfo->lpConnectionName);
        wprintf(L"\tRemaining path = %s\n", remotenameinfo->lpRemainingPath);
    }

    else {
        wprintf(L"WNetGetUser failed for InfoLevel=REMOTE_NAME_INFO_LEVEL with error: %u\n", dwRetVal);
    }
}

Requirements

See also

Determining the Location of a Share

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2

Windows Networking (WNet) Overview

Windows Networking Functions