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