| 术语 | wnetgetuniversalname |
| 释义 | WNetGetUniversalName 语法： C++ DWORD WNetGetUniversalName( __in LPCTSTR lpLocalPath, __in DWORD dwInfoLevel, __out LPVOID lpBuffer, __inout LPDWORD lpBufferSize ); WNetGetUniversalName功能 该WNetGetUniversalName函数接受一个驱动器，基于网络资源的路径，并返回一个信息结构，它包含一个名字更普遍的形式。 参数 lpLocalPath [in] 阿为一个恒定的空指针结尾的字符串，是一个驱动器，基于网络资源的路径。 例如，如果驱动器H已被映射到网络驱动器共享和网络资源的利益是名为目录Sample.doc，位于 \\Win32\\Examples，该驱动器的路径文件是H:\\Win32\\Examples\\Sample.doc。 dwInfoLevel [in] 的结构类型，在缓冲存储功能所指出的lpBuffer参数的。此参数可在Winnetwk.h头文件中定义下列值之一。 ValueMeaning UNIVERSAL_NAME_INFO_LEVELThe功能存储在缓冲区UNIVERSAL_NAME_INFO结构。 REMOTE_NAME_INFO_LEVELThe功能存储在缓冲区REMOTE_NAME_INFO结构。 在UNIVERSAL_NAME_INFO结构指向一个通用命名约定(UNC)名称字符串。 在REMOTE_NAME_INFO结构指向一个UNC名称字符串和两个额外的连接信息的字符串。有关详细信息，请参阅下面的备注部分。 lpBuffer [out] 一个缓冲区所获得的dwInfoLevel参数指定的结构的指针。 lpBufferSize [ in , out ] 一个变量，指定大小，以字节的缓冲区，指针指向的lpBuffer参数。 如果函数成功，它设置的变量所指向的lpBufferSize对存储在缓冲区中的字节数。如果函数失败，因为缓冲区太小，此位置获得所需的缓冲区大小，该函数返回ERROR_MORE_DATA。 返回值 如果函数成功，返回值为NO_ERROR。 如果函数失败，返回值是一个系统错误代码，如下列值之一。 返回codeDescription ERROR_BAD_DEVICEThe字符串指出的lpLocalPath参数是无效的。 ERROR_CONNECTION_UNAVAILThere目前没有连接到远程设备，但有一个记忆(持久)连接到它。 ERROR_EXTENDED_ERRORA网络特定的错误。使用WNetGetLastError函数获取错误的描述。 ERROR_MORE_DATAThe所指向的缓冲区lpBuffer参数的是太小了。该函数设置变量指出的lpBufferSize参数所需的缓冲区大小。更多的项目，可与后续调用。 ERROR_NOT_SUPPORTEDThe dwInfoLevel参数设置为UNIVERSAL_NAME_INFO_LEVEL，但网络提供程序不支持UNC名称。 (网络供应商没有支持此功能。) 网络提供ERROR_NO_NET_OR_BAD_PATHNone承认有一个连接的本地名称。然而，网络不可用至少一个供应商，其中可能属于该连接。 ERROR_NO_NETWORKThe网络不可用。 ERROR_NOT_CONNECTEDThe设备的lpLocalPath参数指定不重定向。 备注 一个本地驱动器普遍的形式为基础的道路标识的网络资源，在一个明确的，计算机无关的方式。该名称可以被传递到其他计算机上的进程，让这些进程，以获得对资源的访问。 该WNetGetUniversalName功能目前支持一个统一的名称形式：通用命名约定(UNC)名称，类似如下所示： \\\\servername\\sharename\\path\\file 利用从lpLocalPath参数的前面描述的例子，如果共享的网络驱动器名为COOLSERVER一个服务器，并共享名HOTSHARE，对网络资源的UNC名称的驱动器的名称是H:\\Win32\\Examples\\Sample.doc将是如下： \\\\coolserver\\hotshare\\win32\\examples\\sample.doc 该UNIVERSAL_NAME_INFO结构包含一个指向一个UNC名称字符串。该REMOTE_NAME_INFO结构还包含一个指向字符串的UNC名称，以及其他有用的两个字符串指针。例如，一个进程可以通过REMOTE_NAME_INFO结构的lpszConnectionInfo成员的WNetAddConnection2函数可连接到本地设备的网络资源。然后，这个过程可以追加字符串指向的lpszRemainingPath成员，本地设备的字符串。结果字符串可以传递给函数需要一个驱动器的路径。 该lpLocalPath参数没有指定路径或资源上已远程资源存在。例如，lpLocalPath参数可以指定和文件夹，文件夹hieracrchy，或一个文件，目前不存在。函数返回的WNetGetUniversalName在这些案件的名称更普遍的形式。 缓冲区的大小指向的lpBuffer参数和lpBufferSize参数中指定要远远高于在REMOTE_NAME_INFO或UNIVERSAL_NAME_INFO结构的大小。缓冲区指向的lpBuffer参数必须足够大，存储字符串指出联合国军司令部在REMOTE_NAME_INFO或UNIVERSAL_NAME_INFO结构的成员。如果缓冲区大小太小，则函数失败，ERROR_MORE_DATA和变量指出的lpBufferSize参数显示所需的缓冲区大小。 Windows Server 2003和Windows XP中：此功能查询MS - DOS设备的登录会话，因为MS - DOS设备是由AuthenticationID确定相关的命名空间。 (一个AuthenticationID是当地唯一的标识符，或的LUID，与登录会话相关联。)这可能会影响应用程序的WNet函数调用来创建下一个用户登录网络驱动器号，但现有的网络驱动器字母查询下不同的用户登录。这种情况的一个例子是，当用户的第二个登录，在登录会话中创建，例如，通过调用运行CreateProcessAsUser函数，第二个登录的应用程序调用GetLogicalDrives函数。 GetLogicalDrives不会返回网络驱动器由一个WNet函数下创建首次登录字母。请注意，在前面的例子中第一个登录会话仍然存在，而且例子可以适用于任何登录会话，包括终端服务会话。有关更多信息，请参见定义一个MS - DOS设备名。 实例 下面的代码示例演示如何使用WNetGetUniversalName函数来检索普遍UNC名称与驱动器关联的字符串基于网络资源的路径。 #ifndef UNICODE #define UNICODE #endif #pragma comment(lib, "mpr.lib") #include #include #include #include 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); } } 要求： 最低支持：client－Windows 2000专业版 最低支持server－Windows 2000服务器 HeaderWinnetwk.h LibraryMpr.lib DLLMpr.dll Unicode和ANSI namesWNetGetUniversalNameW(Unicode)和WNetGetUniversalNameA(ANSI)的 参见 Windows网络(WNet)概述 Windows网络函数 确定一个共享位置 REMOTE_NAME_INFO UNIVERSAL_NAME_INFO WNetAddConnection2 如果有任何问题和意见，请发送给微软(wsddocfb@microsoft.com) 生成日期：2009年8月6日 ＝＝英文原文＝＝WNetGetUniversalName Function 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 C++ DWORD WNetGetUniversalName( __in LPCTSTR lpLocalPath, __in DWORD dwInfoLevel, __out LPVOID lpBuffer, __inout LPDWORD lpBufferSize ); Parameters lpLocalPath [in] 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. dwInfoLevel [in] 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. ValueMeaning UNIVERSAL_NAME_INFO_LEVELThe function stores a UNIVERSAL_NAME_INFO structure in the buffer. REMOTE_NAME_INFO_LEVELThe 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] A pointer to a buffer that receives the structure specified by the dwInfoLevel parameter. lpBufferSize [in, out] 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. Return codeDescription ERROR_BAD_DEVICEThe string pointed to by the lpLocalPath parameter is invalid. ERROR_CONNECTION_UNAVAILThere is no current connection to the remote device, but there is a remembered (persistent) connection to it. ERROR_EXTENDED_ERRORA network-specific error occurred. Use the WNetGetLastError function to obtain a description of the error. ERROR_MORE_DATAThe 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_SUPPORTEDThe 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_PATHNone 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_NETWORKThe network is unavailable. ERROR_NOT_CONNECTEDThe 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 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 hieracrchy 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 #include #include #include 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 Minimum supported clientWindows 2000 Professional Minimum supported serverWindows 2000 Server HeaderWinnetwk.h LibraryMpr.lib DLLMpr.dll Unicode and ANSI namesWNetGetUniversalNameW (Unicode) and WNetGetUniversalNameA (ANSI) See Also Windows Networking (WNet) Overview Windows Networking Functions Determining the Location of a Share REMOTE_NAME_INFO UNIVERSAL_NAME_INFO WNetAddConnection2 Send comments about this topic to Microsoft Build date: 8/6/2009 ＝＝原始网址＝＝http://msdn.microsoft.com/en-us/library/aa385474(VS.85).aspx\n |
| 随便看 |
|
windows api函数参考手册包含2258条windows api函数文档，详细介绍nodejs、java、rust调用windows api的方法技巧，是学习windows api编程的入门中文文档。