Abilitazione della funzionalità Internet

Prima di usare le funzioni WinINet, l'applicazione deve tentare di eseguire una connessione a Internet usando la funzione InternetAttemptConnect . Questa funzione chiama la finestra di dialogo di accesso esterno per avviare una connessione a Internet o verificare se esiste già una connessione. Se questa funzione ha esito negativo, l'applicazione può immettere la modalità offline, che consente di accedere alle informazioni memorizzate nella cache durante le connessioni precedenti a Internet.

Usare la funzione InternetCheckConnection per controllare la connessione a Internet. Tenta di eseguire il ping del server designato dall'URL passato alla funzione. Se il flag FLAG_ICC_FORCE_CONNECTION è impostato e l'URL è NULL, la funzione verifica se è presente una voce nel database del server per il server più vicino. Se esiste, la funzione esegue il ping del server.

Usare quindi la funzione InternetOpen per stabilire le caratteristiche della connessione Internet in uso all'applicazione client. InternetOpen crea l'handle XAMLNET radice usato per stabilire sessioni ftphttp. InternetOpen non testa la connessione a Internet per verificare che le caratteristiche passate alla funzione siano corrette.

Usare la funzione InternetConnect per creare una sessione specifica. InternetConnect inizializza una sessione per il sito specificato usando gli argomenti passati e crea un handle XAMLNET che è un ramo dell'handle radice. InternetConnect non tenta di accedere o stabilire una connessione al sito specificato, tranne nel caso di una sessione FTP. Le funzioni FtpFindFirstFile, FtpOpenFile e HttpOpenRequest usano l'handle creato da InternetConnect per stabilire una connessione al sito specificato.

Uso di InternetOpen

Per abilitare una connessione a Internet, è necessario creare un handle XAMLNET radice usando InternetOpen. Informazioni sull'agente utente (l'applicazione che chiama le funzioni Internet), il tipo di accesso a Internet, i nomi proxy, gli host e gli indirizzi che ignorano il proxy e il comportamento vengono passati a InternetOpen.

Impostazione dell'agente utente

L'applicazione chiamante deve assegnare una stringa contenente il nome dell'applicazione o dell'entità che accede a Internet al parametro lpszAgent di InternetOpen. Questa stringa viene usata come agente utente nel protocollo HTTP. Ad esempio, Microsoft Internet Explorer usa "Microsoft Internet Explorer".

Impostazione dei tipi di accesso

InternetOpen supporta tre tipi di accesso:

• Usare INTERNET_OPEN_TYPE_DIRECT se il sistema in cui è in esecuzione l'applicazione usa una connessione diretta a Internet. I parametri lpszProxyName e lpszProxyBypass di InternetOpen non vengono usati e devono essere impostati su NULL.
• Usare INTERNET_OPEN_TYPE_PROXY se il sistema in cui è in esecuzione l'applicazione usa uno o più server proxy per accedere a Internet. InternetOpen usa i server proxy indicati da lpszProxyName e ignora il proxy per qualsiasi nome host o indirizzi IP specificati da lpszProxyBypass.
• Usare INTERNET_OPEN_TYPE_PRECONFIG per indicare all'applicazione di recuperare la configurazione dal Registro di sistema. Questa è in genere la scelta migliore, come la maggior parte delle applicazioni che includono i Web browser usa questa opzione.

INTERNET_OPEN_TYPE_PRECONFIG esamina i valori del Registro di sistema ProxyEnable, ProxyServer e ProxyOverride. Questi valori si trovano in "HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Internet Settings".

Se ProxyEnable è zero, l'applicazione usa INTERNET_OPEN_TYPE_DIRECT. In caso contrario, l'applicazione usa INTERNET_OPEN_TYPE_PROXY e usa le informazioni ProxyServer e ProxyOverride .

Le funzioni WinINet forniscono supporto per i proxy di tipo SOCKS solo se Internet Explorer è installato. L'installazione di Internet Explorer include il file Wsock32n.dll, necessario per supportare i proxy SOCKS. Wsock32n.dll non è ridistribuibile.

Elenco dei server proxy

WinINet riconosce due tipi di proxy: proxy di tipo CERN (solo HTTP) e proxy FTP TIS (solo FTP). Se Internet Explorer è installato, WinINet supporta anche proxy di tipo SOCKS. InternetConnect presuppone, per impostazione predefinita, che il proxy specificato sia un proxy CERN. Se il tipo di accesso è impostato su INTERNET_OPEN_TYPE_DIRECT o INTERNET_OPEN_TYPE_PRECONFIG, il parametro lpszProxyName di InternetOpen deve essere impostato su NULL. In caso contrario, il valore passato a lpszProxyName deve contenere i proxy in una stringa delimitata dallo spazio. Gli elenchi proxy possono contenere il numero di porta usato per accedere al proxy.

