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

Статья
11/20/2024

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

Синтаксис

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

Параметры

[in] lpLocalName

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

[out] lpRemoteName

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

[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. (Идентификатор проверки подлинности — это локально уникальный идентификаторили LUID, связанный с сеансом входа.) Это может повлиять на приложения, которые вызывают одну из функций WNet, чтобы создать букву сетевого диска под одним входом пользователя, но запрашивать существующие буквы сетевого диска под другим пользователем. Примером этой ситуации может быть создание второго входа пользователя в сеанс входа, например путем вызова функции CreateProcessAsUser, а второй вход запускает приложение, которое вызывает функцию GetLogicalDrives. GetLogicalDrives не возвращает буквы сетевого диска, созданные функцией WNet при первом входе. Обратите внимание, что в предыдущем примере первый сеанс входа по-прежнему существует, и пример может применяться к любому сеансу входа, включая сеанс служб терминалов. Дополнительные сведения см. в разделе Определение MS-DOS имени устройства.

Примеры

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

Заметка

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

Требования

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