Condividi tramite

Conversione di applicazioni WinINet in WinHTTP

Microsoft Windows HTTP Services (WinHTTP) è destinato a applicazioni server di livello intermedio e back-end che richiedono l'accesso a uno stack client HTTP. microsoft Windows Internet (WinINet) fornisce uno stack client HTTP per le applicazioni client, nonché l'accesso ai protocolli FTP (File Transfer Protocol), SOCKSv4 e Gopher. Questa panoramica può aiutare a determinare se la conversione delle applicazioni WinINet in WinHTTP sarebbe utile. Descrive anche requisiti di conversione specifici.

Aspetti da considerare prima di convertire l'applicazione WinINet

Valutare la possibilità di convertire l'applicazione WinINet in WinHTTP se l'applicazione trarrà vantaggio da:

  • Una pila client HTTP sicura per server.
  • Riduzione al minimo dell'utilizzo dello stack.
  • Scalabilità di un'applicazione server.
  • Meno dipendenze dalle API correlate alla piattaforma.
  • Supporto per l'impersonificazione dei thread.
  • Uno stack HTTP ottimizzato per i servizi.
  • Accesso all'oggetto WinHttpRequest scriptable.

Non prendere in considerazione la conversione dell'applicazione WinINet in WinHTTP se deve supportare uno o più dei seguenti elementi:

  • Il protocollo FTP o Gopher dallo stack HTTP.
  • Supporto per il protocollo SOCKSv4 per la comunicazione con i proxy SOCKS.
  • Servizi automatici di connessione remota.

Se si decide di convertire l'applicazione in WinHTTP, le sezioni seguenti illustrano il processo di conversione.

Per un'applicazione di esempio per WinINet e WinHTTP, confrontare l'esempio AsyncDemo per WinINet con l'esempio AsyncDemo per WinHTTP.

Equivalenti WinHTTP delle funzioni WinINet

La tabella seguente elenca le funzioni WinINet correlate allo stack client HTTP insieme agli equivalenti WinHTTP.

Se l'applicazione richiede funzioni WinINet non elencate, non convertire l'applicazione in WinHTTP.

Funzione WinINet Equivalente a WinHTTP Modifiche rilevanti
HttpAddRequestHeaders WinHttpAddRequestHeaders Nessuno.
HttpEndRequest WinHttpReceiveResponse Il valore di contesto viene impostato con WinHttpSendRequest o WinHttpSetOption. Le opzioni di richiesta vengono impostate con WinHttpOpenRequest. WinHttpReceiveResponse deve essere chiamato dopo l'invio di una richiesta.
HttpOpenRequest WinHttpOpenRequest Il valore di contesto viene impostato con WinHttpSendRequest o WinHttpSetOption.
HttpQueryInfo WinHttpQueryHeaders Nessuno.
HttpSendRequest WinHttpSendRequest Il valore di contesto può essere impostato con WinHttpSendRequest.
HttpSendRequestEx WinHttpSendRequest Non è possibile fornire buffer.
InternetCanonicalizeUrl Nessun equivalente Gli URL vengono ora inseriti in forma canonica in WinHttpOpenRequest.
InternetCheckConnection Nessun equivalente Non implementato in WinHTTP.
InternetCloseHandle WinHttpCloseHandle La chiusura di un handle padre in WinHTTP non chiude in modo ricorsivo gli handle figlio.
InternetCombineUrl Nessun equivalente Gli URL possono essere assemblati con la funzioneWinHttpCreateUrl.
ConfermaAttraversamentoZonaInternet Nessun equivalente Non implementato in WinHTTP.
InternetConnect WinHttpConnect Il valore di contesto viene impostato con WinHttpSendRequest o WinHttpSetOption. Le opzioni di richiesta vengono impostate con WinHttpOpenRequest. Le credenziali utente vengono impostate con WinHttpSetCredentials.
InternetCrackUrl WinHttpCrackUrl Comportamento opposto del flag di ICU_ESCAPE: con InternetCrackUrl, questo flag fa sì che le sequenze di escape (%xx) vengano convertite in caratteri, ma con WinHttpCrackUrl, fa sì che i caratteri che devono essere protetti in una richiesta HTTP vengano convertiti in sequenze di escape.
InternetCreateUrl WinHttpCreateUrl Nessuno.
InternetErrorDlg Nessun equivalente Poiché WinHTTP è destinato alle applicazioni lato server, non implementa alcuna interfaccia utente.
InternetGetCookie Nessun equivalente WinHTTP non rende persistenti i dati tra sessioni e non può accedere ai cookie WinINet.
InternetOpen WinHttpOpen Nessuno.
InternetOpenUrl WinHttpConnect, WinHttpOpenRequest, WinHttpSendRequest, WinHttpReceiveResponse Questa funzionalità è disponibile nelle funzioni WinHTTP elencate.
InternetQueryDataAvailable WinHttpQueryDataAvailable Nessun parametro riservato.
InternetQueryOption WinHttpQueryOption WinHTTP offre un set di opzioni diverso da WinINet. Per altre informazioni e opzioni offerte da WinHTTP, vedere flag di opzione .
InternetReadFile WinHttpReadData Nessuno.
InternetReadFileEx WinHttpReadData Anziché una struttura, il buffer è un'area di memoria indirizzata con un puntatore.
InternetSetOption WinHttpSetOption Nessuno.
InternetSetStatusCallback WinHttpSetStatusCallback Per altre informazioni, vedere "Gestione diversa delle richieste asincrone" in questo argomento.
InternetTimeFromSystemTime WinHttpTimeFromSystemTime Nessuno.
InternetTimeToSystemTime winHttpTimeToSystemTime Nessuno.
InternetWriteFile WinHttpWriteData Nessuno.

 

