Festlegen und Abrufen von Internetoptionen

In diesem Thema wird beschrieben, wie Internetoptionen mithilfe der Funktionen InternetSetOption und InternetQueryOption festgelegt und abgerufen werden.

Internetoptionen können für ein angegebenes HINTERNET-Handle oder die aktuellen Einstellungen in Microsoft Internet Explorer festgelegt oder abgerufen werden.

Implementierungsschritte

Führen Sie Folgendes aus, um Internetoptionen festzulegen oder abzurufen:

Auswählen von Internetoptionen

Da es so viele Internetoptionen gibt, ist die Auswahl der richtigen Optionen wichtig. Viele Internetoptionen wirken sich auf das Verhalten der WinINet-Funktionen und des Internet-Explorer aus:

Beispielsweise können Sie folgende Aktionen ausführen:

  • Behandeln Sie die einfache Server- und Proxyauthentifizierung, indem Sie Benutzernamen und Kennwörter festlegen.
  • Legen Sie die Benutzer-Agent-Zeichenfolge fest, die von Servern verwendet wird, um die Features der Clientanwendung oder des Browsers zu identifizieren.
  • Rufen Sie den Handletyp des angegebenen HINTERNET-Handles ab.

Weitere Informationen und eine Liste der Internetoptionen finden Sie unter Optionsflags.

In Internet Explorer 5 und höher können einige Optionen mithilfe der INTERNET_PER_CONN_OPTION_LIST- und INTERNET_PER_CONN_OPTION-Strukturen festgelegt oder von einer bestimmten Internetverbindung abgerufen werden. Weitere Informationen und eine Liste der Optionen, die festgelegt oder von einer bestimmten Internetverbindung abgerufen werden können, finden Sie im dwOptions-Element der INTERNET_PER_CONN_OPTION-Struktur .

Auswählen des HINTERNET-Handle

Das HINTERNET-Handle , das zum Festlegen oder Abrufen von Internetoptionen verwendet wird, bestimmt den Umfang des Vorgangs. Alle über dieses Handle erstellten Handles erben die für dieses Handle festgelegten Optionen.

Clientanwendungen, die beispielsweise einen Proxy mit Authentifizierung erfordern, müssen den Proxybenutzernamen und das Kennwort wahrscheinlich nicht jedes Mal festlegen, wenn die Anwendung versucht, auf eine Internetressource zuzugreifen. Wenn alle Anforderungen für eine bestimmte Verbindung von demselben Proxy verarbeitet werden, kann das Festlegen des Proxybenutzernamens und -kennworts für ein HINTERNET-Handle vom Verbindungstyp, d. h. ein Handle, der durch einen Aufruf von InternetConnect erstellt wurde, zulassen, dass alle von diesem HINTERNET-Handle abgeleiteten Aufrufe denselben Proxybenutzernamen und dasselbe Kennwort verwenden. Das Festlegen des Proxybenutzernamens und des Kennworts jedes Mal, wenn ein HINTERNET-Handle von HttpOpenRequest erstellt wird, erfordert zusätzlichen und unnötigen Aufwand. Beachten Sie: Wenn die Anwendung einen Proxy verwendet, der eine Authentifizierung erfordert, sollte sie die Proxyanmeldeinformationen für jede neue Verbindung festlegen.

Festlegen oder Abrufen der Optionen

Wenn Sie ermittelt haben, welche Internetoptionen und HINTERNET-Vorgänge verwendet werden sollen, rufen Sie diese Internetoptionen ab. Um Optionen festzulegen oder abzurufen, rufen Sie entweder InternetQueryOption oder InternetSetOption auf.

Bereich des HINTERNET-Handle

Das HINTERNET-Handle zum Festlegen oder Abrufen von Internetoptionen bestimmt die Aktionen, für die die Optionen gültig sind.

Diese Handles verfügen über drei Ebenen:

