Функция WNetUseConnectionA (winnetwk.h)

Статья
03/08/2023

Функция WNetUseConnection устанавливает подключение к сетевому ресурсу. Функция может перенаправлять локальное устройство в сетевой ресурс.

Функция WNetUseConnection аналогична функции WNetAddConnection3 . Разница main заключается в том, что WNetUseConnection может автоматически выбрать неиспользуемое локальное устройство для перенаправления на сетевой ресурс.

Синтаксис

DWORD WNetUseConnectionA(
  [in]      HWND           hwndOwner,
  [in]      LPNETRESOURCEA lpNetResource,
  [in]      LPCSTR         lpPassword,
  [in]      LPCSTR         lpUserId,
  [in]      DWORD          dwFlags,
  [out]     LPSTR          lpAccessName,
  [in, out] LPDWORD        lpBufferSize,
  [out]     LPDWORD        lpResult
);

Параметры

[in] hwndOwner

Обработка окна, которое поставщик сетевых ресурсов может использовать в качестве окна владельца для диалоговых окон. Используйте этот параметр, если вы задали значение CONNECT_INTERACTIVE в параметре dwFlags .

[in] lpNetResource

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

Необходимо указать следующие элементы структуры NETRESOURCE .

Член	Значение
dwType	Указывает тип ресурса, к которому необходимо подключиться. Наиболее эффективно указать тип ресурса в этом элементе, например RESOURCETYPE_DISK или RESOURCETYPE_PRINT. Однако если элемент lpLocalName имеет значение NULL или указывает на пустую строку, а CONNECT_REDIRECT не задан, dwType можно RESOURCETYPE_ANY. Этот метод работает только в том случае, если функция не выбирает устройство для перенаправления на сетевой ресурс автоматически. Хотя этот элемент является обязательным, его сведения могут быть проигнорированы поставщиком сетевых служб.
lpLocalName	Указатель на строку, завершающуюся значением NULL, которая указывает имя локального устройства для перенаправления, например "F:" или "LPT1". Строка обрабатывается без учета регистра. Если строка пуста или lpLocalName имеет значение NULL, подключение к сети происходит без перенаправления. Если значение CONNECT_REDIRECT задано в параметре dwFlags или для сети требуется перенаправленное локальное устройство, функция выбирает локальное устройство для перенаправления и возвращает имя устройства в параметре lpAccessName .
lpRemoteName	Указатель на строку, завершающуюся нулевым значением, которая указывает сетевой ресурс для подключения. Строка может содержать до MAX_PATH символов и должна соответствовать соглашениям об именовании поставщика сети.
lpProvider	Указатель на строку, завершающуюся нулевым значением, которая указывает поставщика сети, к которому нужно подключиться. Если lpProvider имеет значение NULL или указывает на пустую строку, операционная система пытается определить правильного поставщика, проанализировав строку, на которую указывает элемент lpRemoteName . Если этот элемент не равен NULL, операционная система пытается установить подключение только к именованным поставщику сети. Этот член следует задавать только в том случае, если вы знаете поставщика сети, который вы хотите использовать. В противном случае дайте операционной системе определить, с каким поставщиком сопоставляется сетевое имя.

Функция WNetUseConnection игнорирует другие элементы структуры NETRESOURCE . Дополнительные сведения см. в следующих описаниях для параметра dwFlags .

[in] lpPassword

Указатель на константную строку, завершающуюся значением NULL, которая указывает пароль, используемый при подключении к сети.

Если lpPassword имеет значение NULL, функция использует текущий пароль по умолчанию, связанный с пользователем, указанным в lpUserID.

Если lpPassword указывает на пустую строку, функция не использует пароль.

Если подключение завершается сбоем из-за недопустимого пароля и в параметре dwFlags задано значение CONNECT_INTERACTIVE, функция отображает диалоговое окно с запросом на ввод пароля.

[in] lpUserId

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

Если lpUserID имеет значение NULL, функция использует имя пользователя по умолчанию. (Контекст пользователя для процесса предоставляет имя пользователя по умолчанию.)

Параметр lpUserID указывается, когда пользователи хотят подключиться к сетевому ресурсу, для которого им назначено имя пользователя или учетная запись, отличные от имени пользователя или учетной записи по умолчанию.

Строка имени пользователя представляет контекст безопасности. Он может быть специфичным для сетевого поставщика.

[in] dwFlags

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

