Memorizzazione nella cache (Windows Internet)

Le funzioni WinINet hanno un supporto di memorizzazione nella cache semplice, ma flessibile e predefinito. Tutti i dati recuperati dalla rete vengono memorizzati nella cache sul disco rigido e recuperati per le richieste successive. L'applicazione può controllare la memorizzazione nella cache in ogni richiesta. Per le richieste HTTP dal server, vengono memorizzate nella cache anche la maggior parte delle intestazioni ricevute. Quando una richiesta HTTP viene soddisfatta dalla cache, anche le intestazioni memorizzate nella cache vengono restituite al chiamante. Ciò rende facile il download dei dati, indipendentemente dal fatto che i dati provenino dalla cache o dalla rete.

Le applicazioni devono allocare correttamente un buffer per ottenere i risultati desiderati quando si usano le funzioni di memorizzazione nella cache degli URL persistenti. Per altre informazioni, vedere Uso dei buffer.

Comportamento della cache durante l'elaborazione della risposta

La cache WinINet è conforme alle direttive HTTP cache-control descritte in RFC 2616. Le direttive di controllo della cache e i flag del set di applicazioni determinano cosa può essere memorizzato nella cache; Tuttavia, WinINet determina ciò che viene effettivamente memorizzato nella cache in base al criterio seguente:

• WinINet memorizza nella cache solo le risposte HTTP e FTP.
• Solo risposte ben comportate possono essere archiviate da una cache e usate in una risposta a una richiesta successiva. Le risposte ben comportate vengono definite come risposte che restituiscono correttamente.
• Per impostazione predefinita, WinINet memorizza nella cache le risposte riuscite, a meno che non venga memorizzata una direttiva di controllo della cache dal server o un flag definito dall'applicazione in modo specifico indica che la risposta potrebbe non essere memorizzata nella cache.
• In generale, le risposte al verbo GET vengono memorizzate nella cache se vengono soddisfatti i requisiti elencati in precedenza. Le risposte ai verbi PUT e POST non vengono memorizzate nella cache in alcuna circostanza.
• Gli elementi verranno memorizzati nella cache anche quando la cache è piena. Se un elemento aggiunto supera il limite di dimensioni, lo scavenger della cache viene pianificato. Per impostazione predefinita, non è garantito che gli elementi rimangano più di 10 minuti nella cache. Per altre informazioni, vedere la sezione Cache Scavenger di seguito.
• Https viene memorizzato nella cache per impostazione predefinita. Viene gestito da un'impostazione globale che non può essere sottoposta a override dalle direttive della cache definite dall'applicazione. Per eseguire l'override dell'impostazione globale, selezionare l'applet Opzioni Internet nel pannello di controllo e passare alla scheda Avanzate. Selezionare la casella "Non salvare le pagine crittografate su disco" nella sezione "Sicurezza".

Cache Scavenger

Lo scavenger della cache pulisce periodicamente gli elementi dalla cache. Se un elemento viene aggiunto alla cache e la cache è piena, l'elemento viene aggiunto alla cache e viene pianificato lo scavenger della cache. Se lo scavenger della cache completa un round di scavenging e la cache non ha raggiunto il limite di cache, lo scavenger viene pianificato per un altro round quando viene aggiunto un altro elemento alla cache. In generale, lo scavenger viene pianificato quando un elemento aggiunto inserisce la cache oltre il limite di dimensioni. Per impostazione predefinita, il tempo minimo per la memorizzazione nella cache è impostato su 10 minuti, se non diversamente specificato in una direttiva di controllo della cache. Quando viene avviato lo scavenger della cache, non esiste alcuna garanzia che gli elementi meno recenti siano i primi a essere eliminati dalla cache.

La cache viene condivisa tra tutte le applicazioni WinINet nel computer per lo stesso utente. A partire da Windows Vista e Windows Server 2008 le dimensioni della cache sono impostate su 1/32nd le dimensioni del disco, con una dimensione minima di 8 MB e una dimensione massima di 50 MB.

Uso dei flag per controllare la memorizzazione nella cache

