Функция WNetAddConnection2A (winnetwk.h)

Функция WNetAddConnection2 устанавливает подключение к сетевому ресурсу и может перенаправлять локальное устройство в сетевой ресурс.

Функция WNetAddConnection2 заменяет функцию WNetAddConnection . Если вы можете передать дескриптор в окно, которое поставщик сетевых ресурсов может использовать в качестве окна-владельца для диалоговых окон, вызовите вместо этого функцию WNetAddConnection3 .

Синтаксис

DWORD WNetAddConnection2A(
  [in] LPNETRESOURCEA lpNetResource,
  [in] LPCSTR         lpPassword,
  [in] LPCSTR         lpUserName,
  [in] DWORD          dwFlags
);

Параметры

[in] lpNetResource

Указатель на структуру NETRESOURCE , которая указывает сведения о предполагаемом подключении, например сведения о сетевом ресурсе, локальном устройстве и поставщике сетевых ресурсов.

Необходимо указать следующие элементы структуры NETRESOURCE .

Функция WNetAddConnection2 игнорирует другие элементы структуры NETRESOURCE .

[in] lpPassword

Указатель на константную строку, завершающуюся значением NULL, которая указывает пароль, используемый при сетевом подключении.

Если lpPassword имеет значение NULL, функция использует текущий пароль по умолчанию, связанный с пользователем, указанным параметром lpUserName .

Если lpPassword указывает на пустую строку, функция не использует пароль.

Если подключение завершается сбоем из-за недопустимого пароля и в параметре dwFlags задано значение CONNECT_INTERACTIVE, функция отображает диалоговое окно с запросом на ввод пароля.

Windows Me/98/95: Этот параметр должен иметь значение NULL или пустую строку.

[in] lpUserName

Указатель на константную строку, завершающуюся null, которая указывает имя пользователя для соединения.

Если lpUserName имеет значение NULL, функция использует имя пользователя по умолчанию. (Контекст пользователя для процесса предоставляет имя пользователя по умолчанию.)

Параметр lpUserName указывается, когда пользователи хотят подключиться к сетевому ресурсу, для которого им назначено имя пользователя или учетная запись, отличные от имени пользователя или учетной записи по умолчанию.

Строка имени пользователя представляет контекст безопасности. Он может быть специфичным для сетевого поставщика.

Windows Me/98/95: Этот параметр должен иметь значение NULL или пустую строку.

[in] dwFlags

Набор параметров подключения. Возможные значения для параметров подключения определяются в файле заголовка Winnetwk.h . В настоящее время можно использовать следующие значения.

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

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

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

Комментарии

В Windows Server 2003 и Windows XP функции WNet создают и удаляют буквы сетевых дисков в пространстве имен устройств MS-DOS, связанном с сеансом входа, так как устройства MS-DOS идентифицируются с помощью AuthenticationID (a).
локально уникальный идентификатор или LUID, связанный с сеансом входа.) Это может повлиять на приложения, которые вызывают одну из функций WNet для создания буквы сетевого диска при входе одного пользователя, но запрашивают существующие буквы сетевых дисков при входе другого пользователя. Примером такой ситуации может быть создание второго входа пользователя в сеансе входа, например путем вызова функции CreateProcessAsUser , а при втором входе запускается приложение, которое вызывает функцию GetLogicalDrives . Вызов функции GetLogicalDrives не возвращает буквы сетевых дисков, созданные вызовами функции WNet при первом входе в систему. Обратите внимание, что в предыдущем примере первый сеанс входа по-прежнему существует, и этот пример может применяться к любому сеансу входа, включая сеанс служб терминалов. Дополнительные сведения см. в разделе Определение имени устройства MS-DOS.

Если в Windows Server 2003 и Windows XP служба, которая выполняется как LocalSystem, вызывает функцию WNetAddConnection2 , сопоставленный диск будет виден всем сеансам входа пользователей.

