Функция InternetConnectA (wininet.h)
Открывает сеанс FTP или HTTP для данного сайта.
Синтаксис
HINTERNET InternetConnectA(
[in] HINTERNET hInternet,
[in] LPCSTR lpszServerName,
[in] INTERNET_PORT nServerPort,
[in] LPCSTR lpszUserName,
[in] LPCSTR lpszPassword,
[in] DWORD dwService,
[in] DWORD dwFlags,
[in] DWORD_PTR dwContext
);
Параметры
[in] hInternet
Дескриптор, возвращенный предыдущим вызовом InternetOpen.
[in] lpszServerName
Указатель на строку, завершающуюся значением NULL, которая указывает имя узла интернет-сервера. Кроме того, строка может содержать IP-номер сайта в формате ASCII с точками в десятичном формате (например, 11.0.1.45).
[in] nServerPort
Порт TCP/IP на сервере. Эти флаги задают только используемый порт. Служба задается значением dwService. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Использует порт по умолчанию для FTP-серверов (порт 21). |
|
Использует порт по умолчанию для серверов Gopher (порт 70). Примечание Только Windows XP и Windows Server 2003 R2 и более ранних версий.
|
|
Использует порт по умолчанию для HTTP-серверов (порт 80). |
|
Использует порт по умолчанию для серверов HTTPS (порт 443). |
|
Использует порт по умолчанию для серверов брандмауэра SOCKS (порт 1080). |
|
Использует порт по умолчанию для службы, указанной dwService. |
[in] lpszUserName
Указатель на строку, завершающуюся значением NULL, которая указывает имя пользователя для входа. Если этот параметр имеет значение NULL, функция использует соответствующее значение по умолчанию. Для протокола FTP по умолчанию используется значение "anonymous".
[in] lpszPassword
Указатель на строку, завершающуюся значением NULL, которая содержит пароль для входа в систему. Если и lpszPassword , и lpszUsername имеют значение NULL, функция использует "анонимный" пароль по умолчанию. В случае FTP пароль по умолчанию — это имя электронной почты пользователя. Если параметр lpszPassword имеет значение NULL, а lpszUsername не имеет значение NULL, функция использует пустой пароль.
[in] dwService
Тип службы для доступа. Этот параметр может принимать одно из указанных ниже значений.
| Значение | Значение |
|---|---|
|
Служба FTP. |
|
Служба Gopher. Примечание Только Windows XP и Windows Server 2003 R2 и более ранних версий.
|
|
Служба HTTP. |
[in] dwFlags
Параметры, относящиеся к используемой службе. If
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.h определяет InternetConnect как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Professional [только классические приложения] |
| Минимальная версия сервера | Windows 2000 Server [только классические приложения] |
| Целевая платформа | Windows |
| Header | wininet.h |
| Библиотека | Wininet.lib |
| DLL | Wininet.dll |