Gestione diversa delle richieste asincrone

Tenere presente che in WinINet e WinHTTP alcune funzioni possono completare le richieste asincrone in modo sincrono o asincrono. L'applicazione deve gestire entrambe le situazioni. Esistono differenze significative nel modo in cui WinINet e WinHTTP gestiscono queste funzioni potenzialmente asincrone.

WinINet

  • Completamento sincrono: se una chiamata di funzione WinINet potenzialmente asincrona viene completata in modo sincrono, i parametri OUT della funzione restituiscono i risultati dell'operazione. Quando si verifica un errore, recuperare il codice di errore chiamando GetLastError dopo la chiamata di funzione WinINet.

  • Completamento asincrono: se una chiamata di funzione potenzialmente asincrona viene completata in modo asincrono, i risultati dell'operazione e gli eventuali errori sono accessibili nella funzione di callback. La funzione di callback viene eseguita su un thread di lavoro, non sul thread che ha eseguito la chiamata di funzione iniziale.

In altre parole, l'applicazione deve duplicare la logica per gestire i risultati di tali operazioni in due posizioni: entrambe immediatamente dopo la chiamata di funzione e nella funzione di callback.

WinHTTP semplifica questo modello consentendo di implementare la logica operativa solo nella funzione di callback, che riceve una notifica di completamento indipendentemente dal fatto che l'operazione sia stata completata in modo sincrono o asincrono. Quando l'operazione asincrona è abilitata, i parametri OUT delle funzioni WinHTTP non restituiscono dati significativi e devono essere impostati su NULL.

L'unica differenza significativa tra il completamento asincrono e sincrono in WinHTTP, dal punto di vista dell'applicazione, si trova nella posizione in cui viene eseguita la funzione di callback.

WinHTTP

  • Completamento sincrono: quando un'operazione viene completata in modo sincrono, i risultati vengono restituiti in una funzione di callback eseguita nello stesso thread della chiamata di funzione originale.

  • Completamento asincrono: quando un'operazione viene completata in modo asincrono, i risultati vengono restituiti in una funzione di callback eseguita in un thread di lavoro.

Anche se la maggior parte degli errori può essere gestita interamente all'interno della funzione di callback, le applicazioni WinHTTP devono comunque essere preparate affinché una funzione restituisca false a causa di un ERROR_INVALID_PARAMETER o di un altro errore simile recuperato chiamando GetLastError.

A differenza di WinINet, che può eseguire più operazioni asincrone contemporaneamente, WinHTTP applica un criterio di un'operazione asincrona in sospeso per ogni handle di richiesta. Se un'operazione è in sospeso e viene chiamata un'altra funzione WinHTTP, la seconda funzione ha esito negativo e GetLastError restituisce ERROR_INVALID_OPERATION.

WinHTTP semplifica questo modello consentendo di implementare la logica operativa solo nella funzione di callback, che riceve una notifica di completamento indipendentemente dal fatto che l'operazione sia stata completata in modo sincrono o asincrono. Quando l'operazione asincrona è abilitata, i parametri OUT delle funzioni WinHTTP non restituiscono dati significativi e devono essere impostati su NULL.

Differenze nelle notifiche di callback WinHTTP

La funzione di callback di stato riceve gli aggiornamenti sullo stato delle operazioni tramite flag di notifica. In WinHTTP le notifiche vengono selezionate usando il parametro dwNotificationFlags della funzioneWinHttpSetStatusCallback. Usare il flag WINHTTP_CALLBACK_FLAG_ALL_NOTIFICATIONS per ricevere una notifica di tutti gli aggiornamenti dello stato.

Le notifiche che indicano che una particolare operazione è stata completata sono chiamate notifiche di completamento o solo completamenti. In WinINet ogni volta che la funzione di callback riceve un completamento, il parametro lpvStatusInformation contiene una struttura INTERNET_ASYNC_RESULT. In WinHTTP questa struttura non è disponibile per tutti i completamenti. È importante esaminare la pagina di riferimento per WINHTTP_STATUS_CALLBACK, che contiene informazioni sulle notifiche e sul tipo di dati che è possibile prevedere per ognuno.

In WinHTTP, un singolo completamento, WINHTTP_CALLBACK_STATUS_REQUEST_ERROR, indica che un'operazione non è riuscita. Tutti gli altri completamenti indicano un'operazione riuscita.