I flag di memorizzazione nella cache consentono a un'applicazione di controllare quando e come usa la cache. Questi flag possono essere usati da soli o in combinazione con il parametro dwFlags nelle funzioni che accedono a informazioni o risorse su Internet. Per impostazione predefinita, le funzioni archiviano tutti i dati scaricati da Internet.

I flag seguenti possono essere usati per controllare la memorizzazione nella cache.

Funzioni di memorizzazione nella cache persistente

I client che necessitano di servizi di memorizzazione nella cache persistente usano le funzioni di memorizzazione nella cache persistente per consentire alle applicazioni di salvare i dati nel file system locale per un uso successivo, ad esempio in situazioni in cui un collegamento a larghezza di banda ridotta limita l'accesso ai dati o l'accesso non è disponibile affatto.

Le funzioni della cache forniscono la memorizzazione nella cache permanente e l'esplorazione offline. A meno che il flag INTERNET_FLAG_NO_CACHE_WRITE non specifichi in modo esplicito alcuna memorizzazione nella cache, le funzioni memorizzano nella cache tutti i dati scaricati dalla rete. Le risposte ai dati POST non vengono memorizzate nella cache.

Uso delle funzioni della cache degli URL persistenti

Le funzioni cache url persistenti seguenti consentono a un'applicazione di accedere e modificare le informazioni archiviate nella cache.

Enumerazione della cache

Le funzioni FindFirstUrlCacheEntry e FindNextUrlCacheEntry enumera le informazioni archiviate nella cache. FindFirstUrlCacheEntry avvia l'enumerazione prendendo un criterio di ricerca, un buffer e una dimensione del buffer per creare un handle e restituire la prima voce della cache. FindNextUrlCacheEntry accetta l'handle creato da FindFirstUrlCacheEntry, un buffer e una dimensione del buffer per restituire la voce della cache successiva.

Entrambe le funzioni archiviano una struttura INTERNET_CACHE_ENTRY_INFO nel buffer. Le dimensioni di questa struttura variano per ogni voce. Se le dimensioni del buffer passate a una delle due funzioni non sono sufficienti, la funzione ha esito negativo e GetLastError restituisce ERROR_INSUFFICIENT_BUFFER. La variabile delle dimensioni del buffer contiene le dimensioni del buffer necessarie per recuperare la voce della cache. È necessario allocare un buffer delle dimensioni indicate dalla variabile di dimensione del buffer e chiamare nuovamente la funzione con il nuovo buffer.

La struttura INTERNET_CACHE_ENTRY_INFO contiene le dimensioni della struttura, l'URL delle informazioni memorizzate nella cache, il nome del file locale, il tipo di voce della cache, il numero di riscontri, la frequenza di hit, le dimensioni, l'ora dell'ultima modifica, la scadenza, l'ultimo accesso, l'ora dell'ultima sincronizzazione, le informazioni sull'intestazione, le dimensioni delle informazioni sull'intestazione e l'estensione del nome file.

La funzione FindFirstUrlCacheEntry accetta un criterio di ricerca, un buffer che archivia la struttura INTERNET_CACHE_ENTRY_INFO e le dimensioni del buffer. Attualmente viene implementato solo il modello di ricerca predefinito, che restituisce tutte le voci della cache.

Dopo l'enumerazione della cache, l'applicazione deve chiamare FindCloseUrlCache per chiudere l'handle di enumerazione della cache.

Nell'esempio seguente viene visualizzato l'URL di ogni voce della cache in una casella di riepilogo IDC_CacheList. Usa MAX_CACHE_ENTRY_INFO_SIZE per allocare inizialmente un buffer, poiché le versioni iniziali dell'API WinINet non enumerano correttamente la cache in caso contrario. Le versioni successive enumerano correttamente la cache e non è previsto alcun limite di dimensioni della cache. Tutte le applicazioni eseguite nei computer con la versione dell'API WinINet da Internet Explorer 4.0 devono allocare un buffer delle dimensioni necessarie. Per altre informazioni, vedere Uso dei buffer.

