Функция 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.
Функция WNetAddConnection 2 игнорирует другие элементы структуры NETRESOURCE.
[in] lpPassword
Указатель на константу, null-завершенную строку, которая указывает пароль, используемый при подключении к сети.
Если lpPasswordNULL, функция использует текущий пароль по умолчанию, связанный с пользователем, указанным параметром lpUserName.
Если lpPassword указывает на пустую строку, функция не использует пароль.
Если подключение завершается ошибкой из-за недопустимого пароля, а значение CONNECT_INTERACTIVE задано в параметре dwFlags
Windows Me/98/95: Этот параметр должен быть NULL или пустую строку.
[in] lpUserName
Указатель на константу null-завершенную строку, указывающую имя пользователя для создания соединения.
Если lpUserNameNULL, функция использует имя пользователя по умолчанию. (Контекст пользователя для процесса предоставляет имя пользователя по умолчанию.)
Параметр lpUserName указывается, когда пользователи хотят подключиться к сетевому ресурсу, для которого они были назначены имя пользователя или учетная запись, отличные от имени пользователя или учетной записи по умолчанию.
Строка имени пользователя представляет контекст безопасности. Это может быть конкретно для поставщика сети.
Windows Me/98/95: Этот параметр должен быть NULL или пустую строку.
[in] dwFlags
Набор параметров подключения. Возможные значения параметров подключения определяются в файле заголовка Winnetwk.h. В настоящее время можно использовать следующие значения.
| Ценность | Значение |
|---|---|
|
Необходимо помнить подключение к сетевому ресурсу.
Если установлен этот битовый флаг, операционная система автоматически пытается восстановить подключение при входе пользователя. Операционная система запоминает только успешные подключения, которые перенаправляют локальные устройства. Он не запоминает подключения, которые являются неудачными или без устройств. (Подключение без устройства возникает, когда элемент lpLocalNameNULL или указывает на пустую строку.) Если этот битовый флаг ясно, операционная система не пытается восстановить подключение при входе пользователя. |
|
Подключение к сетевому ресурсу не должно быть помещено в список последних подключений.
Если этот флаг установлен и подключение успешно добавлено, подключение к сетевому ресурсу будет помещено в последний список подключений, только если он связан с ним перенаправленным локальным устройством. |
|
Подключение к сетевому ресурсу не должно запоминаться.
Если этот флаг задан, операционная система не попытается восстановить подключение при повторном входе пользователя. |
|
Если этот флаг задан, операционная система может взаимодействовать с пользователем в целях проверки подлинности. |
|
Этот флаг указывает системе не использовать параметры по умолчанию для имен пользователей или паролей без предоставления пользователю возможности предоставить альтернативу. Этот флаг игнорируется, если CONNECT_INTERACTIVE также не задан. |
|
Этот флаг принудительно перенаправляет локальное устройство при подключении.
Если lpLocalName член NETRESOURCE указывает локальное устройство для перенаправления, этот флаг не действует, так как операционная система по-прежнему пытается перенаправить указанное устройство. Когда операционная система автоматически выбирает локальное устройство, элемент dwType Если этот флаг не задан, локальное устройство автоматически выбирается для перенаправления, только если для сети требуется перенаправление локального устройства. 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, уже подключено к сетевому ресурсу. |
|
Тип локального устройства и тип сетевого ресурса не совпадают. |
|
Указанное имя устройства недопустимо. Эта ошибка возвращается, если элемент |
|
Не удается найти имя сети. Это значение возвращается, если элемент lpRemoteName структуры NETRESOURCE, на которую указывает параметр lpNetResource, указывает ресурс, недопустимый для любого поставщика сетевых ресурсов, так как имя ресурса является пустым, недопустимым или поскольку именованный ресурс не может находиться. |
|
Профиль пользователя находится в неправильном формате. |
|
Недопустимое имя указанного поставщика сети. Эта ошибка возвращается, если элемент |
|
Указанное имя пользователя недопустимо. |
|
Маршрутизатор или поставщик занят, возможно, инициализация. Вызывающий объект должен повторить попытку. |
|
Попытка сделать подключение отменена пользователем через диалоговое окно из одного из поставщиков сетевых ресурсов или вызываемого ресурса. |
|
Система не может открыть профиль пользователя для обработки постоянных подключений. |
|
Имя локального устройства имеет запомнить подключение к другому сетевому ресурсу. Эта ошибка возвращается, если запись для устройства, указанного lpLocalName член структуры NETRESOURCE, на которую указывает параметр lpNetResource, указывает значение, которое уже находится в профиле пользователя для другого подключения, отличного от указанного в параметре lpNetResource. |
|
Произошла ошибка, зависявшая от сети. Вызовите функцию |
|
Предпринята попытка получить доступ к недопустимому адресу. Эта ошибка возвращается, если параметр dwFlags указывает значение CONNECT_REDIRECT, но элемент lpLocalName структуры NETRESOURCE, на которую указывает параметр lpNetResource. |
|
Неправильный параметр. Эта ошибка возвращается, если элемент dwType структуры NETRESOURCE, на которую указывает параметр lpNetResource 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-адрес, но это зависит от конкретного сетевого поставщика.
Примеры
В следующем примере кода показано, как использовать функцию 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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 2000 Профессиональный [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winnetwk.h |
| библиотеки |
Mpr.lib |
| DLL | Mpr.dll |
См. также
Обзор сети Windows (WNet)