InternetConnectA, fonction (wininet.h)
Ouvre une session FTP (File Transfer Protocol) ou HTTP pour un site donné.
Syntaxe
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
);
Paramètres
[in] hInternet
Handle retourné par un appel précédent à InternetOpen.
[in] lpszServerName
Pointeur vers une chaîne null-terminated qui spécifie le nom d’hôte d’un serveur Internet. Sinon, la chaîne peut contenir le numéro IP du site, au format pointillé-décimal ASCII (par exemple, 11.0.1.45).
[in] nServerPort
Port TCP/IP (Transmission Control Protocol) sur le serveur. Ces indicateurs définissent uniquement le port utilisé. Le service est défini par la valeur de dwService. Ce paramètre peut être l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Utilise le port par défaut pour les serveurs FTP (port 21). |
|
Utilise le port par défaut pour les serveurs Gopher (port 70).
Remarque Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
|
|
Utilise le port par défaut pour les serveurs HTTP (port 80). |
|
Utilise le port par défaut pour les serveurs HTTPS (Secure Hypertext Transfer Protocol) (port 443). |
|
Utilise le port par défaut pour les serveurs de pare-feu SOCKS (port 1080). |
|
Utilise le port par défaut du service spécifié par dwService. |
[in] lpszUserName
Pointeur vers une chaîne null-terminated qui spécifie le nom de l’utilisateur à ouvrir une session. Si ce paramètre est NULL, la fonction utilise une valeur par défaut appropriée. Pour le protocole FTP, la valeur par défaut est « anonyme ».
[in] lpszPassword
Pointeur vers une chaîne null-terminated qui contient le mot de passe à utiliser pour vous connecter. Si les deux lpszPassword et lpszUsername sont NULL, la fonction utilise le mot de passe « anonyme » par défaut. Dans le cas du protocole FTP, le mot de passe par défaut est le nom de messagerie de l’utilisateur. Si lpszPassword est NULL, mais lpszUsername n’est pas NULL, la fonction utilise un mot de passe vide.
[in] dwService
Type de service auquel accéder. Ce paramètre peut être l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Service FTP. |
|
Service de chiffrement.
Remarque Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
|
|
Service HTTP. |
[in] dwFlags
Options spécifiques au service utilisé. Si
dwService est INTERNET_SERVICE_FTP, INTERNET_FLAG_PASSIVE entraîne l’utilisation de la sémantique FTP passive de l’application.
[in] dwContext
Pointeur vers une variable qui contient une valeur définie par l’application utilisée pour identifier le contexte de l’application pour le handle retourné dans les rappels.
Valeur de retour
Retourne un handle valide à la session si la connexion réussit ou null sinon. Pour récupérer des informations d’erreur étendues, appelez GetLastError. Une application peut également utiliser InternetGetLastResponseInfo pour déterminer pourquoi l’accès au service a été refusé.
Remarques
Le tableau suivant décrit le comportement des quatre paramètres possibles de lpszUsername et lpszPassword.
| lpszUsername | lpszPassword | Nom d’utilisateur envoyé au serveur FTP | Mot de passe envoyé au serveur FTP |
|---|---|---|---|
| NULL | NULL | « anonyme » | Nom de l’e-mail de l’utilisateur |
| Chaîne de NULL non |
NULL | lpszUsername | "" |
| NULL | Chaîne de NULL non |
ERREUR | ERREUR |
| Chaîne de NULL non |
Chaîne de NULL non |
lpszUsername | lpszPassword |
Pour les sites FTP, InternetConnect établit réellement une connexion avec le serveur ; pour d’autres, la connexion réelle n’est pas établie tant que l’application n’a pas demandé une transaction spécifique.
Pour optimiser l’efficacité, les applications utilisant les protocoles HTTP doivent essayer de réduire les appels à InternetConnect et d’éviter d’appeler cette fonction pour chaque transaction demandée par l’utilisateur. Une façon d’y parvenir consiste à conserver un petit cache de handles retournés par internetConnect; lorsque l’utilisateur envoie une demande à un serveur précédemment accédé, ce handle de session est toujours disponible.
Une fois l’application appelante terminée à l’aide du handle HINTERNET
Remarque Lorsqu’une demande est envoyée en mode asynchrone (le paramètre dwFlags de InternetOpen spécifie INTERNET_FLAG_ASYNC), et que le paramètre dwContext est égal à zéro (INTERNET_NO_CALLBACK), la fonction de rappel définie avec InternetSetStatusCallback sur le handle de connexion ne sera pas appelée, mais l’appel sera toujours exécuté en mode asynchrone.
Vous trouverez des exemples d’utilisation de InternetConnect dans les rubriques suivantes.
- gestion des d’authentification
- exemple d’application asynchrone
Comme tous les autres aspects de l’API WinINet, cette fonction ne peut pas être appelée en toute sécurité à partir de DllMain ou des constructeurs et destructeurs d’objets globaux.
Note
L’en-tête wininet.h définit InternetConnect comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | wininet.h |
| bibliothèque | Wininet.lib |
| DLL | Wininet.dll |