Sia WinINet che WinHTTP usano un valore di contesto definito dall'utente per passare informazioni dal thread principale alla funzione di callback di stato, che può essere eseguita in un thread di lavoro. In WinINet il valore di contesto usato dalla funzione di callback di stato viene impostato chiamando una delle diverse funzioni. In WinHTTP il valore di contesto viene impostato solo con WinHttpSendRequest o WinHttpSetOption. Per questo motivo, è possibile che in WinHTTP venga eseguita una notifica prima che venga impostato un valore di contesto. Se la funzione di callback riceve una notifica prima che il valore del contesto sia impostato, l'applicazione deve essere preparata a ricevere NULL nel parametro dwContext della funzione di callback.

Differenze di autenticazione

In WinINet le credenziali utente vengono impostate chiamando la funzione InternetSetOption, usando codice simile a quello fornito nell'esempio di codice seguente.

// Use the WinINet InternetSetOption function to set the 
// user credentials to the user name contained in strUsername 
// and the password to the contents of strPassword.
       
InternetSetOption( hRequest, INTERNET_OPTION_PROXY_USERNAME, 
                   strUsername, strlen(strUsername) + 1 );

InternetSetOption( hRequest, INTERNET_OPTION_PROXY_PASSWORD, 
                   strPassword, strlen(strPassword) + 1 );

Per motivi di compatibilità, le credenziali utente possono essere impostate in Modo analogo in WinHTTP usando la funzionewinHttpSetOption, ma questa operazione non è consigliata perché può rappresentare una vulnerabilità di sicurezza.

Quando invece un'applicazione riceve un codice di stato 401 in WinHTTP, il metodo consigliato di impostazione delle credenziali consiste innanzitutto nell'identificare uno schema di autenticazione usando WinHttpQueryAuthSchemes e, in secondo luogo, impostare le credenziali usando WinHttpSetCredentials. Nell'esempio di codice seguente viene illustrato come eseguire questa operazione.

DWORD dwSupportedSchemes;
DWORD dwPrefered;
DWORD dwTarget;

// Obtain the supported and first schemes.
WinHttpQueryAuthSchemes( hRequest, &dwSupportedSchemes, &dwPrefered, &dwTarget );

// Set the credentials before resending the request.
WinHttpSetCredentials( hRequest, dwTarget, dwPrefered, strUsername, strPassword, NULL );

Poiché non esiste alcun equivalente a InternetErrorDlg in WinHTTP, le applicazioni che ottengono le credenziali tramite un'interfaccia utente devono fornire la propria interfaccia.

A differenza di WinINet, WinHTTP non memorizza nella cache le password. Le credenziali utente valide devono essere specificate per ogni richiesta.

WinHTTP non supporta lo schema DPA (Distributed Password Authentication) supportato da WinINet. WinHTTP supporta tuttavia Microsoft Passport 1.4. Per ulteriori informazioni sull'uso dell'autenticazione Passport in WinHTTP, consultare Autenticazione Passport in WinHTTP.

WinHTTP non si basa sulle impostazioni di Internet Explorer per determinare i criteri di accesso automatici. Al contrario, il criterio di accesso automatico viene impostato con WinHttpSetOption. Per altre informazioni sull'autenticazione in WinHTTP, inclusi i criteri di accesso automatico, vedere autenticazione in WinHTTP.

Differenze nelle transazioni HTTP sicure

In WinINet avviare una sessione protetta usando HttpOpenRequest o InternetConnect, ma in WinHTTP è necessario chiamare WinHttpOpenRequest usando il flag WINHTTP_FLAG_SECURE.

In una transazione HTTP sicura è possibile usare i certificati server per autenticare un server nel client. In WinINet, se un certificato server contiene errori, HttpSendRequest ha esito negativo e fornisce informazioni dettagliate sugli errori del certificato.

In WinHttp gli errori del certificato del server vengono gestiti in base alla versione come indicato di seguito:

  • A partire da WinHttp 5.1, se un certificato server ha esito negativo o contiene errori, la chiamata a WinHttpSendRequest segnala un WINHTTP_CALLBACK_STATUS_SECURE_FAILURE nella funzione di callback. Se l'errore generato da WinHttpSendRequest viene ignorato, le chiamate successive a WinHttpReceiveResponse hanno esito negativo con un errore di ERROR_WINHTTP_OPERATION_CANCELLED.
  • In WinHTTP 5.0, gli errori nei certificati server non, per impostazione predefinita, causano un errore di una richiesta. Gli errori vengono invece segnalati nella funzione di callback con la notifica di WINHTTP_CALLBACK_STATUS_SECURE_FAILURE.

In alcune piattaforme precedenti WinINet supportava i protocolli PCT (Private Communication Technology) e/o Fortezza, anche se non in Windows XP.

WinHTTP non supporta i protocolli PCT e Fortezza su alcuna piattaforma e si basa invece su SECURE Sockets Layer (SSL) 2.0, SSL 3.0 o Transport Layer Security (TLS) 1.0.