Per elencare un proxy per un protocollo specifico, la stringa deve seguire il formato ""<protocol protocol><>://<proxy_name>"". I protocolli validi sono HTTP, HTTPS e FTP. Ad esempio, per elencare un proxy FTP, una stringa valida sarà ""ftp=ftp://ftp_proxy_name:21"", dove ftp_proxy_name è il nome del proxy FTP e 21 è il numero di porta che deve essere usato per accedere al proxy. Se il proxy usa il numero di porta predefinito per tale protocollo, è possibile omettere il numero di porta. Se un nome proxy è elencato da se stesso, viene usato come proxy predefinito per tutti i protocolli che non hanno un proxy specifico specificato. Ad esempio, ""http=https://http_proxy other"" userebbe http_proxy per qualsiasi operazione HTTP, mentre tutti gli altri protocolli userebbero altri protocolli.

Per impostazione predefinita, la funzione presuppone che il proxy specificato da lpszProxyName sia un proxy CERN. Un'applicazione può specificare più proxy, inclusi proxy diversi per i diversi protocolli. Ad esempio, se si specifica ""ftp=ftp://ftp-gw HTTP=https://jericho:99 proxy"", le richieste FTP vengono effettuate tramite il proxy ftp-gw, in ascolto della porta 21 e le richieste HTTP vengono effettuate tramite un proxy CERN denominato jericho, che è in ascolto alla porta 99. In caso contrario, le richieste HTTP verranno effettuate tramite il proxy CERN denominato proxy, che è in ascolto alla porta 80. Si noti che se l'applicazione usa solo FTP, ad esempio, non è necessario specificare ""ftp=ftp://ftp-gw:21". Potrebbe specificare solo ""ftp-gw"". Un'applicazione è necessaria solo per specificare i nomi di protocollo se usa più di un protocollo per handle restituito da InternetOpen.

Elenco del bypass del proxy

I nomi host o gli indirizzi IP che non devono essere inviati al proxy possono essere elencati nell'elenco di bypass del proxy. Questo elenco può contenere caratteri jolly, "*", che causano l'esclusione dell'applicazione dal server proxy per gli indirizzi che soddisfano il modello specificato. Per elencare più indirizzi e nomi host, separarli con punti e virgola nella stringa di bypass del proxy. Se viene specificata la macro "<local>", la funzione ignora il proxy per qualsiasi nome host che non contiene un punto.

Per impostazione predefinita, WinINet ignora il proxy per le richieste che usano i nomi host "localhost", "loopback", "127.0.0.1" o "[::1]". Questo comportamento esiste perché in genere un server proxy remoto non risolverà correttamente questi indirizzi.

Internet Explorer 9: È possibile rimuovere il computer locale dall'elenco di bypass proxy usando la macro "<-loopback>".

Nell'esempio seguente vengono illustrate chiamate di esempio a InternetOpen usando stringhe di bypass proxy diverse. I commenti sopra ogni chiamata descrivono l'effetto della stringa di bypass sui nomi host a cui viene eseguito l'accesso dall'handle HINTERNET creato.

HINTERNET hInternetRoot;

/* bypass the proxy for any host name that does not 
    contain a period */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("<local>"), 0);

/* bypass the proxy for any host name that starts with the 
    letters "ms" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("ms*"), 0);

/* bypass the proxy for any host name that contains "int", 
    such as "internet" and "painter" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("*int*"), 0);

/* bypass the proxy for the host name "example" and any 
    host name that contains "test" */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("proxy"),TEXT("example *test*"), 0);

/* Disable the loopback proxy bypass for localhost */
hInternetRoot = InternetOpen(TEXT("WinInet Example"), 
    INTERNET_OPEN_TYPE_PROXY,TEXT("127.0.0.1:8888"),TEXT("<-loopback>"), 0);

Uso di InternetConnect

Per iniziare una sessione, la funzione InternetConnect deve creare un handle fuori dall'handle radice restituito dalla funzione InternetOpen . InternetConnect imposta l'indirizzo del server, il numero di porta, il nome utente, la password e il tipo di servizio.

