Partager via

Définition et récupération des options Internet

  • Article

Cette rubrique explique comment définir et récupérer des options Internet à l’aide des fonctions InternetSetOption et InternetQueryOption .

Les options Internet peuvent être définies sur ou récupérées à partir d’un handle HINTERNET spécifié ou des paramètres actuels dans Microsoft Internet Explorer.

Étapes d’implémentation

Pour définir ou récupérer des options Internet, procédez comme suit :

Choix des options Internet

Étant donné qu’il existe de nombreuses options Internet, il est important de choisir les bonnes options. De nombreuses options Internet affectent le comportement des fonctions WinINet et des Explorer Internet :

Par exemple, vous pouvez :

  • Gérez l’authentification de base du serveur et du proxy en définissant des noms d’utilisateur et des mots de passe.
  • Définissez ou récupérez la chaîne d’agent utilisateur utilisée par les serveurs pour identifier les fonctionnalités de l’application cliente ou du navigateur.
  • Récupérez le type de handle du handle HINTERNET spécifié.

Pour plus d’informations et une liste des options Internet, consultez Indicateurs d’option.

Dans Internet Explorer 5 et versions ultérieures, certaines options peuvent être définies ou récupérées à partir d’une connexion Internet spécifique à l’aide des structures INTERNET_PER_CONN_OPTION_LIST et INTERNET_PER_CONN_OPTION. Pour plus d’informations et la liste des options qui peuvent être définies ou récupérées à partir d’une connexion Internet spécifique, consultez le membre dwOptions de la structure INTERNET_PER_CONN_OPTION .

Choix du handle HINTERNET

Le handle HINTERNET utilisé pour définir ou récupérer des options Internet détermine l’étendue de l’opération. Tous les handles créés par le biais de ce handle héritent des options définies sur ce handle.

Par exemple, les applications clientes qui nécessitent un proxy avec authentification n’ont probablement pas besoin de définir le nom d’utilisateur et le mot de passe du proxy chaque fois que l’application tente d’accéder à une ressource Internet. Si toutes les demandes sur une connexion donnée sont gérées par le même proxy, la définition du nom d’utilisateur et du mot de passe du proxy sur un handle HINTERNET de type de connexion, c’est-à-dire un handle créé par un appel à InternetConnect, permet à tous les appels dérivés de ce handle HINTERNET d’utiliser le même nom d’utilisateur proxy et le même mot de passe. La définition du nom d’utilisateur et du mot de passe du proxy chaque fois qu’un handle HINTERNET est créé par HttpOpenRequest nécessiterait une surcharge supplémentaire et inutile. N’oubliez pas que si l’application utilise un proxy qui nécessite une authentification, elle doit définir les informations d’identification du proxy sur chaque nouvelle connexion.

Définition ou récupération des options

Une fois que vous avez déterminé les options Internet et le handle HINTERNET à utiliser, récupérez ces options Internet. Pour définir ou récupérer des options, appelez InternetQueryOption ou InternetSetOption.

Étendue du handle HINTERNET

Le handle HINTERNET utilisé pour définir ou récupérer des options Internet détermine les actions pour lesquelles les options sont valides.

Ces handles ont trois niveaux :

En plus des différents handles HINTERNET, une application peut également utiliser NULL pour définir ou récupérer les valeurs par défaut des options Internet utilisées par internet Explorer et les fonctions WinINet. La définition des options Internet lors de l’utilisation de null comme handle modifie les valeurs par défaut des options, qui sont actuellement stockées dans le Registre. Les applications clientes ne doivent pas utiliser de fonctions de Registre pour modifier les valeurs par défaut des options Internet, car l’implémentation de la façon dont les options sont stockées peut être modifiée à l’avenir.

Le tableau suivant répertorie le type de handles HINTERNET et l’étendue des options Internet qui leur sont associées.

