Функция WNetGetConnectionA (winnetwk.h)
Функция WNetGetConnection извлекает имя сетевого ресурса, связанного с локальным устройством.
Синтаксис
DWORD WNetGetConnectionA(
[in] LPCSTR lpLocalName,
[out] LPSTR lpRemoteName,
[in, out] LPDWORD lpnLength
);
Параметры
[in] lpLocalName
Указатель на константную строку, завершающуюся значением NULL, которая указывает имя локального устройства для получения сетевого имени.
[out] lpRemoteName
Указатель на строку, завершающуюся нулевым значением, которая получает удаленное имя, используемое для соединения.
[in, out] lpnLength
Указатель на переменную, указывающую размер буфера, на который указывает параметр lpRemoteName , в символах. Если функция завершается сбоем из-за недостаточно большого размера буфера, этот параметр возвращает требуемый размер буфера.
Возвращаемое значение
Если функция выполняется успешно, возвращаемое значение будет NO_ERROR.
Если функция завершается сбоем, возвращаемое значение представляет собой системный код ошибки, например одно из следующих значений.
| Код возврата | Описание |
|---|---|
|
Недопустимая строка, на которую указывает параметр lpLocalName . |
|
Устройство, указанное с помощью lpLocalName , не является перенаправленным устройством. Дополнительные сведения см. в разделе "Примечания". |
|
Буфер слишком мал. Параметр lpnLength указывает на переменную, содержащую требуемый размер буфера. При последующих вызовах доступны дополнительные записи. |
|
Устройство в настоящее время не подключено, но оно является постоянным. Дополнительные сведения см. в разделе "Примечания". |
|
Сеть недоступна. |
|
Произошла ошибка, относявшаяся к сети. Чтобы получить описание ошибки, вызовите функцию WNetGetLastError . |
|
Ни один из поставщиков не распознает локальное имя как имеющее подключение. Однако сеть недоступна по крайней мере для одного поставщика, которому может принадлежать подключение. |
Комментарии
Если сетевое подключение было установлено с помощью сети 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 |