Функция 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 указывает на строку имени UNC.

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

[out] lpBuffer

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

[in, out] lpBufferSize

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

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

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

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

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

Комментарии

Универсальная форма локального пути на основе диска определяет сетевой ресурс однозначно, независимо от компьютера. Затем имя может быть передано процессам на других компьютерах, что позволит этим процессам получить доступ к ресурсу.

Функция 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);
    }
}

Требования

См. также раздел

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

REMOTE_NAME_INFO

UNIVERSAL_NAME_INFO

WNetAddConnection2

Общие сведения о сети Windows (WNet)

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