Функция WNetGetUniversalNameA (winnetwk.h)
Функция WNetGetUniversalName принимает путь на основе диска для сетевого ресурса и возвращает структуру информации, которая содержит более универсальную форму имени.
Синтаксис
DWORD WNetGetUniversalNameA(
[in] LPCSTR lpLocalPath,
[in] DWORD dwInfoLevel,
[out] LPVOID lpBuffer,
[in, out] LPDWORD lpBufferSize
);
Параметры
[in] lpLocalPath
Указатель на константную строку, завершающуюся значением NULL, которая представляет собой путь к сетевому ресурсу на основе диска.
Например, если диск H сопоставлен с общей папкой сетевого диска, а интересующим сетевым ресурсом является файл с именем Sample.doc в каталоге \Win32\Examples в этой общей папке, путь на основе диска H:\Win32\Examples\Sample.doc.
[in] dwInfoLevel
Тип структуры, хранимой функцией в буфере, на который указывает параметр lpBuffer . Этот параметр может быть одним из следующих значений, определенных в файле заголовка Winnetwk.h .
| Значение | Значение |
|---|---|
|
Функция сохраняет структуру UNIVERSAL_NAME_INFO в буфере. |
|
Функция сохраняет структуру REMOTE_NAME_INFO в буфере. |
Структура UNIVERSAL_NAME_INFO указывает на строку имени UNC.
Структура REMOTE_NAME_INFO указывает на строку UNC-имени и две дополнительные строки сведений о подключении. Дополнительные сведения см. в разделе "Примечания".
[out] lpBuffer
Указатель на буфер, получающий структуру, заданную параметром dwInfoLevel .
[in, out] lpBufferSize
Указатель на переменную, указывающую размер (в байтах) буфера, на который указывает параметр lpBuffer .
Если функция выполняется успешно, она задает для переменной, на которую указывает lpBufferSize , количество байтов, хранящихся в буфере. Если функция завершается сбоем, так как буфер слишком мал, это расположение получает требуемый размер буфера, а функция возвращает ERROR_MORE_DATA.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки, например одно из следующих значений.
| Код возврата | Описание |
|---|---|
|
Недопустимая строка, на которую указывает параметр lpLocalPath . |
|
Текущее подключение к удаленному устройству отсутствует, но к нему имеется запоминающееся (постоянное) подключение. |
|
Произошла ошибка, относявшаяся к сети. Используйте функцию WNetGetLastError , чтобы получить описание ошибки. |
|
Буфер, на который указывает параметр lpBuffer , слишком мал. Функция присваивает переменной, на которую указывает параметр lpBufferSize , требуемый размер буфера. При последующих вызовах доступны дополнительные записи. |
|
Параметру dwInfoLevel присвоено значение UNIVERSAL_NAME_INFO_LEVEL, но поставщик сети не поддерживает UNC-имена. (Ни один из поставщиков сети не поддерживает эту функцию.) |
|
Ни один из поставщиков сети не распознает локальное имя как имеющее подключение. Однако сеть недоступна по крайней мере для одного поставщика, которому может принадлежать подключение. |
|
Сеть недоступна. |
|
Устройство, указанное параметром 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-имени, а также указатели на две другие полезные строки. Например, процесс может передать элемент lpszConnectionInfoструктуры REMOTE_NAME_INFO функции WNetAddConnection2 для подключения локального устройства к сетевому ресурсу. Затем процесс может добавить строку, на которую указывает член lpszRemainingPath , в строку локального устройства. Результирующая строка может быть передана в функции, которым требуется путь на основе диска.
Параметр lpLocalPath не должен указывать путь или ресурс, который уже присутствует в удаленном ресурсе. Например, параметр lpLocalPath может указывать папку и, иерархию папок или файл, который в настоящее время не существует. Функция WNetGetUniversalName в этих случаях возвращает более универсальную форму имени.
Размер буфера, на который указывает параметр lpBuffer и указанный в параметре lpBufferSize , должен быть гораздо больше размера REMOTE_NAME_INFO или UNIVERSAL_NAME_INFO структур. Буфер, на который указывает параметр lpBuffer , должен быть достаточно большим для хранения строк UNC, на которые указывают члены в 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 <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);
}
}
Примечание
Заголовок winnetwk.h определяет WNetGetUniversalName в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | winnetwk.h |
| Библиотека | Mpr.lib |
| DLL | Mpr.dll |
См. также раздел
Определение расположения общей папки
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по