Activation des fonctionnalités Internet

Avant d’utiliser les fonctions WinINet, l’application doit tenter d’établir une connexion à Internet à l’aide de la fonction InternetAttemptConnect . Cette fonction appelle la boîte de dialogue d’accès à distance pour établir une connexion à Internet ou case activée si une connexion existe déjà. Si cette fonction échoue, l’application peut passer en mode hors connexion, ce qui lui permet d’accéder aux informations mises en cache lors des connexions précédentes à Internet.

Utilisez la fonction InternetCheckConnection pour case activée la connexion à Internet. Il tente d’effectuer un test ping sur le serveur désigné par l’URL passée à la fonction . Si l’indicateur FLAG_ICC_FORCE_CONNECTION est défini et que l’URL a la valeur NULL, la fonction vérifie s’il existe une entrée dans la base de données du serveur pour le serveur le plus proche. S’il en existe un, la fonction effectue un test ping sur ce serveur.

Ensuite, utilisez la fonction InternetOpen pour établir les caractéristiques de la connexion Internet utilisée par l’application cliente. InternetOpen crée le handle HINTERNET racine utilisé pour établir des sessions ftphttp. InternetOpen ne teste pas la connexion à Internet pour vérifier que les caractéristiques passées à la fonction sont correctes.

Utilisez la fonction InternetConnect pour créer une session spécifique. InternetConnect initialise une session pour le site spécifié à l’aide des arguments qui lui sont passés et crée un handle HINTERNET qui est une branche du handle racine. InternetConnect ne tente pas d’accéder au site spécifié ou d’établir une connexion à celui-ci, sauf dans le cas d’une session FTP. Les fonctions FtpFindFirstFile, FtpOpenFile et HttpOpenRequest utilisent le handle créé par InternetConnect pour établir une connexion au site spécifié.

Utilisation d’InternetOpen

Pour activer une connexion à Internet, un handle HINTERNET racine doit être créé à l’aide d’InternetOpen. Informations sur l’agent utilisateur (l’application appelant les fonctions Internet), le type d’accès à Internet, les noms de proxy, les hôtes et les adresses qui contournent le proxy et le comportement sont passées à InternetOpen.

Définition de l’agent utilisateur

L’application appelante doit donner une chaîne qui contient le nom de l’application ou de l’entité accédant à Internet au paramètre lpszAgentd’InternetOpen. Cette chaîne est utilisée comme agent utilisateur dans le protocole HTTP. Par exemple, Microsoft Internet Explorer utilise « Microsoft Internet Explorer ».

Définition des types d’accès

InternetOpen prend en charge trois types d’accès :

• Utilisez INTERNET_OPEN_TYPE_DIRECT si le système sur lequel l’application s’exécute utilise une connexion directe à Internet. Les paramètres lpszProxyName et lpszProxyBypassd’InternetOpen ne sont pas utilisés et doivent être définis sur NULL.
• Utilisez INTERNET_OPEN_TYPE_PROXY si le système sur lequel l’application s’exécute utilise un ou plusieurs serveurs proxy pour accéder à Internet. InternetOpen utilise les serveurs proxy indiqués par lpszProxyName et contourne le proxy pour les noms d’hôte ou adresses IP spécifiés par lpszProxyBypass.
• Utilisez INTERNET_OPEN_TYPE_PRECONFIG pour indiquer à votre application de récupérer la configuration à partir du Registre. Il s’agit généralement du meilleur choix, car la plupart des applications, y compris les navigateurs web, utilisent cette option.

INTERNET_OPEN_TYPE_PRECONFIG examine les valeurs de Registre ProxyEnable, ProxyServer et ProxyOverride. Ces valeurs se trouvent sous « HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings ».

Si ProxyEnable est égal à zéro, l’application utilise INTERNET_OPEN_TYPE_DIRECT. Sinon, l’application utilise INTERNET_OPEN_TYPE_PROXY et utilise les informations ProxyServer et ProxyOverride .

Les fonctions WinINet prennent en charge les proxys de type SOCKS uniquement si internet Explorer est installé. L’installation d’Internet Explorer inclut le fichier Wsock32n.dll, qui est nécessaire pour prendre en charge les proxys SOCKS. Wsock32n.dll n’est pas redistribuable.

Liste des serveurs proxy