int WINAPI EnumerateCacheOld(HWND hX)
{
    DWORD dwEntrySize;
    LPINTERNET_CACHE_ENTRY_INFO lpCacheEntry;
    DWORD MAX_CACHE_ENTRY_INFO_SIZE = 4096;
    HANDLE hCacheDir;
    int nCount=0;

    SendDlgItemMessage(hX,IDC_CacheList,LB_RESETCONTENT,0,0);
    
    SetCursor(LoadCursor(NULL,IDC_WAIT));

    dwEntrySize = MAX_CACHE_ENTRY_INFO_SIZE;
    lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO) new char[dwEntrySize];
    lpCacheEntry->dwStructSize = dwEntrySize;

again:

    hCacheDir = FindFirstUrlCacheEntry(NULL,
                                       lpCacheEntry,
                                       &dwEntrySize);
    if (!hCacheDir)                                             
    {
        delete[]lpCacheEntry;
        switch(GetLastError())
        {
            case ERROR_NO_MORE_ITEMS: 
                TCHAR tempout[80];
                _stprintf_s(tempout, 
                            80,   
                            TEXT("The number of cache entries = %d \n"),
                            nCount);
                MessageBox(hX,tempout,TEXT("Cache Enumeration"),MB_OK);
                FindCloseUrlCache(hCacheDir);
                SetCursor(LoadCursor(NULL,IDC_ARROW));
                return TRUE;
                break;
            case ERROR_INSUFFICIENT_BUFFER:
                lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO) 
                                new char[dwEntrySize];
                lpCacheEntry->dwStructSize = dwEntrySize;
                goto again;
                break;
            default:
                ErrorOut( hX,GetLastError(),
                          TEXT("FindNextUrlCacheEntry Init"));
                FindCloseUrlCache(hCacheDir);
                SetCursor(LoadCursor(NULL,IDC_ARROW));
                return FALSE;
        }
    }

    SendDlgItemMessage(hX,IDC_CacheList,LB_ADDSTRING,
                       0,(LPARAM)(lpCacheEntry->lpszSourceUrlName));
    nCount++;
    delete (lpCacheEntry);

    do 
    {
        dwEntrySize = MAX_CACHE_ENTRY_INFO_SIZE;
        lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO) new char[dwEntrySize];
        lpCacheEntry->dwStructSize = dwEntrySize;

retry:
        if (!FindNextUrlCacheEntry(hCacheDir,
                                   lpCacheEntry, 
                                   &dwEntrySize))
        {
            delete[]lpCacheEntry;
            switch(GetLastError())
            {
                case ERROR_NO_MORE_ITEMS: 
                    TCHAR tempout[80];
                    _stprintf_s(tempout,
                                80,
                                TEXT("The number of cache entries = %d \n"),nCount);
                    MessageBox(hX,
                               tempout,
                               TEXT("Cache Enumeration"),MB_OK);
                    FindCloseUrlCache(hCacheDir);
                    return TRUE;
                    break;
                case ERROR_INSUFFICIENT_BUFFER:
                    lpCacheEntry = 
                             (LPINTERNET_CACHE_ENTRY_INFO) 
                              new char[dwEntrySize];
                    lpCacheEntry->dwStructSize = dwEntrySize;
                    goto retry;
                    break;
                default:
                    ErrorOut(hX,
                             GetLastError(),
                             TEXT("FindNextUrlCacheEntry Init"));
                    FindCloseUrlCache(hCacheDir);
                    return FALSE;
            }
        }

        SendDlgItemMessage(hX,
                           IDC_CacheList,LB_ADDSTRING,
                           0,
                          (LPARAM)(lpCacheEntry->lpszSourceUrlName));
        nCount++;
        delete[] lpCacheEntry;        
    }  while (TRUE);

    SetCursor(LoadCursor(NULL,IDC_ARROW));
    return TRUE;        
}

Recupero delle informazioni sulla voce della cache

La funzione GetUrlCacheEntryInfo consente di recuperare la struttura INTERNET_CACHE_ENTRY_INFO per l'URL specificato. Questa struttura contiene le dimensioni della struttura, l'URL delle informazioni memorizzate nella cache, il nome del file locale, il tipo di voce della cache, il conteggio, la frequenza di hit, le dimensioni, l'ora dell'ultima modifica, la scadenza, l'ultimo accesso, l'ora dell'ultima sincronizzazione, le informazioni di intestazione, le dimensioni delle informazioni di intestazione e l'estensione del nome file.

