WinHTTP AutoProxy-functies

WinHTTP implementeert het WPAD-protocol met behulp van de functie WinHttpGetProxyForUrl samen met twee ondersteunende hulpprogrammafuncties, WinHttpDetectAutoProxyConfigUrl en WinHttpGetIEProxyConfigForCurrentUser.

AutoProxy-ondersteuning is niet volledig geïntegreerd in de HTTP-stack in WinHTTP. Voordat u een aanvraag verzendt, moet de toepassing WinHttpGetProxyForUrl- aanroepen om de naam van een proxyserver te verkrijgen en vervolgens WinHttpSetOption- aanroepen met behulp van WINHTTP_OPTION_PROXY om de proxyconfiguratie in te stellen op de WinHTTP-aanvraagafhandeling die is gemaakt door WinHttpOpenRequest.

De functie WinHttpGetProxyForUrl kan alle drie de stappen van het WPAD-protocol uitvoeren dat in het vorige overzicht wordt beschreven: (1) de PAC-URL detecteren, (2) het PAC-scriptbestand downloaden(3) de scriptcode uitvoeren en de proxyconfiguratie in een WINHTTP_PROXY_INFO-structuur retourneren. Als de toepassing van tevoren de PAC-URL kent, kan deze desgewenst worden opgegeven om winHttpGetProxyForUrl te.

In de volgende voorbeeldcode wordt gebruikgemaakt van autoproxy. Er wordt een HTTP GET-aanvraag ingesteld door eerst de WinHTTP-sessieverbinding en aanvraagingangen te maken. De WinHttpOpen aanroep geeft WINHTTP_ACCESS_TYPE_NO_PROXY op voor de eerste proxyconfiguratie, om aan te geven dat aanvragen standaard rechtstreeks naar de doelserver worden verzonden. Met behulp van autoproxy wordt de proxyconfiguratie vervolgens rechtstreeks op de aanvraaghandler ingesteld.

  HINTERNET hHttpSession = NULL;
  HINTERNET hConnect     = NULL;
  HINTERNET hRequest     = NULL;
  
  WINHTTP_AUTOPROXY_OPTIONS  AutoProxyOptions;
  WINHTTP_PROXY_INFO         ProxyInfo;
  DWORD                      cbProxyInfoSize = sizeof(ProxyInfo);
  
  ZeroMemory( &AutoProxyOptions, sizeof(AutoProxyOptions) );
  ZeroMemory( &ProxyInfo, sizeof(ProxyInfo) );
  
//
// Create the WinHTTP session.
//
  hHttpSession = WinHttpOpen( L"WinHTTP AutoProxy Sample/1.0",
                              WINHTTP_ACCESS_TYPE_NO_PROXY,
                              WINHTTP_NO_PROXY_NAME,
                              WINHTTP_NO_PROXY_BYPASS,
                              0 );
  
// Exit if WinHttpOpen failed.
  if( !hHttpSession )
    goto Exit;
  
//
// Create the WinHTTP connect handle.
//
  hConnect = WinHttpConnect( hHttpSession,
                             L"www.microsoft.com",
                             INTERNET_DEFAULT_HTTP_PORT,
                             0 );
  
// Exit if WinHttpConnect failed.
  if( !hConnect )
    goto Exit;
  
//
// Create the HTTP request handle.
//
  hRequest = WinHttpOpenRequest( hConnect,
                                 L"GET",
                                 L"ms.htm",
                                 L"HTTP/1.1",
                                 WINHTTP_NO_REFERER,
                                 WINHTTP_DEFAULT_ACCEPT_TYPES,
                                 0 );
  
// Exit if WinHttpOpenRequest failed.
  if( !hRequest )
    goto Exit;
  
//
// Set up the autoproxy call.
//

// Use auto-detection because the Proxy 
// Auto-Config URL is not known.
  AutoProxyOptions.dwFlags = WINHTTP_AUTOPROXY_AUTO_DETECT;

// Use DHCP and DNS-based auto-detection.
  AutoProxyOptions.dwAutoDetectFlags = 
                             WINHTTP_AUTO_DETECT_TYPE_DHCP |
                             WINHTTP_AUTO_DETECT_TYPE_DNS_A;

// If obtaining the PAC script requires NTLM/Negotiate
// authentication, then automatically supply the client
// domain credentials.
  AutoProxyOptions.fAutoLogonIfChallenged = TRUE;

//
// Call WinHttpGetProxyForUrl with our target URL. If 
// auto-proxy succeeds, then set the proxy info on the 
// request handle. If auto-proxy fails, ignore the error 
// and attempt to send the HTTP request directly to the 
// target server (using the default WINHTTP_ACCESS_TYPE_NO_PROXY 
// configuration, which the requesthandle will inherit 
// from the session).
//
  if( WinHttpGetProxyForUrl( hHttpSession,
                             L"https://www.microsoft.com/ms.htm",
                             &AutoProxyOptions,
                             &ProxyInfo))
  {
  // A proxy configuration was found, set it on the
  // request handle.
    
    if( !WinHttpSetOption( hRequest, 
                           WINHTTP_OPTION_PROXY,
                           &ProxyInfo,
                           cbProxyInfoSize ) )
    {
      // Exit if setting the proxy info failed.
      goto Exit;
    }
  }

//
// Send the request.
//
  if( !WinHttpSendRequest( hRequest,
                           WINHTTP_NO_ADDITIONAL_HEADERS,
                           0,
                           WINHTTP_NO_REQUEST_DATA,
                           0,
                           0,
                           NULL ) )
  {
    // Exit if WinHttpSendRequest failed.
    goto Exit;
  }