WinINet reconnaît deux types de proxys : les proxys de type CERN (HTTP uniquement) et les proxys FTP TIS (FTP uniquement). Si internet Explorer est installé, WinINet prend également en charge les proxys de type SOCKS. InternetConnect suppose, par défaut, que le proxy spécifié est un proxy CERN. Si le type d’accès est défini sur INTERNET_OPEN_TYPE_DIRECT ou INTERNET_OPEN_TYPE_PRECONFIG, le paramètre lpszProxyNamed’InternetOpen doit avoir la valeur NULL. Sinon, la valeur passée à lpszProxyName doit contenir les proxys dans une chaîne délimitée par des espaces. Les listes de proxy peuvent contenir le numéro de port utilisé pour accéder au proxy.

Pour répertorier un proxy pour un protocole spécifique, la chaîne doit suivre le format « "<protocol><protocol>://<proxy_name>" ». Les protocoles valides sont HTTP, HTTPS et FTP. Par exemple, pour répertorier un proxy FTP, une chaîne valide est « « "ftp=ftp://ftp_proxy_name:21" », où ftp_proxy_name est le nom du proxy FTP et 21 est le numéro de port qui doit être utilisé pour accéder au proxy. Si le proxy utilise le numéro de port par défaut pour ce protocole, le numéro de port peut être omis. Si un nom de proxy est répertorié par lui-même, il est utilisé comme proxy par défaut pour tous les protocoles dont aucun proxy spécifique n’est spécifié. Par exemple, « "http=https://http_proxy other" » utilise http_proxy pour toutes les opérations HTTP, tandis que tous les autres protocoles en utilisent d’autres.

Par défaut, la fonction suppose que le proxy spécifié par lpszProxyName est un proxy CERN. Une application peut spécifier plusieurs proxys, y compris différents proxys pour les différents protocoles. Par exemple, si vous spécifiez « "ftp=ftp://ftp-gw HTTP=https://jericho:99 proxy », les requêtes FTP sont effectuées via le proxy ftp-gw, qui écoute au port 21, et les requêtes HTTP sont effectuées via un proxy CERN appelé jericho, qui écoute au port 99. Dans le cas contraire, les requêtes HTTP seraient effectuées via le proxy DU CERN appelé proxy, qui écoute au port 80. Notez que si l’application utilise uniquement FTP, par exemple, elle n’a pas besoin de spécifier « "ftp=ftp://ftp-gw:21" ». Il peut spécifier simplement « "ftp-gw" ». Une application n’est requise pour spécifier les noms de protocole que si elle utilise plusieurs protocoles par handle retourné par InternetOpen.

Liste de la déviation du proxy

Les noms d’hôte ou les adresses IP qui ne doivent pas être envoyés au proxy peuvent être répertoriés dans la liste de contournement du proxy. Cette liste peut contenir des caractères génériques, « * », qui amènent l’application à contourner le serveur proxy pour les adresses qui correspondent au modèle spécifié. Pour répertorier plusieurs adresses et noms d’hôtes, séparez-les par des points-virgules dans la chaîne de contournement du proxy. Si la macro «< local> » est spécifiée, la fonction contourne le proxy pour tout nom d’hôte qui ne contient pas de point.

Par défaut, WinINet contourne le proxy pour les requêtes qui utilisent les noms d’hôte « localhost », « bouclage », « 127.0.0.1 » ou « [::1] ». Ce comportement existe, car un serveur proxy distant ne résout généralement pas correctement ces adresses.

Internet Explorer 9 : vous pouvez supprimer l’ordinateur local de la liste de contournement du proxy à l’aide de la macro «< -bouclage> ».

L’exemple suivant montre des exemples d’appels à InternetOpen à l’aide de différentes chaînes de contournement de proxy. Les commentaires au-dessus de chaque appel décrivent l’effet de la chaîne de contournement sur les noms d’hôtes accessibles à partir du handle HINTERNET qu’elle crée.

HINTERNET hInternetRoot;

/* bypass the proxy for any host name that does not 
    contain a period */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("<local>"), 0);

/* bypass the proxy for any host name that starts with the 
    letters "ms" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("ms*"), 0);

/* bypass the proxy for any host name that contains "int", 
    such as "internet" and "painter" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("*int*"), 0);

/* bypass the proxy for the host name "example" and any 
    host name that contains "test" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("example *test*"), 0);

/* Disable the loopback proxy bypass for localhost */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("127.0.0.1:8888"),TEXT("<-loopback>"), 0);

Utilisation d’InternetConnect

Pour commencer une session, la fonction InternetConnect doit créer un handle à partir du handle racine retourné par la fonction InternetOpen . InternetConnect définit l’adresse du serveur, le numéro de port, le nom d’utilisateur, le mot de passe et le type de service.