GetUrlCacheEntryInfo accetta un URL, un buffer per una struttura INTERNET_CACHE_ENTRY_INFO e le dimensioni del buffer. Se viene trovato l'URL, le informazioni sono copiate nel buffer. In caso contrario, la funzione ha esito negativo e GetLastError restituisce ERROR_FILE_NOT_FOUND. Se le dimensioni del buffer non sono sufficienti per archiviare le informazioni sulla voce della cache, la funzione ha esito negativo e GetLastError restituisce ERROR_INSUFFICIENT_BUFFER. Le dimensioni necessarie per recuperare le informazioni vengono archiviate nella variabile delle dimensioni del buffer.

GetUrlCacheEntryInfo non esegue l'analisi degli URL, quindi un URL che contiene un ancoraggio (#) non verrà trovato nella cache, anche se la risorsa viene memorizzata nella cache. Ad esempio, se l'URL "https://example.com/example.htm#sample" viene passata, la funzione restituisce ERROR_FILE_NOT_FOUND anche se "https://example.com/example.htm" è nella cache.

Nell'esempio seguente vengono recuperate le informazioni sulla voce della cache per l'URL specificato. La funzione visualizza quindi le informazioni sull'intestazione nella casella di modifica IDC_CacheDump .

int WINAPI GetCacheEntryInfo(HWND hX,LPTSTR lpszUrl)
{
    DWORD dwEntrySize=0;
    LPINTERNET_CACHE_ENTRY_INFO lpCacheEntry;

    SetCursor(LoadCursor(NULL,IDC_WAIT));
    if (!GetUrlCacheEntryInfo(lpszUrl,NULL,&dwEntrySize))
    {
        if (GetLastError()!=ERROR_INSUFFICIENT_BUFFER)
        {
            ErrorOut(hX,GetLastError(),TEXT("GetUrlCacheEntryInfo"));
            SetCursor(LoadCursor(NULL,IDC_ARROW));
            return FALSE;
        }
        else
            lpCacheEntry = (LPINTERNET_CACHE_ENTRY_INFO) 
                            new char[dwEntrySize];
    }
    else
        return FALSE; // should not be successful w/ NULL buffer
                      // and 0 size

    if (!GetUrlCacheEntryInfo(lpszUrl,lpCacheEntry,&dwEntrySize))
    {
        ErrorOut(hX,GetLastError(),TEXT("GetUrlCacheEntryInfo"));
        SetCursor(LoadCursor(NULL,IDC_ARROW));
        return FALSE;
    }
    else
    {
        if ((lpCacheEntry->dwHeaderInfoSize)!=0)
        {
            LPSTR(lpCacheEntry->lpHeaderInfo)
                                [lpCacheEntry->dwHeaderInfoSize]=TEXT('\0');
            SetDlgItemText(hX,IDC_Headers,
                           lpCacheEntry->lpHeaderInfo);
        }
        else
        {
            SetDlgItemText(hX,IDC_Headers,TEXT("None"));
        }

        SetCursor(LoadCursor(NULL,IDC_ARROW));
        return TRUE;
    }
        
}

Creazione di una voce della cache

Un'applicazione usa le funzioni CreateUrlCacheEntry e CommitUrlCacheEntry per creare una voce della cache.

CreateUrlCacheEntry accetta l'URL, le dimensioni previste del file e l'estensione del nome file. La funzione crea quindi un nome di file locale per salvare la voce della cache corrispondente all'URL e all'estensione del nome file.

Usando il nome del file locale, scrivere i dati nel file locale. Dopo che i dati sono stati scritti nel file locale, l'applicazione deve chiamare CommitUrlCacheEntry.

CommitUrlCacheEntry accetta l'URL, il nome del file locale, la scadenza, l'ora dell'ultima modifica, il tipo di voce della cache, le informazioni di intestazione, le dimensioni delle informazioni di intestazione e l'estensione del nome file. La funzione memorizza quindi nella cache i dati nel file specificato nell'archiviazione della cache e lo associa all'URL specificato.

