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

Статья
08/27/2023

Функция WNetGetConnection извлекает имя сетевого ресурса, связанного с локальным устройством.

Синтаксис

DWORD WNetGetConnectionA(
  [in]      LPCSTR  lpLocalName,
  [out]     LPSTR   lpRemoteName,
  [in, out] LPDWORD lpnLength
);

Параметры

[in] lpLocalName

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

[out] lpRemoteName

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

[in, out] lpnLength

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

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

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

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

Код возврата	Описание
ERROR_BAD_DEVICE	Недопустимая строка, на которую указывает параметр lpLocalName .
ERROR_NOT_CONNECTED	Устройство, указанное с помощью lpLocalName , не является перенаправленным устройством. Дополнительные сведения см. в разделе "Примечания".
ERROR_MORE_DATA	Буфер слишком мал. Параметр lpnLength указывает на переменную, содержащую требуемый размер буфера. При последующих вызовах доступны дополнительные записи.
ERROR_CONNECTION_UNAVAIL	Устройство в настоящее время не подключено, но оно является постоянным. Дополнительные сведения см. в разделе "Примечания".
ERROR_NO_NETWORK	Сеть недоступна.
ERROR_EXTENDED_ERROR	Произошла ошибка, относявшаяся к сети. Чтобы получить описание ошибки, вызовите функцию WNetGetLastError .
ERROR_NO_NET_OR_BAD_PATH	Ни один из поставщиков не распознает локальное имя как имеющее подключение. Однако сеть недоступна по крайней мере для одного поставщика, которому может принадлежать подключение.

Если сетевое подключение было установлено с помощью сети Microsoft LAN Manager, а вызывающее приложение выполняется в сеансе входа, отличном от сеанса входа приложения, которое выполнило подключение, вызов функции WNetGetConnection для связанного локального устройства завершится ошибкой. Функция завершается сбоем с ERROR_NOT_CONNECTED или ERROR_CONNECTION_UNAVAIL. Это связано с тем, что подключение, выполненное с помощью Microsoft LAN Manager, отображается только для приложений, работающих в том же сеансе входа, что и приложение, создающее подключение. (Чтобы предотвратить сбой вызова WNetGetConnection , недостаточно, чтобы приложение выполнялось в учетной записи пользователя, создавшего подключение.)

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

Примеры

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

Примечание

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

Требования


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