Функция InternetConnectW (wininet.h)

Статья
11/20/2024

Открывает протокол передачи файлов (FTP) или сеанс HTTP для данного сайта.

Синтаксис

HINTERNET InternetConnectW(
  [in] HINTERNET     hInternet,
  [in] LPCWSTR       lpszServerName,
  [in] INTERNET_PORT nServerPort,
  [in] LPCWSTR       lpszUserName,
  [in] LPCWSTR       lpszPassword,
  [in] DWORD         dwService,
  [in] DWORD         dwFlags,
  [in] DWORD_PTR     dwContext
);

Параметры

[in] hInternet

Дескриптор, возвращаемый предыдущим вызовом InternetOpen.

[in] lpszServerName

Указатель на строку null-terminated, указывающую имя узла интернет-сервера. Кроме того, строка может содержать IP-номер сайта в формате ASCII dotted-decimal (например, 11.0.1.45).

[in] nServerPort

Протокол управления передачей или порт TCP/IP на сервере. Эти флаги задают только используемый порт. Служба задается значением dwService. Этот параметр может быть одним из следующих значений.

Ценность	Значение
INTERNET_DEFAULT_FTP_PORT	Использует порт по умолчанию для FTP-серверов (порт 21).
INTERNET_DEFAULT_GOPHER_PORT	Использует порт по умолчанию для серверов Gopher (порт 70). примечание Windows XP и Windows Server 2003 R2 и более ранних версий.
INTERNET_DEFAULT_HTTP_PORT	Использует порт по умолчанию для HTTP-серверов (порт 80).
INTERNET_DEFAULT_HTTPS_PORT	Использует порт по умолчанию для серверов протокола HTTPS (порт 443).
INTERNET_DEFAULT_SOCKS_PORT	Использует порт по умолчанию для серверов брандмауэра SOCKS (порт 1080).
INTERNET_INVALID_PORT_NUMBER	Использует порт по умолчанию для службы, указанной dwService.

[in] lpszUserName

Указатель на строку null-terminated, указывающую имя пользователя для входа. Если этот параметр null, функция использует соответствующий параметр по умолчанию. Для протокола FTP по умолчанию используется "анонимный".

[in] lpszPassword

Указатель на строку null-terminated, содержащую пароль для входа. Если оба lpszPasswordи l lpszUsernameNULL, функция использует пароль по умолчанию "анонимный". В случае FTP пароль по умолчанию — это имя электронной почты пользователя. Если lpszPasswordNULL, но lpszUsername не NULL, функция использует пустой пароль.

[in] dwService

Тип службы для доступа. Этот параметр может быть одним из следующих значений.

Ценность	Значение
INTERNET_SERVICE_FTP	СЛУЖБА FTP.
INTERNET_SERVICE_GOPHER	Служба gopher. примечание Windows XP и Windows Server 2003 R2 и более ранних версий.
INTERNET_SERVICE_HTTP	СЛУЖБА HTTP.

[in] dwFlags

Параметры, относящиеся к используемой службе. Если
dwService INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE заставляет приложение использовать пассивные семантики FTP.

[in] dwContext

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

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

Возвращает допустимый дескриптор сеанса, если подключение выполнено успешно или NULL в противном случае. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError. Приложение также может использовать InternetGetLastResponseInfo, чтобы определить, почему доступ к службе был отклонен.

Замечания

В следующей таблице описано поведение четырех возможных параметров lpszUsername и lpszPassword.

lpszUsername	lpszPassword	Имя пользователя, отправленное на FTP-сервер	Пароль, отправленный на FTP-сервер
NULL	NULL	"анонимный"	Имя электронной почты пользователя
СтрокаNULL	NULL	lpszUsername	""
NULL	СтрокаNULL	ОШИБКА	ОШИБКА
СтрокаNULL	СтрокаNULL	lpszUsername	lpszPassword

Для сайтов FTP InternetConnect фактически устанавливает подключение к серверу; для других пользователей фактическое подключение не устанавливается, пока приложение не запрашивает определенную транзакцию.

Для максимальной эффективности приложения, использующие протоколы HTTP, должны попытаться свести к минимуму вызовы InternetConnect и избежать вызова этой функции для каждой транзакции, запрошенной пользователем. Одним из способов этого является сохранение небольшого кэша дескрипторов, возвращаемых из InternetConnect; Когда пользователь отправляет запрос на ранее доступ к серверу, этот дескриптор сеанса по-прежнему доступен.

После завершения вызова приложения с помощью дескриптора HINTERNET , возвращаемого InternetConnect, его необходимо закрыть с помощью функции InternetCloseHandle.

Примечание Если запрос отправляется асинхронный режим (параметр dwFlagsInternetOpen указывает INTERNET_FLAG_ASYNC), а параметр dwContext равен нулю (INTERNET_NO_CALLBACK), функция обратного вызова с InternetSetStatusCallback на дескрипторе подключения не будет вызываться, однако вызов по-прежнему будет выполняться в асинхронном режиме.

Примеры использования InternetConnect см. в следующих разделах.

Как и все остальные аспекты API WinINet, эта функция не может быть безопасно вызвана из dllMain или конструкторов и деструкторов глобальных объектов.

Примечание WinINet не поддерживает реализации сервера. Кроме того, его не следует использовать из службы. Для реализации или служб сервера microsoft Windows HTTP Services (WinHTTP).

Заметка

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

Требования

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

См. также

включение функций Интернета

функций WinINet

Поделиться через