Значение	Значение
CONNECT_INTERACTIVE	Если этот флаг установлен, операционная система может взаимодействовать с пользователем для проверки подлинности.
CONNECT_PROMPT	Этот флаг предписывает системе не использовать параметры по умолчанию для имен пользователей или паролей, не предлагая пользователю возможность предоставить альтернативу. Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE.
CONNECT_REDIRECT	Этот флаг принудительно выполняет перенаправление локального устройства при подключении. Если элемент lpLocalNamenetRESOURCE указывает локальное устройство для перенаправления, этот флаг не действует, так как операционная система по-прежнему пытается перенаправить указанное устройство. Когда операционная система автоматически выбирает локальное устройство, член dwType не должен быть равен RESOURCETYPE_ANY. Если этот флаг не установлен, локальное устройство автоматически выбирается для перенаправления, только если сеть требует перенаправления локального устройства. Windows XP: Когда система автоматически назначает буквы сетевого диска, назначаются буквы, начинающиеся с Z:, затем Y:, и заканчивающиеся C:. Это снижает вероятность конфликта между буквами дисков для каждого входа (например, буквами сетевых дисков) и буквами глобальных дисков (например, дисков). Обратите внимание, что в предыдущих выпусках были назначены буквы диска, начинающиеся с C: и заканчивающиеся буквами Z:.
CONNECT_UPDATE_PROFILE	Этот флаг указывает операционной системе сохранить подключение к сетевым ресурсам. Если этот битовый флаг установлен, операционная система автоматически пытается восстановить подключение при входе пользователя в систему. Система запоминает только успешные подключения, которые перенаправляют локальные устройства. Он не запоминает неудачные подключения или подключения без устройства. (Подключение без устройства возникает, если lpLocalName имеет значение NULL или указывает на пустую строку.) Если этот битовый флаг не установлен, операционная система не восстанавливает подключение автоматически при входе в систему.
CONNECT_COMMANDLINE	Если этот флаг установлен, операционная система запрашивает проверку подлинности пользователя с помощью командной строки, а не графического пользовательского интерфейса (GUI). Этот флаг игнорируется, если не задано CONNECT_INTERACTIVE. Windows 2000/NT и Windows Me/98/95: Это значение не поддерживается.
CONNECT_CMD_SAVECRED	Если этот флаг установлен и операционная система запрашивает учетные данные, диспетчер учетных данных должен сохранить учетные данные. Если диспетчер учетных данных отключен для сеанса входа вызывающего абонента или поставщик сети не поддерживает сохранение учетных данных, этот флаг игнорируется. Этот флаг также игнорируется, если вы не задали флаг CONNECT_COMMANDLINE. Windows 2000/NT и Windows Me/98/95: Это значение не поддерживается.

[out] lpAccessName

Указатель на буфер, который получает системные запросы к подключению. Этот параметр может принимать значение NULL.

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

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

[in, out] lpBufferSize

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

[out] lpResult

Указатель на переменную, которая получает дополнительные сведения о подключении. Этот параметр может иметь следующее значение.

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

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

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

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

Код возврата	Описание
ERROR_ACCESS_DENIED	Вызывающий объект не имеет доступа к сетевому ресурсу.
ERROR_ALREADY_ASSIGNED	Локальное устройство, указанное членом lpLocalName , уже подключено к сетевому ресурсу.
ERROR_BAD_DEVICE	Недопустимое значение, указанное параметром lpLocalName .
ERROR_BAD_NET_NAME	Значение, указанное членом lpRemoteName , недопустимо для любого поставщика сетевых ресурсов, так как недопустимое имя ресурса или невозможность найти именованный ресурс.
ERROR_BAD_PROVIDER	Значение, указанное членом lpProvider , не соответствует ни одному поставщику.
ERROR_CANCELLED	Попытка установить подключение была отменена пользователем через диалоговое окно от одного из поставщиков сетевых ресурсов или с помощью вызываемого ресурса.
ERROR_EXTENDED_ERROR	Произошла ошибка, относявшаяся к сети. Чтобы получить описание ошибки, вызовите функцию WNetGetLastError .
ERROR_INVALID_ADDRESS	Вызывающий объект передает указатель на буфер, к которому не удается получить доступ.
ERROR_INVALID_PARAMETER	Эта ошибка возникает в результате одного из следующих условий: Элемент lpRemoteName имеет значение NULL. Кроме того, lpAccessName не имеет значение NULL, но lpBufferSize имеет значение NULL или указывает на ноль. Член dwType не является ни RESOURCETYPE_DISK, ни RESOURCETYPE_PRINT. Кроме того, либо CONNECT_REDIRECT задано в dwFlags , а lpLocalName имеет значение NULL, либо подключение к сети, требующей перенаправления локального устройства.
ERROR_INVALID_PASSWORD	Указанный пароль недопустим, а флаг CONNECT_INTERACTIVE не установлен.
ERROR_MORE_DATA	Буфер lpAccessName слишком мал. Если перенаправляется локальное устройство, буфер должен быть достаточно большим, чтобы содержать имя локального устройства. В противном случае буфер должен быть достаточно большим, чтобы содержать строку, на которую указывает lpRemoteName, или имя подключаемого ресурса, псевдоним которого указывает на lpRemoteName. Если эта ошибка возвращается, подключение не установлено.
ERROR_NO_MORE_ITEMS	Операционная система не может автоматически выбрать локальное перенаправление, так как используются все допустимые локальные устройства.
ERROR_NO_NET_OR_BAD_PATH	Операция не может быть завершена либо из-за того, что сетевой компонент не запущен, либо из-за того, что указанное имя ресурса не распознано.
ERROR_NO_NETWORK	Сеть недоступна.

Windows Server 2003 и Windows XP: Функции WNet создают и удаляют буквы сетевых дисков в пространстве имен устройств MS-DOS, связанном с сеансом входа, так как устройства MS-DOS идентифицируются по идентификатору authenticationID. (AuthenticationID — это локальный уникальный идентификатор (LUID), связанный с сеансом входа в систему.) Это может повлиять на приложения, которые вызывают одну из функций WNet для создания буквы сетевого диска при входе одного пользователя, но запрашивают существующие буквы сетевых дисков при входе другого пользователя. Примером такой ситуации может быть создание второго входа пользователя в сеансе входа, например путем вызова функции CreateProcessAsUser , а при втором входе запускается приложение, которое вызывает функцию GetLogicalDrives . GetLogicalDrives не возвращает буквы сетевых дисков, созданные функцией WNet при первом входе в систему. Обратите внимание, что в предыдущем примере первый сеанс входа по-прежнему существует, и этот пример может применяться к любому сеансу входа, включая сеанс служб терминалов. Дополнительные сведения см. в разделе Определение имени устройства MS-DOS.

Примечание

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

Требования


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