Функция WNetAddConnection3A (winnetwk.h)
Функция WNetAddConnection3 устанавливает подключение к сетевому ресурсу. Функция может перенаправлять локальное устройство в сетевой ресурс.
Функция WNetAddConnection3 аналогична функции WNetAddConnection2 . Разница main заключается в том, что WNetAddConnection3 имеет дополнительный параметр, дескриптор окна, который поставщик сетевых ресурсов может использовать в качестве окна-владельца для диалоговых окон. Функции WNetAddConnection2 и WNetAddConnection3 заменяют функцию WNetAddConnection .
Синтаксис
DWORD WNetAddConnection3A(
[in] HWND hwndOwner,
[in] LPNETRESOURCEA lpNetResource,
[in] LPCSTR lpPassword,
[in] LPCSTR lpUserName,
[in] DWORD dwFlags
);
Параметры
[in] hwndOwner
Дескриптор окна, который поставщик сетевых ресурсов может использовать в качестве окна владельца для диалоговых окон. Используйте этот параметр, если вы задали значение CONNECT_INTERACTIVE в параметре dwFlags .
Параметр hwndOwner может иметь значение NULL. Если это так, вызов WNetAddConnection3 эквивалентен вызову функции WNetAddConnection2 .
[in] lpNetResource
Указатель на структуру NETRESOURCE , которая указывает сведения о предполагаемом подключении, например сведения о сетевом ресурсе, локальном устройстве и поставщике сетевых ресурсов.
Необходимо указать следующие элементы структуры NETRESOURCE .
Функция WNetAddConnection3 игнорирует другие элементы структуры 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
Набор параметров подключения. В настоящее время определены следующие значения.
| Значение | Значение |
|---|---|
|
Если этот флаг установлен, операционная система может взаимодействовать с пользователем для проверки подлинности. |
|
Этот флаг предписывает системе не использовать параметры по умолчанию для имен пользователей или паролей, не предлагая пользователю возможность предоставить альтернативу. Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE. |
|
Этот флаг принудительно выполняет перенаправление локального устройства при подключении.
Если элемент lpLocalNamenetRESOURCE указывает локальное устройство для перенаправления, этот флаг не действует, так как операционная система по-прежнему пытается перенаправить указанное устройство. Когда операционная система автоматически выбирает локальное устройство, член dwType не должен быть равен RESOURCETYPE_ANY. Если этот флаг не установлен, локальное устройство автоматически выбирается для перенаправления, только если сеть требует перенаправления локального устройства. Windows Server 2003 и Windows XP: Когда система автоматически назначает буквы сетевого диска, назначаются буквы, начинающиеся с Z:, затем Y:, и заканчивающиеся C:. Это снижает вероятность конфликта между буквами дисков для каждого входа (например, буквами сетевых дисков) и буквами глобальных дисков (например, дисков). Обратите внимание, что в более ранних версиях Windows назначали диску буквы, начинающиеся с C: и заканчивающиеся Z:. |
|
Следует помнить о подключении к сетевым ресурсам.
Если этот битовый флаг установлен, операционная система автоматически пытается восстановить подключение при входе пользователя в систему. Операционная система запоминает только успешные подключения, которые перенаправляют локальные устройства. Он не запоминает неудачные подключения или подключения без устройства. (Подключение без устройства возникает, когда элемент lpLocalName имеет значение NULL или когда он указывает на пустую строку.) Если этот битовый флаг не установлен, операционная система не восстанавливает подключение автоматически при входе в систему. |
|
Если этот флаг установлен, операционная система запрашивает проверку подлинности пользователя с помощью командной строки, а не графического пользовательского интерфейса (GUI). Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE.
Windows 2000/NT и Windows Me/98/95: Это значение не поддерживается. |
|
Если этот флаг установлен и операционная система запрашивает учетные данные, диспетчер учетных данных должен сохранить учетные данные. Если диспетчер учетных данных отключен для сеанса входа вызывающего абонента или поставщик сети не поддерживает сохранение учетных данных, этот флаг игнорируется. Этот флаг также игнорируется, если вы не задали флаг CONNECT_COMMANDLINE.
Windows 2000/NT и Windows Me/98/95: Это значение не поддерживается. |
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки, например одно из следующих значений.
| Код возврата | Описание |
|---|---|
|
Вызывающий объект не имеет доступа к сетевому ресурсу. |
|
Локальное устройство, указанное элементом lpLocalName , уже подключено к сетевому ресурсу. |
|
Тип локального устройства и тип сетевого ресурса не совпадают. |
|
Недопустимое значение, указанное в параметре lpLocalName . |
|
Значение, указанное элементом lpRemoteName , недопустимо для любого поставщика сетевых ресурсов, поскольку имя ресурса недопустимо или поскольку именованный ресурс не может быть найден. |
|
Профиль пользователя имеет неправильный формат. |
|
Значение, указанное элементом lpProvider , не соответствует ни одному поставщику. |
|
Маршрутизатор или поставщик занят, возможно, инициализируется. Вызывающий объект должен повторить попытку. |
|
Попытка установить подключение была отменена пользователем с помощью диалогового окна одного из поставщиков сетевых ресурсов или вызываемого ресурса. |
|
Системе не удается открыть профиль пользователя для обработки постоянных подключений. |
|
Запись для устройства, указанного элементом lpLocalName , уже находится в профиле пользователя. |
|
Произошла ошибка, относявшаяся к сети. Вызовите функцию WNetGetLastError , чтобы получить описание ошибки. |
|
Указанный пароль недопустим, а флаг CONNECT_INTERACTIVE не установлен. |
|
Невозможно выполнить операцию, так как не запущен сетевой компонент или невозможно использовать указанное имя. |
|
Сеть недоступна. |
Комментарии
Функция WNetUseConnection аналогична функции WNetAddConnection3 . Разница main заключается в том, что WNetUseConnection может автоматически выбрать неиспользуемое локальное устройство для перенаправления на сетевой ресурс.
В 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, вызывает функцию WNetAddConnection3 , сопоставленный диск будет виден всем сеансам входа пользователя.
Для поставщиков сетей Майкрософт элемент 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: Если функция WNetAddConnection3 вызывается с явными учетными данными пользователя, указанными в pUsername и lpPassword , чтобы установить подключение к сетевому ресурсу на определенном сервере, а затем снова вызывается с помощью любого из этих параметров в качестве NULL (для использования имени пользователя по умолчанию или пароля по умолчанию) к тому же серверу, вызов с ошибкой. Возвращенная ошибка будет ERROR_BAD_USERNAME или ERROR_INVALID_PASSWORD.
Примечание
Заголовок winnetwk.h определяет WNetAddConnection3 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | winnetwk.h |
| Библиотека | Mpr.lib |
| DLL | Mpr.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по