InternetConnect utilise le handle HINTERNET racine créé par InternetOpen pour établir un handle de session. Si l’indicateur INTERNET_FLAG_ASYNC a été défini dans l’appel à InternetOpen, l’appel à InternetConnect doit inclure une valeur de contexte différente de zéro.

Le nom du serveur peut contenir le nom d’hôte (par exemple, « www.servername.com ») ou le numéro IP du site au format ASCII pointillé-décimal (par exemple, « 10.0.1.45 »).

Le port du serveur est le numéro de port TCP/IP (Transmission Control Protocol/Internet Protocol) auquel se connecter sur le serveur. InternetConnect utilise le port par défaut pour le type de service sélectionné si la valeur INTERNET_INVALID_PORT_NUMBER est utilisée. Les tableaux suivants contiennent les ports de serveur par défaut pour WinINet.

Valeur	Signification
INTERNET_DEFAULT_FTP_PORT	Utilisez le port par défaut pour les serveurs FTP (port 21).
INTERNET_DEFAULT_GOPHER_PORT	Utilisez le port par défaut pour les serveurs gopher (port 70). Note: Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
INTERNET_DEFAULT_HTTP_PORT	Utilisez le port par défaut pour les serveurs HTTP (port 80).
INTERNET_DEFAULT_HTTPS_PORT	Utilisez le port par défaut pour les serveurs https (port 443).
INTERNET_DEFAULT_SOCKS_PORT	Utilisez le port par défaut pour les serveurs de pare-feu SOCKS (port 1080).

Définition du nom d’utilisateur et du mot de passe

La valeur de lpszUsername est l’adresse d’une chaîne terminée par null qui contient le nom de l’utilisateur qui se connecte. Si ce paramètre a la valeur NULL, la fonction utilise une valeur par défaut appropriée, à l’exception de HTTP. Un paramètre NULL dans HTTP entraîne le retour d’une erreur par le serveur. Pour le protocole FTP, la valeur par défaut est anonyme.

La valeur de lpszPassword est l’adresse d’une chaîne terminée par null qui contient le mot de passe de connexion. Si lpszUsername et lpszPassword ont la valeur NULL, la fonction utilise le mot de passe anonyme par défaut. Dans le cas de FTP, le mot de passe anonyme par défaut est le nom de l’e-mail de l’utilisateur. Si lpszUsername n’est pas NULL et lpszPassword a la valeur NULL, la fonction utilise un mot de passe vide. Il existe quatre paramètres possibles de lpszUsername et lpszPassword, qui produisent les comportements indiqués dans le tableau suivant.

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 non NULL	NULL	lpszUsername	""
NULL	Chaîne non NULL	ERROR	ERROR
Chaîne non NULL	Chaîne non NULL	lpszUsername	lpszPassword

Ces informations peuvent être modifiées à l’aide des fonctions InternetSetOption et InternetErrorDlg . InternetSetOption modifie les valeurs de nom d’utilisateur et de mot de passe, tandis qu’InternetErrorDlg affiche une boîte de dialogue qui demande le nom d’utilisateur et le mot de passe appropriés.

Définition de la session

Pour définir la session en cours d’établissement, définissez le type de service, les indicateurs et la valeur de contexte pour InternetConnect.

Deux types de services sont disponibles pour InternetConnect : INTERNET_SERVICE_FTP et INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP est utilisé pour les sessions HTTP et HTTPS.

INTERNET_FLAG_PASSIVE est le seul indicateur spécifique au service utilisé par les fonctions WinINet. Cet indicateur peut être défini lorsque le type de service est INTERNET_SERVICE_FTP afin d’utiliser la sémantique FTP passive.

Pour toutes les opérations synchrones, la valeur de dwContext doit être définie sur zéro. Si des opérations asynchrones ont été établies en définissant l’indicateur INTERNET_FLAG_ASYNC dans l’appel à InternetOpen, une valeur différente de zéro doit être fournie pour dwContext. Pour plus d’informations sur les opérations asynchrones, consultez Configuration des opérations asynchrones.

Pour les sessions FTP, InternetConnect tente d’établir une connexion au serveur sur Internet. Pour les sessions HTTP, InternetConnect n’établit pas de connexion tant qu’une autre fonction n’a pas tenté d’obtenir des informations à partir du serveur.

Notes

WinINet ne prend pas en charge les implémentations de serveur. En outre, il ne doit pas être utilisé à partir d’un service. Pour les implémentations de serveur ou les services, utilisez Microsoft Windows HTTP Services (WinHTTP).