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 daraus abgerufen werden.

Implementierungsschritte

Führen Sie die folgenden Schritte aus, um Internetoptionen festzulegen oder abzurufen:

Auswählen von Internetoptionen

Da es so viele Internetoptionen gibt, ist es wichtig, die richtigen Optionen auszuwählen. Viele Internetoptionen beeinflussen das Verhalten der WinINet-Funktionen und Internet Explorer:

Beispielsweise können Sie folgende Aktionen ausführen:

  • Behandeln Sie die grundlegende Server- und Proxyauthentifizierung, indem Sie Benutzernamen und Kennwörter festlegen.
  • Legen Sie die Benutzer-Agent-Zeichenfolge fest, die von Servern zum Identifizieren der Features der Clientanwendung oder des Browsers verwendet wird, oder rufen Sie sie ab.
  • Ruft 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 Strukturen INTERNET _ PER CONN OPTION _ _ _ LIST und INTERNET PER CONN OPTION festgelegt oder aus einer _ _ bestimmten _ Internetverbindung abgerufen werden. Weitere Informationen und eine Liste der Optionen, die von einer bestimmten Internetverbindung festgelegt oder abgerufen werden können, finden Sie unter dem dwOptions-Element der INTERNET PER _ _ CONN _ OPTION-Struktur.

Auswählen des HINTERNET-Handles

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

Beispielsweise erfordern Clientanwendungen, die einen Proxy mit Authentifizierung erfordern, wahrscheinlich nicht jedes Mal, wenn die Anwendung versucht, auf eine Internetressource zuzugreifen, den Proxybenutzernamen und das Kennwort festzulegen. Wenn alle Anforderungen für eine bestimmte Verbindung vom gleichen Proxy verarbeitet werden, ermöglicht das Festlegen des Proxybenutzernamens und des Kennworts für ein HINTERNET-Handle des Verbindungstyps, d. h. ein handle, das durch einen Aufruf von InternetConnecterstellt wurde, allen aufrufen, die von diesem HINTERNET-Handle abgeleitet werden, den gleichen Proxybenutzernamen und dasselbe Kennwort zu verwenden. Das Festlegen des Proxybenutzernamens und -kennworts jedes Mal, wenn ein HINTERNET-Handle von HttpOpenRequest erstellt wird, würde zusätzlichen und unnötigen Mehraufwand erfordern. Beachten Sie Folgendes: 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-Handle verwendet werden sollen, rufen Sie diese Internetoptionen ab. Um Optionen festzulegen oder abzurufen, rufen Sie entweder InternetQueryOption oder InternetSetOption auf.

Bereich des HINTERNET-Handles

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

Diese Handles haben 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. Das Festlegen von Internetoptionen bei Verwendung von NULL als Handle ändert die Standardwerte der Optionen, 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 Bereich der ihnen zugeordneten Internetoptionen aufgeführt.

Handletyp 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 von diesem 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 von diesem HINTERNET-Handle initiiert werden, z. B. Dateidownloads.
[!Note]
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 von diesem HINTERNET-Handle initiiert werden, z. B. Dateidownloads.
INTERNET_HANDLE_TYPE_FILE_REQUEST Die dieser Dateianforderung zugeordneten Optionseinstellungen.
INTERNET_HANDLE_TYPE_FTP_FILE Die Optionseinstellungen, die diesem FTP-Ressourcendownload zugeordnet sind.
INTERNET_HANDLE_TYPE_FTP_FILE_HTML Die Optionseinstellungen, die diesem FTP-Ressourcendownload zugeordnet sind, formatiert in HTML.
INTERNET_HANDLE_TYPE_FTP_FIND Die Optionseinstellungen, die dieser Suche nach Dateien auf einem FTP-Server zugeordnet sind.
INTERNET_HANDLE_TYPE_FTP_FIND_HTML Die Optionseinstellungen, die dieser Suche nach Dateien auf einem IN HTML formatierten FTP-Server zugeordnet sind.
INTERNET_HANDLE_TYPE_GOPHER_FILE Die Optionseinstellungen, die diesem Gopher-Ressourcendownload zugeordnet sind.
[!Note]
Windows XP und Windows Server 2003 R2 und früher.

INTERNET_HANDLE_TYPE_GOPHER_FILE_HTML Die Optionseinstellungen, die diesem Gopher-Ressourcendownload zugeordnet sind, sind im HTML-Format formatiert.
[!Note]
Windows XP und Windows Server 2003 R2 und früher.

INTERNET_HANDLE_TYPE_GOPHER_FIND Die Optionseinstellungen, die dieser Suche nach Dateien auf einem Gopher-Server zugeordnet sind.
[!Note]
Windows XP und Windows Server 2003 R2 und früher.

INTERNET_HANDLE_TYPE_GOPHER_FIND_HTML Die Optionseinstellungen, die dieser Suche nach Dateien auf einem in HTML formatierten Gopher-Server zugeordnet sind.
[!Note]
Windows XP und Windows Server 2003 R2 und früher.

INTERNET_HANDLE_TYPE_HTTP_REQUEST Die dieser HTTP-Anforderung zugeordneten Optionseinstellungen.
INTERNET_HANDLE_TYPE_INTERNET Die Dieser Instanz der WinINet-Funktionen zugeordneten Optionseinstellungen.

Festlegen einzelner Optionen

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

Das folgende Beispiel zeigt, wie Sie den Proxybenutzernamen und das Kennwort für ein angegebenes HINTERNET-Handle festlegen.

// 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. Zuordnen eines Arbeitsspeichers für den Puffer.

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

    InternetQueryOption( NULL, 
                         INTERNET_OPTION_USER_AGENT,
                         lpszData, &dwSize );
    
  4. Freigeben des Arbeitsspeichers.

    delete [] lpszData;
    

Vollständiges Beispiel

Im Folgenden finden Sie das vollständige Beispiel, das im vorherigen Abschnitt verwendet wurde. In diesem Beispiel wird gezeigt, wie die Standard-Benutzer-Agent-Zeichenfolge 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 für eine bestimmte Verbindung festgelegt werden. Zuvor haben alle Verbindungen die gleichen Internetoptionseinstellungen verwendet. 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 mit InternetSetOption fest.

Das folgende Codebeispiel zeigt, 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 von einer bestimmten 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 mit InternetQueryOption ab.
  5. Verwenden Sie die Optionsdaten.
  6. Freigeben des Arbeitsspeichers, der zum Speichern der Optionsdaten zugeordnet ist, mithilfe der GlobalFree-Funktion.

Hinweis

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

Behandeln der Authentifizierung

HINTERNET-Handles