Nell'esempio seguente viene utilizzato il nome del file locale, creato da una chiamata precedente a CreateUrlCacheEntry, archiviato nella casella di testo IDC_LocalFile, per archiviare il testo dalla casella di testo , IDC_CacheDump, nella voce della cache. Dopo che i dati sono stati scritti nel file usando fopen, fprintf e fclose, viene eseguito il commit della voce usando CommitUrlCacheEntry.

int WINAPI CommitEntry(HWND hX)
{
    LPTSTR lpszUrl, lpszExt, lpszFileName;
    LPTSTR lpszData,lpszSize;
    DWORD dwSize;
    DWORD dwEntryType=0;
    FILE *lpfCacheEntry;
    LPFILETIME lpdtmExpire, lpdtmLastModified;
    LPSYSTEMTIME lpdtmSysTime;
    errno_t err;

    if( SendDlgItemMessage(hX,IDC_RBNormal,BM_GETCHECK,0,0) )
    {
        dwEntryType = dwEntryType + NORMAL_CACHE_ENTRY;
    }
    else if( SendDlgItemMessage(hX,IDC_RBSticky, BM_GETCHECK,0,0) )
    {
        dwEntryType = dwEntryType + STICKY_CACHE_ENTRY;
    }
    else if(SendDlgItemMessage( hX,IDC_RBSparse, BM_GETCHECK,0,0) )
    {
        dwEntryType = dwEntryType + SPARSE_CACHE_ENTRY;
    }
 

    if( SendDlgItemMessage(hX,IDC_RBCookie, BM_GETCHECK,0,0))
    {
            dwEntryType = dwEntryType + COOKIE_CACHE_ENTRY;
    }
    else if( SendDlgItemMessage(hX,IDC_RBUrl, BM_GETCHECK,0,0) )
    {
        dwEntryType = dwEntryType + URLHISTORY_CACHE_ENTRY;
    }


    if( SendDlgItemMessage(hX,IDC_RBNone, BM_GETCHECK,0,0) )
    {
        dwEntryType=0;
    }
        
    lpdtmSysTime = new SYSTEMTIME;
    lpdtmExpire = new FILETIME;
    lpdtmLastModified = new FILETIME;

    GetLocalTime(lpdtmSysTime);
    SystemTimeToFileTime(lpdtmSysTime,lpdtmExpire);
    SystemTimeToFileTime(lpdtmSysTime,lpdtmLastModified);
    delete(lpdtmSysTime);

    lpszUrl = new TCHAR[MAX_PATH];
    lpszFileName = new TCHAR[MAX_PATH];
    lpszExt = new TCHAR[5];
    lpszSize = new TCHAR[10];

    GetDlgItemText(hX,IDC_SourceURL,lpszUrl,MAX_PATH);
    GetDlgItemText(hX,IDC_LocalFile,lpszFileName,MAX_PATH);
    GetDlgItemText(hX,IDC_FileExt,lpszExt,5);

    GetDlgItemText(hX,IDC_SizeLow,lpszSize,10);
    dwSize = (DWORD)_ttol(lpszSize);
    delete(lpszSize);

    if (dwSize==0)
    {
        if((MessageBox(hX,
                       TEXT("Incorrect File Size.\nUsing 8000 characters, Okay?\n"),
                       TEXT("Commit Entry"),MB_YESNO))
                        ==IDYES)
        {
            dwSize = 8000;
        }
        else
        {
            return FALSE;
        }
    }

    lpszData = new TCHAR[dwSize];
    GetDlgItemText(hX,IDC_CacheDump,lpszData,dwSize);
        
     err = _tfopen_s(&lpfCacheEntry,lpszFileName,_T("w"));
     if (err)
        return FALSE;
    fprintf(lpfCacheEntry,"%s",lpszData);
    fclose(lpfCacheEntry);
    delete(lpszData);

    if ( !CommitUrlCacheEntry( lpszUrl, 
                               lpszFileName, 
                               *lpdtmExpire,
                               *lpdtmLastModified, 
                               dwEntryType,
                               NULL,
                               0,
                               lpszExt,
                               0) )
    {
        ErrorOut(hX,GetLastError(),TEXT("Commit Cache Entry"));
        delete(lpszUrl);
        delete(lpszFileName);
        delete(lpszExt);
        delete(lpdtmExpire);
        delete(lpdtmLastModified);
        return FALSE;
    }
    else
    {
        delete(lpszUrl);
        delete(lpszFileName);
        delete(lpszExt);
        delete(lpdtmExpire);
        delete(lpdtmLastModified);
        return TRUE;
    }
}

