Функция WNetUseConnectionA (winnetwk.h)
Функция WNetUseConnection делает подключение к сетевому ресурсу. Функция может перенаправить локальное устройство в сетевой ресурс.
Функция 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.
Функция WNetUseConnection
[in] lpPassword
Указатель на константу, null-завершенную строку, которая указывает пароль для использования при подключении к сети.
Если lpPasswordNULL, функция использует текущий пароль по умолчанию, связанный с пользователем, указанным lpUserID.
Если lpPassword указывает на пустую строку, функция не использует пароль.
Если подключение завершается ошибкой из-за недопустимого пароля, а значение CONNECT_INTERACTIVE задано в параметре dwFlags
[in] lpUserId
Указатель на константу null-terminated string, указывающую имя пользователя для создания подключения.
Если lpUserIDNULL, функция использует имя пользователя по умолчанию. (Контекст пользователя для процесса предоставляет имя пользователя по умолчанию.)
Параметр lpUserID указывается, когда пользователи хотят подключиться к сетевому ресурсу, для которого они были назначены имя пользователя или учетная запись, отличные от имени пользователя или учетной записи по умолчанию.
Строка имени пользователя представляет контекст безопасности. Это может быть конкретно для поставщика сети.
[in] dwFlags
Набор битовых флагов, описывающих подключение. Этот параметр может быть любым сочетанием следующих значений.
| Ценность | Значение |
|---|---|
|
Если этот флаг задан, операционная система может взаимодействовать с пользователем в целях проверки подлинности. |
|
Этот флаг указывает системе не использовать параметры по умолчанию для имен пользователей или паролей без предоставления пользователю возможности предоставить альтернативу. Этот флаг игнорируется, если CONNECT_INTERACTIVE также не задан. |
|
Этот флаг принудительно перенаправляет локальное устройство при подключении.
Если lpLocalName член NETRESOURCE указывает локальное устройство для перенаправления, этот флаг не действует, так как операционная система по-прежнему пытается перенаправить указанное устройство. Когда операционная система автоматически выбирает локальное устройство, элемент dwType Если этот флаг не задан, локальное устройство автоматически выбирается для перенаправления, только если для сети требуется перенаправление локального устройства. Windows XP: Когда система автоматически назначает буквы сетевого диска, буквы назначаются начиная с Z:, а затем Y:, и заканчивая C:. Это уменьшает столкновение между буквами диска для входа (например, буквами сетевого диска) и глобальными буквами дисков (например, дисками). Обратите внимание, что предыдущие выпуски назначили буквы дисков, начиная с C: и заканчивая Z:. |
|
Этот флаг указывает операционной системе хранить подключение к сетевому ресурсу.
Если установлен этот битовый флаг, операционная система автоматически пытается восстановить подключение при входе пользователя. Система запоминает только успешные подключения, которые перенаправляют локальные устройства. Он не запоминает подключения, которые являются неудачными или без устройств. (Подключение без устройства возникает, когда lpLocalNameNULL или когда указывает на пустую строку.) Если этот битовый флаг ясно, операционная система не восстанавливает подключение при входе в систему. |
|
Если этот флаг задан, операционная система запрашивает у пользователя проверку подлинности с помощью командной строки вместо графического пользовательского интерфейса (GUI). Этот флаг игнорируется, если CONNECT_INTERACTIVE также не задан.
Windows 2000/NT и Windows Me/98/95: Это значение не поддерживается. |
|
Если этот флаг задан, а операционная система запрашивает учетные данные, учетные данные должны сохраняться диспетчером учетных данных. Если диспетчер учетных данных отключен для сеанса входа вызывающего абонента или если поставщик сети не поддерживает сохранение учетных данных, этот флаг игнорируется. Этот флаг также игнорируется, если не задан флаг 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
Указатель на переменную, которая получает дополнительные сведения о подключении. Этот параметр может быть следующим значением.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение NO_ERROR.
Если функция завершается ошибкой, возвращаемое значение является системным кодом ошибки, например одно из следующих значений.
| Возвращаемый код | Описание |
|---|---|
|
Вызывающий объект не имеет доступа к сетевому ресурсу. |
|
Локальное устройство, указанное элементом lpLocalName, уже подключено к сетевому ресурсу. |
|
Недопустимое значение, указанное lpLocalName. |
|
Значение, указанное элементом lpRemoteName, не допускается любому поставщику сетевых ресурсов, так как имя ресурса недопустимо или поскольку именованный ресурс не может быть расположен. |
|
Значение, указанное элементом lpProvider, не соответствует ни одному поставщику. |
|
Попытка сделать подключение отменена пользователем через диалоговое окно из одного из поставщиков сетевых ресурсов или вызываемого ресурса. |
|
Произошла ошибка, зависявшая от сети. Чтобы получить описание ошибки, вызовите функцию WNetGetLastError. |
|
Вызывающий объект передает указатель на буфер, к которому не удалось получить доступ. |
|
Эта ошибка является результатом одного из следующих условий:
|
|
Указанный пароль недопустим, и флаг CONNECT_INTERACTIVE не задан. |
|
Буфер lpAccessName слишком мал.
Если локальное устройство перенаправляется, буфер должен быть достаточно большим, чтобы содержать имя локального устройства. В противном случае буфер должен быть достаточно большим, чтобы содержать строку, указанную lpRemoteName, или имя подключаемого ресурса, псевдоним которого указывает на lpRemoteName. Если эта ошибка возвращается, подключение не было сделано. |
|
Операционная система не может автоматически выбрать локальное перенаправление, так как все допустимые локальные устройства используются. |
|
Не удалось завершить операцию, так как сетевой компонент не запущен или не распознается указанное имя ресурса. |
|
Сеть недоступна. |
Замечания
Windows Server 2003 и Windows XP: Функции WNet создают и удаляют буквы сетевого диска в пространстве имен устройства MS-DOS, связанном с сеансом входа, так как MS-DOS устройства определяются идентификатором AuthenticationID. (Идентификатор проверки подлинности — это локально уникальный идентификаторили LUID, связанный с сеансом входа.) Это может повлиять на приложения, которые вызывают одну из функций WNet, чтобы создать букву сетевого диска под одним входом пользователя, но запрашивать существующие буквы сетевого диска под другим пользователем. Примером этой ситуации может быть создание второго входа пользователя в сеанс входа, например путем вызова функции CreateProcessAsUser, а второй вход запускает приложение, которое вызывает функцию GetLogicalDrives. GetLogicalDrives не возвращает буквы сетевого диска, созданные функцией WNet при первом входе. Обратите внимание, что в предыдущем примере первый сеанс входа по-прежнему существует, и пример может применяться к любому сеансу входа, включая сеанс служб терминалов. Дополнительные сведения см. в разделе Определение MS-DOS имени устройства.
Заметка
Заголовок winnetwk.h определяет WNetUseConnection в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 2000 Профессиональный [только классические приложения] |
| минимальный поддерживаемый сервер | Windows 2000 Server [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winnetwk.h |
| библиотеки |
Mpr.lib |
| DLL | Mpr.dll |
См. также
Обзор сети Windows (WNet)