Поделиться через

Функция 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_LEVEL
 Функция сохраняет UNIVERSAL_NAME_INFO структуру в буфере.
REMOTE_NAME_INFO_LEVEL
 Функция сохраняет структуру REMOTE_NAME_INFO в буфере.
 

Структура UNIVERSAL_NAME_INFO указывает на строку имени универсального соглашения об именовании (UNC).

Структура REMOTE_NAME_INFO указывает на строку имени UNC и две дополнительные строки сведений о подключении. Дополнительные сведения см. в следующем разделе "Примечания".

[out] lpBuffer

Указатель на буфер, который получает структуру, указанную параметром dwInfoLevel .

[in, out] lpBufferSize

Указатель на переменную, указывающую размер буфера в байтах, на который указывает параметр lpBuffer.

Если функция выполнена успешно, она задает переменную, на которую указывает lpBufferSize число байтов, хранящихся в буфере. Если функция завершается ошибкой, так как буфер слишком мал, это расположение получает требуемый размер буфера, а функция возвращает ERROR_MORE_DATA.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение NO_ERROR.

Если функция завершается ошибкой, возвращаемое значение является системным кодом ошибки, например одно из следующих значений.

Возвращаемый код Описание
ERROR_BAD_DEVICE
 Строка, на которую указывает параметр lpLocalPath, является недопустимым.
ERROR_CONNECTION_UNAVAIL
 Нет текущего подключения к удаленному устройству, но к нему не подключено (постоянное) подключение.
ERROR_EXTENDED_ERROR
 Произошла ошибка, зависявшая от сети. Используйте функцию WNetGetLastError, чтобы получить описание ошибки.
ERROR_MORE_DATA
 Буфер, на который указывает параметр lpBuffer, слишком мал. Функция задает переменную, на которую указывает параметр lpBufferSize в требуемый размер буфера. Дополнительные записи доступны при последующих вызовах.
ERROR_NOT_SUPPORTED
 Параметр dwInfoLevel имеет значение UNIVERSAL_NAME_INFO_LEVEL, но поставщик сети не поддерживает имена UNC. (Ни один из поставщиков сети не поддерживает эту функцию.)
ERROR_NO_NET_OR_BAD_PATH
 Ни один из сетевых поставщиков не распознает локальное имя как подключение. Однако сеть недоступна по крайней мере для одного поставщика, которому может принадлежать подключение.
ERROR_NO_NETWORK
 Сеть недоступна.
ERROR_NOT_CONNECTED
 Устройство, указанное параметром 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 может указывать и папку, иерархию папок или файл, который в настоящее время не существует. Функция 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. (Идентификатор проверки подлинности — это локально уникальный идентификаторили 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 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер Windows 2000 Server [только классические приложения]
целевая платформа Виндоус
заголовка winnetwk.h
библиотеки Mpr.lib
DLL Mpr.dll

См. также

определение расположения общей папки

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2

Обзор сети Windows (WNet)

Сетевые функции Windows