Zusätzlich zu den verschiedenen HINTERNET-Handles kann eine Anwendung auch NULL verwenden, um die Standardwerte der Internetoptionen festzulegen oder abzurufen, die von internet Explorer und den WinINet-Funktionen verwendet werden. Durch festlegen von Internetoptionen bei Verwendung von NULL als Handle werden die Standardwerte der Optionen geändert, die derzeit in der Registrierung gespeichert sind. Clientanwendungen sollten keine Registrierungsfunktionen verwenden, um die Standardwerte der Internetoptionen zu ändern, da die Implementierung der Speicherung der Optionen in Zukunft geändert werden kann.

In der folgenden Tabelle sind der Typ der HINTERNET-Handles und der Umfang der ihnen zugeordneten Internetoptionen aufgeführt.

Handle-Typ `Scope`
NULL Die Standardoptionseinstellungen für internet Explorer.
INTERNET_HANDLE_TYPE_CONNECT_FTP Die Optionseinstellungen für diese Verbindung mit einem FTP-Server. Diese Optionen wirken sich auf alle Vorgänge aus, die über dieses HINTERNET-Handle initiiert werden, z. B. Dateidownloads.
INTERNET_HANDLE_TYPE_CONNECT_GOPHER Die Optionseinstellungen für diese Verbindung mit einem Gopher-Server. Diese Optionen wirken sich auf alle Vorgänge aus, die über dieses HINTERNET-Handle initiiert werden, z. B. Dateidownloads. Hinweis: Nur Windows XP und Windows Server 2003 R2 und früher.
INTERNET_HANDLE_TYPE_CONNECT_HTTP Die Optionseinstellungen für diese Verbindung mit einem HTTP-Server. Diese Optionen wirken sich auf alle Vorgänge aus, die über dieses HINTERNET-Handle initiiert werden, z. B. Dateidownloads.
INTERNET_HANDLE_TYPE_FILE_REQUEST Die Optionseinstellungen, die dieser Dateianforderung zugeordnet sind.
INTERNET_HANDLE_TYPE_FTP_FILE Die Optionseinstellungen, die diesem FTP-Ressourcendownload zugeordnet sind.
INTERNET_HANDLE_TYPE_FTP_FILE_HTML Die Optionseinstellungen, die diesem IN HTML formatierten FTP-Ressourcendownload zugeordnet sind.
INTERNET_HANDLE_TYPE_FTP_FIND Die Optionseinstellungen, die dieser Suche von Dateien auf einem FTP-Server zugeordnet sind.
INTERNET_HANDLE_TYPE_FTP_FIND_HTML Die Optionseinstellungen, die dieser Suche von Dateien auf einem IN HTML formatierten FTP-Server zugeordnet sind.
INTERNET_HANDLE_TYPE_GOPHER_FILE Die Optionseinstellungen, die diesem Gopher-Ressourcendownload zugeordnet sind. Hinweis: Nur Windows XP und Windows Server 2003 R2 und früher.
INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML Die Optionseinstellungen, die diesem In HTML-Format formatierten Gopher-Ressourcendownload zugeordnet sind. Hinweis: Nur Windows XP und Windows Server 2003 R2 und früher.
INTERNET_HANDLE_TYPE_GOPHER_FIND Die Optionseinstellungen, die dieser Suche von Dateien auf einem Gopher-Server zugeordnet sind. Hinweis: Nur Windows XP und Windows Server 2003 R2 und früher.
INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML Die Optionseinstellungen, die dieser Suche von Dateien auf einem Gopher-Server zugeordnet sind, der in HTML formatiert ist. Hinweis: Nur Windows XP und Windows Server 2003 R2 und früher.
INTERNET_HANDLE_TYPE_HTTP_REQUEST Die Optionseinstellungen, die dieser HTTP-Anforderung zugeordnet sind.
INTERNET_HANDLE_TYPE_INTERNET Die Optionseinstellungen, die diesem instance der WinINet-Funktionen zugeordnet sind.

Festlegen einzelner Optionen

