| Platform SDK: Windows Networking |
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 );
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.
| 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.
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.
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. |
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.
Windows NT/2000: Requires Windows NT 3.5 or later.
Windows 95/98: 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.
Windows Networking (WNet) Overview, Windows Networking Functions, REMOTE_NAME_INFO, UNIVERSAL_NAME_INFO, WNetAddConnection2