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


Функция 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 .

Член Значение
dwType
Тип сетевого ресурса для подключения.

Если элемент lpLocalName указывает на непустую строку, этот элемент может быть равен RESOURCETYPE_DISK или RESOURCETYPE_PRINT.

Если lpLocalName имеет значение NULL или указывает на пустую строку, параметр dwType может быть равен RESOURCETYPE_DISK, RESOURCETYPE_PRINT или RESOURCETYPE_ANY.

Хотя этот элемент является обязательным, его сведения могут быть проигнорированы поставщиком сетевых служб.

lpLocalName
Указатель на строку, завершающуюся значением NULL, которая указывает имя локального устройства для перенаправления, например "F:" или "LPT1". Строка обрабатывается без учета регистра.

Если строка пуста или lpLocalName имеет значение NULL, функция устанавливает подключение к сетевому ресурсу без перенаправления локального устройства.

lpRemoteName
Указатель на строку, завершающуюся значением NULL, которая указывает сетевой ресурс для подключения. Строка может содержать до MAX_PATH символов и должна соответствовать соглашениям об именовании поставщика сети.
lpProvider
Указатель на строку, завершающуюся значением NULL, которая указывает поставщика сети, к которому необходимо подключиться.

Если lpProvider имеет значение NULL или указывает на пустую строку, операционная система пытается определить правильного поставщика, проанализировав строку, на которую указывает элемент lpRemoteName .

Если этот элемент не равен NULL, операционная система пытается установить подключение только к именованным поставщику сети.

Этот член следует задавать только в том случае, если вы знаете поставщика сети, который вы хотите использовать. В противном случае дайте операционной системе определить, с каким поставщиком сопоставляется сетевое имя.

 

Функция 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 . В настоящее время можно использовать следующие значения.

Значение Значение
CONNECT_UPDATE_PROFILE
0x00000001
Следует помнить о подключении к сетевым ресурсам.

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

Операционная система запоминает только успешные подключения, которые перенаправляют локальные устройства. Он не запоминает неудачные подключения или подключения без устройства. (Подключение без устройства возникает, когда элемент lpLocalName имеет значение NULL или указывает на пустую строку.)

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

CONNECT_UPDATE_RECENT
0x00000002
Подключение к сетевому ресурсу не следует помещать в список последних подключений.

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

CONNECT_TEMPORARY
0x00000004
Не следует помнить о подключении к сетевому ресурсу.

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

CONNECT_INTERACTIVE
0x00000008
Если этот флаг установлен, операционная система может взаимодействовать с пользователем для проверки подлинности.
CONNECT_PROMPT
0x00000010
Этот флаг предписывает системе не использовать параметры по умолчанию для имен пользователей или паролей, не предлагая пользователю возможность предоставить альтернативу. Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE.
CONNECT_REDIRECT
0x00000080
Этот флаг принудительно выполняет перенаправление локального устройства при подключении.

Если элемент lpLocalNamenetRESOURCE указывает локальное устройство для перенаправления, этот флаг не действует, так как операционная система по-прежнему пытается перенаправить указанное устройство. Когда операционная система автоматически выбирает локальное устройство, член dwType не должен быть равен RESOURCETYPE_ANY.

Если этот флаг не установлен, локальное устройство автоматически выбирается для перенаправления, только если сеть требует перенаправления локального устройства.

Windows Server 2003 и Windows XP: Когда система автоматически назначает буквы сетевого диска, назначаются буквы, начинающиеся с Z:, затем Y:, и заканчивающиеся C:. Это снижает вероятность конфликта между буквами дисков для каждого входа (например, буквами сетевых дисков) и буквами глобальных дисков (например, дисков). Обратите внимание, что в более ранних версиях Windows назначали диску буквы, начинающиеся с C: и заканчивающиеся Z:.

CONNECT_CURRENT_MEDIA
0x00000200
Если этот флаг установлен, операционная система не начинает использовать новый носитель для попытки установить подключение (например, инициировать новое коммутируемое подключение).
CONNECT_COMMANDLINE
0x00000800
Если этот флаг установлен, операционная система запрашивает проверку подлинности пользователя с помощью командной строки, а не графического пользовательского интерфейса (GUI). Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE.

Windows XP: Это значение поддерживается в Windows XP и более поздних версиях.

CONNECT_CMD_SAVECRED
0x00001000
Если этот флаг установлен и операционная система запрашивает учетные данные, диспетчер учетных данных должен сохранить учетные данные. Если диспетчер учетных данных отключен для сеанса входа вызывающего абонента или поставщик сети не поддерживает сохранение учетных данных, этот флаг игнорируется. Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE. Этот флаг также игнорируется, если вы не задали флаг CONNECT_COMMANDLINE.