Nachdem Sie die Internetoptionen ermittelt haben, die Sie festlegen möchten, und den Von diesen Optionen betroffenen Bereich, ist das Festlegen von Internetoptionen nicht kompliziert. Sie müssen lediglich die InternetSetOption-Funktion mit gewünschtem HINTERNET-Handle , Internetoptionsflag und einem Puffer aufrufen, der die gewünschten Informationen enthält.

Das folgende Beispiel zeigt, wie Der Proxybenutzername und das Kennwort für ein angegebenes HINTERNET-Handle festgelegt werden.

// 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);

Abrufen einzelner Optionen

Internetoptionen können mithilfe der InternetQueryOption-Funktion abgerufen werden. So rufen Sie Internetoptionen ab:

  1. Bestimmen Sie die Puffergröße, die zum Abrufen der Internetoptionsinformationen erforderlich ist.

    Die Puffergröße kann bestimmt werden, indem NULL für die Adresse des Puffers verwendet und eine Puffergröße von 0 (null) übergeben wird.

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

    Der von InternetQueryOption zurückgegebene Wert ist die Menge an Arbeitsspeicher, die zum Abrufen der Informationen in Bytes erforderlich ist.

  2. Weisen Sie einen Arbeitsspeicher für den Puffer zu.

    char *lpszData;
    lpszData = new char[dwSize];
    
  3. Rufen Sie die Daten ab.

    InternetQueryOption( NULL, 
                         INTERNET_OPTION_USER_AGENT,
                         lpszData, &dwSize );
    
  4. Geben Sie den Arbeitsspeicher frei.

    delete [] lpszData;
    

Vollständiges Beispiel

Es folgt das vollständige Beispiel, das im vorherigen Abschnitt verwendet wurde. In diesem Beispiel wird gezeigt, wie die Standardzeichenfolge des Benutzer-Agents abgerufen wird.

// 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;

Festlegen von Verbindungsoptionen

In Internet Explorer 5 und höher können Internetoptionen für eine bestimmte Verbindung festgelegt werden. Bisher hatten alle Verbindungen die gleichen Internetoptionseinstellungen. So legen Sie Optionen für eine bestimmte Verbindung fest:

  1. Erstellen Sie eine INTERNET_PER_CONN_OPTION_LIST-Struktur .
  2. Ordnen Sie den Arbeitsspeicher für die einzelnen Internetoptionen zu, die Sie für die Verbindung festlegen möchten.
  3. Legen Sie die Optionen in INTERNET_PER_CONN_OPTION-Strukturen fest.
  4. Legen Sie die Optionen mithilfe von InternetSetOption fest.

Im folgenden Codebeispiel wird gezeigt, wie Proxydaten für eine LAN-Verbindung festgelegt werden.

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;
}

Abrufen von Verbindungsoptionen

In Internet Explorer 5 und höher können Internetoptionen über eine bestimmte Verbindung abgerufen werden. So rufen Sie Optionen aus einer bestimmten Verbindung ab:

  1. Erstellen Sie eine INTERNET_PER_CONN_OPTION_LIST-Struktur .
  2. Ordnen Sie den Arbeitsspeicher für die einzelnen Internetoptionen zu, die von der Verbindung abgerufen werden sollen.
  3. Geben Sie die Optionen mithilfe von INTERNET_PER_CONN_OPTION-Strukturen an.
  4. Rufen Sie die Optionen mithilfe von InternetQueryOption ab.
  5. Verwenden Sie die Optionsdaten.
  6. Geben Sie den Speicher frei, der für die Optionsdaten zugeordnet ist, mithilfe der GlobalFree-Funktion .

Hinweis

WinINet unterstützt keine Serverimplementierungen. Darüber hinaus sollte es nicht von einem Dienst verwendet werden. Verwenden Sie für Serverimplementierungen oder Dienste Microsoft Windows HTTP Services (WinHTTP).

Behandeln der Authentifizierung

HINTERNET-Handles