Функция 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 . В настоящее время можно использовать следующие значения.
| Значение | Значение |
|---|---|
|
Следует помнить о подключении к сетевым ресурсам.
Если этот битовый флаг установлен, операционная система автоматически пытается восстановить подключение при входе пользователя в систему. Операционная система запоминает только успешные подключения, которые перенаправляют локальные устройства. Он не запоминает неудачные подключения или подключения без устройства. (Подключение без устройства возникает, когда элемент lpLocalName имеет значение NULL или указывает на пустую строку.) Если этот битовый флаг не задан, операционная система не пытается восстановить подключение при входе пользователя в систему. |
|
Подключение к сетевому ресурсу не следует помещать в список последних подключений.
Если этот флаг установлен и подключение успешно добавлено, подключение к сетевым ресурсам будет помещено в список последних подключений только в том случае, если с ним связано перенаправленное локальное устройство. |
|
Не следует помнить о подключении к сетевому ресурсу.
Если этот флаг установлен, операционная система не будет пытаться восстановить подключение при повторном входе пользователя в систему. |
|
Если этот флаг установлен, операционная система может взаимодействовать с пользователем для проверки подлинности. |
|
Этот флаг предписывает системе не использовать параметры по умолчанию для имен пользователей или паролей, не предлагая пользователю возможность предоставить альтернативу. Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE. |
|
Этот флаг принудительно выполняет перенаправление локального устройства при подключении.
Если элемент lpLocalNamenetRESOURCE указывает локальное устройство для перенаправления, этот флаг не действует, так как операционная система по-прежнему пытается перенаправить указанное устройство. Когда операционная система автоматически выбирает локальное устройство, член dwType не должен быть равен RESOURCETYPE_ANY. Если этот флаг не установлен, локальное устройство автоматически выбирается для перенаправления, только если сеть требует перенаправления локального устройства. Windows Server 2003 и Windows XP: Когда система автоматически назначает буквы сетевого диска, назначаются буквы, начинающиеся с Z:, затем Y:, и заканчивающиеся C:. Это снижает вероятность конфликта между буквами дисков для каждого входа (например, буквами сетевых дисков) и буквами глобальных дисков (например, дисков). Обратите внимание, что в более ранних версиях Windows назначали диску буквы, начинающиеся с C: и заканчивающиеся Z:. |
|
Если этот флаг установлен, операционная система не начинает использовать новый носитель для попытки установить подключение (например, инициировать новое коммутируемое подключение). |
|
Если этот флаг установлен, операционная система запрашивает проверку подлинности пользователя с помощью командной строки, а не графического пользовательского интерфейса (GUI). Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE.
Windows XP: Это значение поддерживается в Windows XP и более поздних версиях. |
|
Если этот флаг установлен и операционная система запрашивает учетные данные, диспетчер учетных данных должен сохранить учетные данные. Если диспетчер учетных данных отключен для сеанса входа вызывающего абонента или поставщик сети не поддерживает сохранение учетных данных, этот флаг игнорируется. Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE. Этот флаг также игнорируется, если вы не задали флаг CONNECT_COMMANDLINE.
Windows XP: Это значение поддерживается в Windows XP и более поздних версиях. |
|
Если этот флаг установлен и операционная система запрашивает учетные данные, диспетчер учетных данных сбрасывает учетные данные. Если диспетчер учетных данных отключен для сеанса входа вызывающей стороны или если поставщик сети не поддерживает сохранение учетных данных, этот флаг игнорируется. Этот флаг также игнорируется, если не задан флаг CONNECT_COMMANDLINE.
Windows Vista: Это значение поддерживается в Windows Vista и более поздних версиях. |
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращаемым значением может быть один из следующих кодов ошибок или один из кодов системных ошибок.
| Код возврата | Описание |
|---|---|
|
Вызывающий объект не имеет доступа к сетевому ресурсу. |
|
Локальное устройство, указанное членом lpLocalName , уже подключено к сетевому ресурсу. |
|
Тип локального устройства и тип сетевого ресурса не совпадают. |
|
Указанное имя устройства недопустимо. Эта ошибка возвращается, если элемент lpLocalName структуры NETRESOURCE , на который указывает параметр lpNetResource , указывает устройство, которое не может быть перенаправлено. |
|
Не найдено сетевое имя". Это значение возвращается, если элемент lpRemoteName структуры NETRESOURCE , на который указывает параметр lpNetResource , указывает ресурс, который не является приемлемым для любого поставщика сетевых ресурсов, либо потому, что имя ресурса пустое, недопустимое или потому, что именованный ресурс не может быть найден. |
|
Профиль пользователя имеет неправильный формат. |
|
Недопустимое имя указанного поставщика сети. Эта ошибка возвращается, если член lpProvider структуры NETRESOURCE , на который указывает параметр lpNetResource , задает значение, не соответствующее ни одному поставщику сети. |
|
Указанное имя пользователя недопустимо. |
|
Маршрутизатор или поставщик занят, возможно, инициализация. Вызывающий объект должен повторить попытку. |
|
Попытка установить подключение была отменена пользователем через диалоговое окно от одного из поставщиков сетевых ресурсов или с помощью вызываемого ресурса. |
|
Системе не удается открыть профиль пользователя для обработки постоянных подключений. |
|
Имя локального устройства имеет запоминаемое подключение к другому сетевому ресурсу. Эта ошибка возвращается, если запись для устройства, указанного элементом lpLocalName структуры NETRESOURCE , на которую указывает параметр lpNetResource , указывает значение, которое уже находится в профиле пользователя для подключения, отличного от указанного в параметре lpNetResource . |
|
Произошла ошибка, относявшаяся к сети. Вызовите функцию WNetGetLastError , чтобы получить описание ошибки. |
|
Предпринята попытка доступа к недопустимому адресу. Эта ошибка возвращается, если параметр dwFlags задает значение CONNECT_REDIRECT, но элемент lpLocalName структуры NETRESOURCE , на который указывает параметр lpNetResource , не указан. |
|
Неправильный параметр. Эта ошибка возвращается, если элемент dwType структуры NETRESOURCE , на который указывает параметр lpNetResource , задает значение, отличное от RESOURCETYPE_DISK, RESOURCETYPE_PRINT или RESOURCETYPE_ANY. Эта ошибка также возвращается, если параметр dwFlags указывает неверное или неизвестное значение. |
|
Указанный пароль недопустим, а флаг CONNECT_INTERACTIVE не установлен. |
|
Сбой входа из-за неизвестного имени пользователя или неправильного пароля. |
|
Ни поставщики сети не приняли указанный сетевой путь. Эта ошибка возвращается, если поставщик сети не распознал элемент lpRemoteName структуры NETRESOURCE, на которую указывает параметр lpNetResource . |
|
Сеть недоступна. |
|
Используйте 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 |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по