Eliminazione di una voce della cache

La funzione DeleteUrlCacheEntry accetta un URL e rimuove il file della cache associato. Se il file della cache non esiste, la funzione ha esito negativo e GetLastError restituisce ERROR_FILE_NOT_FOUND. Se il file della cache è attualmente bloccato o in uso, la funzione ha esito negativo e GetLastError restituisce ERROR_ACCESS_DENIED. Il file viene eliminato quando viene sbloccato.

Recupero dei file di immissione della cache

Per le applicazioni che richiedono il nome file di una risorsa, usare le funzioni RetrieveUrlCacheEntryFile e UnlockUrlCacheEntryFile . Le applicazioni che non richiedono il nome file devono usare le funzioni RetrieveUrlCacheEntryStream, ReadUrlCacheEntryStream e UnlockUrlCacheEntryStream per recuperare le informazioni nella cache.

RetrieveUrlCacheEntryStream non esegue l'analisi degli URL, quindi un URL che contiene un ancoraggio (#) non verrà trovato nella cache, anche se la risorsa viene memorizzata nella cache. Ad esempio, se l'URL "https://example.com/example.htm#sample" viene passata, la funzione restituisce ERROR_FILE_NOT_FOUND anche se "https://example.com/example.htm" è nella cache.

RetrieveUrlCacheEntryFile accetta un URL, un buffer che archivia la struttura INTERNET_CACHE_ENTRY_INFO e le dimensioni del buffer. La funzione viene recuperata e bloccata per il chiamante.

Dopo aver usato le informazioni nel file, l'applicazione deve chiamare UnlockUrlCacheEntryFile per sbloccare il file.

Gruppi di cache

Per creare un gruppo di cache, è necessario chiamare la funzione CreateUrlCacheGroup per generare un GROUPID per il gruppo di cache. Le voci possono essere aggiunte al gruppo di cache specificando l'URL della voce della cache e il flag INTERNET_CACHE_GROUP_ADD alla funzione SetUrlCacheEntryGroup . Per rimuovere una voce della cache da un gruppo, passare l'URL della voce della cache e il flag INTERNET_CACHE_GROUP_REMOVE a SetUrlCacheEntryGroup.

Le funzioni FindFirstUrlCacheEntryEx e FindNextUrlCacheEntryEx possono essere usate per enumerare le voci in un gruppo di cache specificato. Al termine dell'enumerazione, la funzione deve chiamare FindCloseUrlCache.

Gestione delle strutture con informazioni sulle dimensioni delle variabili

La cache può contenere informazioni sulle dimensioni delle variabili per ogni URL archiviato. Ciò si riflette nella struttura INTERNET_CACHE_ENTRY_INFO . Quando le funzioni della cache restituiscono questa struttura, creano un buffer che corrisponde sempre alle dimensioni di INTERNET_CACHE_ENTRY_INFO più eventuali informazioni sulle dimensioni delle variabili. Se un membro del puntatore non è NULL, punta all'area di memoria immediatamente dopo la struttura. Durante la copia del buffer restituito da una funzione in un altro buffer, i membri del puntatore devono essere fissi in modo che puntino alla posizione appropriata nel nuovo buffer, come illustrato nell'esempio seguente.

lpDstCEInfo->lpszSourceUrlName = 
    (LPINTERNET_CACHE_ENTRY_INFO) ((LPBYTE) lpSrcCEInfo + 
       ((DWORD)(lpOldCEInfo->lpszSourceUrlName) - (DWORD)lpOldCEInfo));

Alcune funzioni della cache hanno esito negativo con il messaggio di errore ERROR_INSUFFICIENT_BUFFER se si specifica un buffer troppo piccolo per contenere le informazioni sulla voce della cache recuperate dalla funzione. In questo caso, la funzione restituisce anche le dimensioni necessarie del buffer. È quindi possibile allocare un buffer delle dimensioni appropriate e chiamare di nuovo la funzione.