InternetConnect usa l'handle SNAPSHOTNET radice creato da InternetOpen per stabilire un handle di sessione. Se il flag INTERNET_FLAG_ASYNC è stato impostato nella chiamata a InternetOpen, la chiamata a InternetConnect deve includere un valore di contesto diverso da zero.

Il nome del server può contenere il nome host ,ad esempio "www.servername.com") o il numero IP del sito in formato ASCII con estensione decimale (ad esempio "10.0.1.45").

La porta del server è il numero di porta TCP/IP (Transmission Control Protocol/Internet Protocol) da connettere al server. InternetConnect usa la porta predefinita per il tipo di servizio selezionato se viene usato il valore INTERNET_INVALID_PORT_NUMBER. Le tabelle seguenti contengono le impostazioni predefinite della porta server per WinINet.

Valore	Significato
INTERNET_DEFAULT_FTP_PORT	Usare la porta predefinita per i server FTP (porta 21).
INTERNET_DEFAULT_GOPHER_PORT	Usare la porta predefinita per i server gopher (porta 70). Nota: Solo Windows XP e Windows Server 2003 R2 e versioni precedenti.
INTERNET_DEFAULT_HTTP_PORT	Usare la porta predefinita per i server HTTP (porta 80).
INTERNET_DEFAULT_HTTPS_PORT	Usare la porta predefinita per i server https (porta 443).
INTERNET_DEFAULT_SOCKS_PORT	Usare la porta predefinita per i server firewall SOCKS (porta 1080).

Definizione del nome utente e della password

Il valore di lpszUsername è l'indirizzo di una stringa con terminazione null contenente il nome dell'utente che esegue l'accesso. Se questo parametro è NULL, la funzione usa un valore predefinito appropriato, ad eccezione di HTTP. Un parametro NULL in HTTP causa la restituzione di un errore del server. Per il protocollo FTP, il valore predefinito è anonimo.

Il valore di lpszPassword è l'indirizzo di una stringa con terminazione null contenente la password di accesso. Se sia lpszUsername che lpszPassword sono NULL, la funzione usa la password anonima predefinita. Nel caso di FTP, la password anonima predefinita è il nome di posta elettronica dell'utente. Se lpszUsername non è NULL e lpszPassword è NULL, la funzione usa una password vuota. Esistono quattro possibili impostazioni di lpszUsername e lpszPassword, che producono i comportamenti illustrati nella tabella seguente.

lpszUsername	lpszPassword	Nome utente inviato al server FTP	Password inviata al server FTP
NULL	NULL	"anonimo"	Nome di posta elettronica dell'utente
Stringa non NULL	NULL	lpszUsername	""
NULL	Stringa non NULL	ERRORE	ERRORE
Stringa non NULL	Stringa non NULL	lpszUsername	lpszPassword

Queste informazioni possono essere modificate usando le funzioni InternetSetOption e InternetErrorDlg . InternetSetOption modifica i valori di nome utente e password, mentre InternetErrorDlg visualizza una finestra di dialogo che richiede il nome utente e la password appropriati.

Definizione della sessione

Per definire la sessione stabilita, impostare il tipo di servizio, i flag e il valore di contesto per InternetConnect.

Esistono due tipi di servizio disponibili per InternetConnect: INTERNET_SERVICE_FTP e INTERNET_SERVICE_HTTP. INTERNET_SERVICE_HTTP viene usato per le sessioni HTTP e HTTPS.

INTERNET_FLAG_PASSIVE è l'unico flag specifico del servizio usato dalle funzioni WinINet. Questo flag può essere impostato quando il tipo di servizio è INTERNET_SERVICE_FTP per usare la semantica FTP passiva.

Per tutte le operazioni sincrone, il valore di dwContext deve essere impostato su zero. Se le operazioni asincrone sono state stabilite impostando il flag INTERNET_FLAG_ASYNC nella chiamata a InternetOpen, è necessario specificare un valore diverso da zero per dwContext. Per altre informazioni sulle operazioni asincrone, vedere Configurazione di operazioni asincrone.

Per le sessioni FTP, InternetConnect tenta di stabilire una connessione al server su Internet. Per le sessioni HTTP, InternetConnect non stabilisce una connessione finché un'altra funzione non tenta di ottenere informazioni dal server.

Nota

WinINet non supporta le implementazioni del server. Inoltre, non deve essere usato da un servizio. Per le implementazioni del server o i servizi, usare i servizi HTTP di Microsoft Windows (WinHTTP).