Handle Type Étendue
NULL Paramètres d’option par défaut pour Internet Explorer.
INTERNET_HANDLE_TYPE_CONNECT_FTP Paramètres d’option pour cette connexion à un serveur FTP. Ces options affectent toutes les opérations lancées à partir de ce handle HINTERNET , telles que les téléchargements de fichiers.
INTERNET_HANDLE_TYPE_CONNECT_GOPHER Paramètres d’option pour cette connexion à un serveur Gopher. Ces options affectent toutes les opérations lancées à partir de ce handle HINTERNET , telles que les téléchargements de fichiers. Note: Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
INTERNET_HANDLE_TYPE_CONNECT_HTTP Paramètres d’option pour cette connexion à un serveur HTTP. Ces options affectent toutes les opérations lancées à partir de ce handle HINTERNET , telles que les téléchargements de fichiers.
INTERNET_HANDLE_TYPE_FILE_REQUEST Paramètres d’option associés à cette demande de fichier.
INTERNET_HANDLE_TYPE_FTP_FILE Paramètres d’option associés au téléchargement de cette ressource FTP.
INTERNET_HANDLE_TYPE_FTP_FILE_HTML Les paramètres d’option associés à cette ressource FTP sont téléchargés au format HTML.
INTERNET_HANDLE_TYPE_FTP_FIND Paramètres d’option associés à cette recherche de fichiers sur un serveur FTP.
INTERNET_HANDLE_TYPE_FTP_FIND_HTML Paramètres d’option associés à cette recherche de fichiers sur un serveur FTP au format HTML.
INTERNET_HANDLE_TYPE_GOPHER_FILE Paramètres d’option associés au téléchargement de cette ressource Gopher. Note: Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML Les paramètres d’option associés à cette ressource Gopher sont téléchargés au format HTML. Note: Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
INTERNET_HANDLE_TYPE_GOPHER_FIND Paramètres d’option associés à cette recherche de fichiers sur un serveur Gopher. Note: Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML Paramètres d’option associés à cette recherche de fichiers sur un serveur Gopher au format HTML. Note: Windows XP et Windows Server 2003 R2 et versions antérieures uniquement.
INTERNET_HANDLE_TYPE_HTTP_REQUEST Paramètres d’option associés à cette requête HTTP.
INTERNET_HANDLE_TYPE_INTERNET Les paramètres d’option associés à cette instance des fonctions WinINet.

Définition des options individuelles

Après avoir déterminé les options Internet que vous souhaitez définir et l’étendue que vous souhaitez affecter par ces options, la définition des options Internet n’est pas compliquée. Il vous suffit d’appeler la fonction InternetSetOption avec le handle HINTERNET souhaité, l’indicateur d’option Internet et une mémoire tampon contenant les informations que vous souhaitez définir.

L’exemple suivant montre comment définir le nom d’utilisateur et le mot de passe du proxy sur un handle HINTERNET spécifié.

// strUsername is a string buffer of cchMax characters or less.
// It contains the proxy user name.
size_t cchMax = 80;
size_t cchUserLength, cchPasswordLength;
HRESULT hr = StringCchLength(strUsername, cchMax, &cchUserLength);

if (SUCCEEDED(hr))
{
   // hOpen is the HINTERNET handle created by InternetConnect.
   InternetSetOption(hConnect, INTERNET_OPTION_PROXY_USERNAME,
      strUsername, DWORD(cchUserLength)+1);
}
else
{
   // Insert error handling code here.
}

// strPassword is the string buffer that contains the proxy password.
hr = StringCchLength(strPassword, cchMax, &cchPasswordLength);

InternetSetOption(hOpen, INTERNET_OPTION_PROXY_PASSWORD,
    strPassword, DWORD(cchPasswordLength)+1);

Récupération des options individuelles

Les options Internet peuvent être récupérées à l’aide de la fonction InternetQueryOption . Pour récupérer les options Internet :

  1. Déterminez la taille de mémoire tampon nécessaire pour récupérer les informations d’option Internet.

    La taille de la mémoire tampon peut être déterminée en utilisant NULL pour l’adresse de la mémoire tampon et en lui transmettant une taille de mémoire tampon de zéro.

    DWORD dwSize;
InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);

    La valeur retournée par InternetQueryOption correspond à la quantité de mémoire nécessaire pour récupérer les informations, en octets.

  2. Allouez une mémoire pour la mémoire tampon.

    char *lpszData;
lpszData = new char[dwSize];

  3. Récupérez les données.

    InternetQueryOption( NULL, 
                     INTERNET_OPTION_USER_AGENT,
                     lpszData, &dwSize );

  4. Libérez la mémoire.

    delete [] lpszData;

Exemple complet

Voici l’exemple complet utilisé dans la section précédente. Cet exemple montre comment récupérer la chaîne d’agent utilisateur par défaut.

// This call determines the required buffer size.
DWORD dwSize;
InternetQueryOption(NULL, INTERNET_OPTION_USER_AGENT, NULL, &dwSize);

// Allocate the necessary memory.
char *lpszData;
lpszData = new char[dwSize];

// Call InternetQueryOption again with the provided buffer.
InternetQueryOption( NULL, 
                     INTERNET_OPTION_USER_AGENT,
                     lpszData, &dwSize );

// Insert code here to use the user agent string data.

// Free the allocated memory.
delete [] lpszData;

Définition des options de connexion

Dans Internet Explorer 5 et versions ultérieures, les options Internet peuvent être définies pour sur une connexion spécifique. Auparavant, toutes les connexions partageaient les mêmes paramètres d’option Internet. Pour définir les options d’une connexion particulière :

  1. Créez une structure INTERNET_PER_CONN_OPTION_LIST .
  2. Allouez la mémoire aux options Internet individuelles que vous souhaitez définir pour la connexion.
  3. Définissez les options dans INTERNET_PER_CONN_OPTION structures.
  4. Définissez les options à l’aide d’InternetSetOption.

L’exemple de code suivant montre comment définir des données proxy pour une connexion LAN.

BOOL SetConnectionOptions()
{
    INTERNET_PER_CONN_OPTION_LIST list;
    BOOL    bReturn;
    DWORD   dwBufSize = sizeof(list);

    // Fill the list structure.
    list.dwSize = sizeof(list);

    // NULL == LAN, otherwise connectoid name.
    list.pszConnection = NULL;

    // Set three options.
    list.dwOptionCount = 3;
    list.pOptions = new INTERNET_PER_CONN_OPTION[3];

    // Ensure that the memory was allocated.
    if(NULL == list.pOptions)
    {
        // Return FALSE if the memory wasn't allocated.
        return FALSE;
    }

    // Set flags.
    list.pOptions[0].dwOption = INTERNET_PER_CONN_FLAGS;
    list.pOptions[0].Value.dwValue = PROXY_TYPE_DIRECT |
        PROXY_TYPE_PROXY;

    // Set proxy name.
    list.pOptions[1].dwOption = INTERNET_PER_CONN_PROXY_SERVER;
    list.pOptions[1].Value.pszValue = TEXT("https://proxy:80");

    // Set proxy override.
    list.pOptions[2].dwOption = INTERNET_PER_CONN_PROXY_BYPASS;
    list.pOptions[2].Value.pszValue = TEXT("local");

    // Set the options on the connection.
    bReturn = InternetSetOption(NULL,
        INTERNET_OPTION_PER_CONNECTION_OPTION, &list, dwBufSize);

    // Free the allocated memory.
    delete [] list.pOptions;

    return bReturn;
}

Récupération des options de connexion

Dans Internet Explorer 5 et versions ultérieures, les options Internet peuvent être récupérées à partir d’une connexion spécifique. Pour récupérer des options à partir d’une connexion particulière :

  1. Créez une structure INTERNET_PER_CONN_OPTION_LIST .
  2. Allouez la mémoire pour les options Internet individuelles à récupérer à partir de la connexion.
  3. Spécifiez les options à l’aide de structures INTERNET_PER_CONN_OPTION .
  4. Récupérez les options à l’aide d’InternetQueryOption.
  5. Utilisez les données d’option.
  6. Libérez la mémoire allouée pour contenir les données d’option, à l’aide de la fonction GlobalFree .

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).

Gestion de l’authentification

HINTERNET Handles