Для сетевых поставщиков Майкрософт элемент lpRemoteName структуры NETRESOURCE , на который указывает параметр lpNetResource , может содержать IPv4-адрес в точечной десятичной нотации. Примером общего ресурса может быть следующее:

\192.168.1.1\share

Для поставщиков сетей Майкрософт в Windows Vista и более поздних версиях элемент lpRemoteName структуры NETRESOURCE , на который указывает параметр lpNetResource , может содержать IPv6-адрес. Однако для правильного анализа IPv6-адреса необходимо использовать литерал IPv6. Литеральный адрес IPv6 имеет следующий вид:

ipv6-address с символами ":" заменены символами "-", за которыми следует строка ".ipv6-literal.net".

Например, для следующего IPv6-адреса:

2001:4898:9:3:c069:aa97:fe76:2449

Примером общего ресурса может быть следующее:

\2001-4898-9-3-c069-aa97-fe76-2449.ipv6-literal.net\share

Другие поставщики сетей могут поддерживать элемент lpRemoteName структуры NETRESOURCE , на которую указывает параметр lpNetResource , содержащий адрес IPv4 или IPv6, но это зависит от конкретного поставщика сети.

Windows 7 и Windows Server 2008 R2: Если функция WNetAddConnection2 вызывается с явными учетными данными пользователя, указанными в pUsername и lpPassword для установления подключения к сетевому ресурсу на определенном сервере, а затем вызывается еще раз с использованием любого из этих параметров в качестве NULL (для использования имени пользователя по умолчанию или пароля по умолчанию) к тому же серверу, вызов с ошибкой. Возвращенная ошибка будет ERROR_BAD_USERNAME или ERROR_INVALID_PASSWORD.

Примеры

В следующем примере кода показано, как использовать функцию WNetAddConnection2 для подключения к сетевому ресурсу.

#ifndef UNICODE
#define UNICODE
#endif
#pragma comment(lib, "mpr.lib")

#include <windows.h>
#include <tchar.h>
#include <stdio.h>
#include <Winnetwk.h>

// Need to link with Netapi32.lib and Mpr.lib

int wmain(int argc, wchar_t * argv[])
{

    DWORD dwRetVal;

    NETRESOURCE nr;
    DWORD dwFlags;

    if (argc != 5) {
        wprintf(L"Usage: %s <localname> <remotename> <username> <password>\n",
                argv[0]);
        wprintf(L"       %s X: \\\\contoso\\public testuser testpasswd\n",
                argv[0]);
        exit(1);
    }

    wprintf(L"Calling WNetAddConnection2 with\n");
    wprintf(L"  lpLocalName = %s\n", argv[1]);
    wprintf(L"  lpRemoteName = %s\n", argv[2]);
    wprintf(L"  lpUsername = %s\n", argv[3]);
    wprintf(L"  lpPassword = %s\n", argv[4]);

// Zero out the NETRESOURCE struct
    memset(&nr, 0, sizeof (NETRESOURCE));

// Assign our values to the NETRESOURCE structure.

    nr.dwType = RESOURCETYPE_ANY;
    nr.lpLocalName = argv[1];
    nr.lpRemoteName = argv[2];
    nr.lpProvider = NULL;

// Assign a value to the connection options
    dwFlags = CONNECT_UPDATE_PROFILE;
//
// Call the WNetAddConnection2 function to assign
//   a drive letter to the share.
//
    dwRetVal = WNetAddConnection2(&nr, argv[4], argv[3], dwFlags);
//
// If the call succeeds, inform the user; otherwise,
//  print the error.
//
    if (dwRetVal == NO_ERROR)
        wprintf(L"Connection added to %s\n", nr.lpRemoteName);
    else
        wprintf(L"WNetAddConnection2 failed with error: %u\n", dwRetVal);

    exit(1); 
}

Другие примеры кода, демонстрирующие подключение к сетевому ресурсу с помощью функции WNetAddConnection2 , см. в статье Добавление сетевого подключения и назначение диска к общей папке.

Требования

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

NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

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

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