Windows XP: Это значение поддерживается в Windows XP и более поздних версиях.

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

Windows Vista: Это значение поддерживается в Windows Vista и более поздних версиях.

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

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

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

Код возврата Описание
ERROR_ACCESS_DENIED
Вызывающий объект не имеет доступа к сетевому ресурсу.
ERROR_ALREADY_ASSIGNED
Локальное устройство, указанное членом lpLocalName , уже подключено к сетевому ресурсу.
ERROR_BAD_DEV_TYPE
Тип локального устройства и тип сетевого ресурса не совпадают.
ERROR_BAD_DEVICE
Указанное имя устройства недопустимо. Эта ошибка возвращается, если элемент lpLocalName структуры NETRESOURCE , на который указывает параметр lpNetResource , указывает устройство, которое не может быть перенаправлено.
ERROR_BAD_NET_NAME
Не найдено сетевое имя". Это значение возвращается, если элемент lpRemoteName структуры NETRESOURCE , на который указывает параметр lpNetResource , указывает ресурс, который не является приемлемым для любого поставщика сетевых ресурсов, либо потому, что имя ресурса пустое, недопустимое или потому, что именованный ресурс не может быть найден.
ERROR_BAD_PROFILE
Профиль пользователя имеет неправильный формат.
ERROR_BAD_PROVIDER
Недопустимое имя указанного поставщика сети. Эта ошибка возвращается, если член lpProvider структуры NETRESOURCE , на который указывает параметр lpNetResource , задает значение, не соответствующее ни одному поставщику сети.
ERROR_BAD_USERNAME
Указанное имя пользователя недопустимо.
ERROR_BUSY
Маршрутизатор или поставщик занят, возможно, инициализация. Вызывающий объект должен повторить попытку.
ERROR_CANCELLED
Попытка установить подключение была отменена пользователем через диалоговое окно от одного из поставщиков сетевых ресурсов или с помощью вызываемого ресурса.
ERROR_CANNOT_OPEN_PROFILE
Системе не удается открыть профиль пользователя для обработки постоянных подключений.
ERROR_DEVICE_ALREADY_REMEMBERED
Имя локального устройства имеет запоминаемое подключение к другому сетевому ресурсу. Эта ошибка возвращается, если запись для устройства, указанного элементом lpLocalName структуры NETRESOURCE , на которую указывает параметр lpNetResource , указывает значение, которое уже находится в профиле пользователя для подключения, отличного от указанного в параметре lpNetResource .
ERROR_EXTENDED_ERROR
Произошла ошибка, относявшаяся к сети. Вызовите функцию WNetGetLastError , чтобы получить описание ошибки.
ERROR_INVALID_ADDRESS
Предпринята попытка доступа к недопустимому адресу. Эта ошибка возвращается, если параметр dwFlags задает значение CONNECT_REDIRECT, но элемент lpLocalName структуры NETRESOURCE , на который указывает параметр lpNetResource , не указан.
ERROR_INVALID_PARAMETER
Неправильный параметр. Эта ошибка возвращается, если элемент dwType структуры NETRESOURCE , на который указывает параметр lpNetResource , задает значение, отличное от RESOURCETYPE_DISK, RESOURCETYPE_PRINT или RESOURCETYPE_ANY. Эта ошибка также возвращается, если параметр dwFlags указывает неверное или неизвестное значение.
ERROR_INVALID_PASSWORD
Указанный пароль недопустим, а флаг CONNECT_INTERACTIVE не установлен.
ERROR_LOGON_FAILURE
Сбой входа из-за неизвестного имени пользователя или неправильного пароля.
ERROR_NO_NET_OR_BAD_PATH
Ни поставщики сети не приняли указанный сетевой путь. Эта ошибка возвращается, если поставщик сети не распознал элемент lpRemoteName структуры NETRESOURCE, на которую указывает параметр lpNetResource .
ERROR_NO_NETWORK
Сеть недоступна.
Другое
Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

Комментарии

В 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 , см. в статье Добавление сетевого подключения и назначение диска к общей папке.

Примечание

Заголовок winnetwk.h определяет WNetAddConnection2 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

   
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header winnetwk.h
Библиотека Mpr.lib
DLL Mpr.dll

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

NETRESOURCE

WNetAddConnection3

WNetCancelConnection2

WNetGetConnection

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

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