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

Статья
11/20/2024

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

Примечание Эта функция предоставляется только для совместимости с 16-разрядными версиями Windows. Другие приложения на основе Windows должны вызывать WNetAddConnection2 или функцию WNetAddConnection3.

Синтаксис

DWORD WNetAddConnectionA(
  [in] LPCSTR lpRemoteName,
  [in] LPCSTR lpPassword,
  [in] LPCSTR lpLocalName
);

Параметры

[in] lpRemoteName

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

[in] lpPassword

Указатель на константу null-terminated string, которая указывает пароль, используемый для подключения. Обычно этот параметр является паролем, связанным с текущим пользователем.

Если этот параметр null, используется пароль по умолчанию. Если строка пуста, пароль не используется.

Windows Me/98/95: Этот параметр должен быть NULL или пустую строку.

[in] lpLocalName

Указатель на константу, null-завершенную строку, указывающую имя перенаправленного локального устройства, например "F:" или "LPT1". Строка обрабатывается без учета регистра. Если строка NULL, подключение к сетевому ресурсу выполняется без перенаправления локального устройства.

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

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

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

Возвращаемый код	Описание
ERROR_ACCESS_DENIED	Вызывающий объект не имеет доступа к сетевому ресурсу.
ERROR_ALREADY_ASSIGNED	Устройство, указанное в параметре lpLocalName, уже подключено.
ERROR_BAD_DEV_TYPE	Тип устройства и тип ресурса не совпадают.
ERROR_BAD_DEVICE	Недопустимое значение, указанное в параметре lpLocalName.
ERROR_BAD_NET_NAME	Значение, указанное в параметре lpRemoteName, недопустимо или не может быть расположено.
ERROR_BAD_PROFILE	Профиль пользователя находится в неправильном формате.
ERROR_CANNOT_OPEN_PROFILE	Система не может открыть профиль пользователя для обработки постоянных подключений.
ERROR_DEVICE_ALREADY_REMEMBERED	Запись для устройства, указанного в параметре lpLocalName, уже находится в профиле пользователя.
ERROR_EXTENDED_ERROR	Произошла ошибка, зависявшая от сети. Чтобы получить описание ошибки, вызовите функцию WNetGetLastError.
ERROR_INVALID_PASSWORD	Указанный пароль недопустим.
ERROR_NO_NET_OR_BAD_PATH	Невозможно выполнить операцию, так как сетевой компонент не запущен или поскольку указанное имя не может использоваться.
ERROR_NO_NETWORK	Сеть недоступна.

Замечания

В 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, вызывает функцию WNetAddConnection, сопоставленный диск отображается для всех сеансов входа пользователя.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	winnetwk.h
библиотеки	Mpr.lib
DLL	Mpr.dll