//
// Wait for the response.
//

  if( !WinHttpReceiveResponse( hRequest, NULL ) )
    goto Exit;

//
// A response has been received, then process it.
// (omitted)
//


  Exit:
  //
  // Clean up the WINHTTP_PROXY_INFO structure.
  //
    if( ProxyInfo.lpszProxy != NULL )
      GlobalFree(ProxyInfo.lpszProxy);

    if( ProxyInfo.lpszProxyBypass != NULL )
      GlobalFree( ProxyInfo.lpszProxyBypass );

  //
  // Close the WinHTTP handles.
  //
    if( hRequest != NULL )
      WinHttpCloseHandle( hRequest );
  
    if( hConnect != NULL )
      WinHttpCloseHandle( hConnect );
  
    if( hHttpSession != NULL )
      WinHttpCloseHandle( hHttpSession );

In de opgegeven voorbeeldcode geeft de aanroep naar WinHttpGetProxyForUrl de functie opdracht om het automatisch geconfigureerde proxybestand te detecteren door de vlag WINHTTP_AUTOPROXY_AUTO_DETECT op te geven in de WINHTTP_AUTOPROXY_OPTIONS structuur. Voor het gebruik van de vlag WINHTTP_AUTOPROXY_AUTO_DETECT moet de code een of beide markeringen voor automatische detectie (WINHTTP_AUTO_DETECT_TYPE_DHCP, WINHTTP_AUTO_DETECT_TYPE_DNS_A) opgeven. De voorbeeldcode maakt gebruik van de functie voor automatische detectie van WinHttpGetProxyForUrl omdat de PAC-URL van tevoren niet bekend is. Als een PAC-URL zich in dit scenario niet in het netwerk kan bevinden, mislukt WinHttpGetProxyForUrl- (GetLastError- retourneert ERROR_WINHTTP_AUTODETECTION_FAILED).

Als de PAC-URL vooraf bekend is

Als de toepassing de PAC-URL kent, kan deze worden opgegeven in de WINHTTP_AUTOPROXY_OPTIONS structuur en WinHttpGetProxyForUrl- configureren om de fase voor automatische detectie over te slaan.

Als een PAC-bestand bijvoorbeeld beschikbaar is op het lokale netwerk op de URL, 'https://InternalSite/proxy-config.pac", ziet de aanroep naar WinHttpGetProxyForUrl er als volgt uit.

//
// Set up the autoproxy call.
//

// The proxy auto-config URL is known. Auto-detection
// is not required.
  AutoProxyOptions.dwFlags = WINHTTP_AUTOPROXY_CONFIG_URL;

// Set the proxy auto-config URL.
  AutoProxyOptions. lpszAutoConfigUrl =  L"https://InternalSite/proxy-config.pac";

// If obtaining the PAC script requires NTLM/Negotiate
// authentication, then automatically supply the client
// domain credentials.
  AutoProxyOptions.fAutoLogonIfChallenged = TRUE;

//
// Call WinHttpGetProxyForUrl with our target URL. If auto-proxy
// succeeds, then set the proxy info on the request handle.
// If auto-proxy fails, ignore the error and attempt to send the
// HTTP request directly to the target server (using the default
// WINHTTP_ACCESS_TYPE_NO_PROXY configuration, which the request
// handle will inherit from the session).
//
  if( WinHttpGetProxyForUrl( hHttpSession,
                             L"https://www.microsoft.com/ms.htm",
                             &AutoProxyOptions,
                             &ProxyInfo ) )
{
  //...

Als in de WINHTTP_AUTOPROXY_OPTIONS structuur zowel WINHTTP_AUTOPROXY_AUTO_DETECT als WINHTTP_AUTOPROXY_CONFIG_URL vlaggen worden opgegeven (en worden automatisch detctionvlaggen en een AUTOMATISCHE configuratie-URL opgegeven), WinHttpGetProxyForUrl eerst automatische detectie probeert uit te proberen. Als automatische detectie geen PAC-URL kan vinden, valt 'terug' naar de automatisch geconfigureerde URL die door de toepassing wordt geleverd.

De functie WinHttpDetectAutoProxyConfigUrl

De functie WinHttpDetectAutoProxyConfigUrl implementeert een subset van het WPAD-protocol: hiermee wordt geprobeerd de URL voor het proxybestand voor automatische configuratie automatisch te detecteren, zonder het PAC-bestand te downloaden of uit te voeren. Deze functie is handig in speciale situaties waarin een webclienttoepassing het downloaden en uitvoeren van het PAC-bestand zelf moet afhandelen.

De functie WinHttpGetIEProxyConfigForCurrentUser

De functie WinHttpGetIEProxyConfigForCurrentUser retourneert de huidige gebruikersproxy-instellingen voor de huidige actieve netwerkverbinding, zonder aan te roepen naar 'WinInet.dll'. Deze functie is alleen nuttig wanneer deze wordt aangeroepen binnen een proces dat wordt uitgevoerd onder een interactieve gebruikersaccount-id, omdat er anders geen proxyconfiguratie van Internet Explorer beschikbaar is. Het is bijvoorbeeld niet handig om deze functie aan te roepen vanuit een ISAPI-DLL die wordt uitgevoerd in het IIS-serviceproces. Zie Discovery Without an Auto-Config Filevoor meer informatie en een scenario waarin een WinHTTP-gebaseerde toepassing WinHttpGetIEProxyConfigForCurrentUserzou gebruiken.