Mise en cache (Windows Internet)

Les fonctions WinINet ont une prise en charge de la mise en cache intégrée simple, mais flexible. Toutes les données récupérées à partir du réseau sont mises en cache sur le disque dur et récupérées pour les demandes suivantes. L’application peut contrôler la mise en cache sur chaque requête. Pour les requêtes HTTP provenant du serveur, la plupart des en-têtes reçus sont également mis en cache. Lorsqu’une requête HTTP est satisfaite à partir du cache, les en-têtes mis en cache sont également retournés à l’appelant. Cela facilite le téléchargement des données, que les données proviennent du cache ou du réseau.

Les applications doivent allouer correctement une mémoire tampon afin d’obtenir les résultats souhaités lors de l’utilisation des fonctions de mise en cache d’URL persistantes. Pour plus d’informations, consultez Utilisation de tampons.

Comportement du cache pendant le traitement de la réponse

Le cache WinINet est conforme aux directives de contrôle de cache HTTP décrites dans RFC 2616. Les directives de contrôle de cache et les indicateurs de jeu d’applications déterminent ce qui peut être mis en cache ; Toutefois, WinINet détermine ce qui est réellement mis en cache en fonction du critère suivant :

• WinINet met uniquement en cache les réponses HTTP et FTP.
• Seules les réponses bien comportementées peuvent être stockées par un cache et utilisées dans une réponse à une demande suivante. Les réponses bien comportementées sont définies comme des réponses qui retournent avec succès.
• Par défaut, WinINet met en cache les réponses réussies, sauf si une directive de contrôle de cache du serveur ou un indicateur défini par l’application indique spécifiquement que la réponse ne peut pas être mise en cache.
• En général, les réponses au verbe GET sont mises en cache si les conditions répertoriées ci-dessus sont remplies. Les réponses aux verbes PUT et POST ne sont en aucun cas mises en cache.
• Les éléments sont mis en cache même lorsque le cache est plein. Si un élément ajouté place le cache au-dessus de la limite de taille, le charognard de cache est planifié. Par défaut, il n’est pas garanti que les éléments restent plus de 10 minutes dans le cache. Pour plus d’informations, consultez la section Cache Scavenger ci-dessous.
• Https est mis en cache par défaut. Ce paramètre est géré par un paramètre global qui ne peut pas être remplacé par des directives de cache définies par l’application. Pour remplacer le paramètre global, sélectionnez l’applet Options Internet dans le panneau de configuration, puis accédez à l’onglet Avancé. Cochez la case « Ne pas enregistrer les pages chiffrées sur le disque » sous la section « Sécurité ».

Cache Scavenger

Le charognard de cache nettoie régulièrement les éléments du cache. Si un élément est ajouté au cache et que le cache est plein, l’élément est ajouté au cache et le cache scavenger est planifié. Si le charognard de cache effectue une série de nettoyages et que le cache n’a pas atteint la limite de cache, le charognard est planifié pour une autre ronde lorsqu’un autre élément est ajouté au cache. En général, le scavenger est planifié lorsqu’un élément ajouté place le cache au-dessus de sa limite de taille. Par défaut, la durée minimale de vie dans le cache est définie sur 10 minutes, sauf indication contraire dans une directive de contrôle de cache. Lorsque le scavenger de cache est lancé, il n’existe aucune garantie que les éléments les plus anciens sont les premiers à être supprimés du cache.

Le cache est partagé entre toutes les applications WinINet sur l’ordinateur pour le même utilisateur. À compter de Windows Vista et Windows Server 2008, la taille du cache est définie sur 1/32nd de la taille du disque, avec une taille minimale de 8 Mo et une taille maximale de 50 Mo.

Utilisation d’indicateurs pour contrôler la mise en cache

Les indicateurs de mise en cache permettent à une application de contrôler quand et comment elle utilise le cache. Ces indicateurs peuvent être utilisés seuls ou en combinaison avec le paramètre dwFlags dans les fonctions qui accèdent à des informations ou à des ressources sur Internet. Par défaut, les fonctions stockent toutes les données téléchargées à partir d’Internet.

Les indicateurs suivants peuvent être utilisés pour contrôler la mise en cache.

Fonctions de mise en cache permanente

Les clients qui ont besoin de services de mise en cache permanente utilisent les fonctions de mise en cache permanente pour permettre à leurs applications d’enregistrer des données dans le système de fichiers local en vue d’une utilisation ultérieure, par exemple dans les situations où une liaison à faible bande passante limite l’accès aux données, ou où l’accès n’est pas disponible du tout.

Les fonctions de cache fournissent une mise en cache persistante et une navigation hors connexion. À moins que l’indicateur INTERNET_FLAG_NO_CACHE_WRITE ne spécifie explicitement aucune mise en cache, les fonctions mettez en cache toutes les données téléchargées à partir du réseau. Les réponses aux données POST ne sont pas mises en cache.

Utilisation des fonctions de cache d’URL persistantes

Les fonctions de cache d’URL persistantes suivantes permettent à une application d’accéder aux informations stockées dans le cache et de les manipuler.

Énumération du cache

Les fonctions FindFirstUrlCacheEntry et FindNextUrlCacheEntry énumèrent les informations stockées dans le cache. FindFirstUrlCacheEntry démarre l’énumération en prenant un modèle de recherche, une mémoire tampon et une taille de mémoire tampon pour créer un handle et retourner la première entrée de cache. FindNextUrlCacheEntry prend le handle créé par FindFirstUrlCacheEntry, une mémoire tampon et une taille de mémoire tampon pour retourner l’entrée de cache suivante.

Les deux fonctions stockent une structure INTERNET_CACHE_ENTRY_INFO dans la mémoire tampon. La taille de cette structure varie pour chaque entrée. Si la taille de mémoire tampon passée à l’une ou l’autre des fonctions est insuffisante, la fonction échoue et GetLastError retourne ERROR_INSUFFICIENT_BUFFER. La variable de taille de mémoire tampon contient la taille de mémoire tampon nécessaire pour récupérer cette entrée de cache. Une mémoire tampon de la taille indiquée par la variable de taille de mémoire tampon doit être allouée, et la fonction doit être appelée à nouveau avec la nouvelle mémoire tampon.

La structure INTERNET_CACHE_ENTRY_INFO contient la taille de la structure, l’URL des informations mises en cache, le nom du fichier local, le type d’entrée du cache, le nombre d’utilisations, le taux d’accès, la taille, l’heure de la dernière modification, l’expiration, le dernier accès, l’heure de la dernière synchronisation, les informations d’en-tête, la taille des informations d’en-tête et l’extension de nom de fichier.

La fonction FindFirstUrlCacheEntry prend un modèle de recherche, une mémoire tampon qui stocke la structure INTERNET_CACHE_ENTRY_INFO et la taille de la mémoire tampon. Actuellement, seul le modèle de recherche par défaut, qui retourne toutes les entrées de cache, est implémenté.

Une fois le cache énuméré, l’application doit appeler FindCloseUrlCache pour fermer le handle d’énumération du cache.

L’exemple suivant affiche l’URL de chaque entrée de cache dans une zone de liste , IDC_CacheList. Il utilise MAX_CACHE_ENTRY_INFO_SIZE pour allouer initialement une mémoire tampon, car les premières versions de l’API WinINet n’énumèrent pas correctement le cache dans le cas contraire. Les versions ultérieures énumèrent correctement le cache et il n’existe aucune limite de taille de cache. Toutes les applications qui s’exécutent sur des ordinateurs dotés de la version de l’API WinINet d’Internet Explorer 4.0 doivent allouer une mémoire tampon de la taille requise. Pour plus d’informations, consultez Utilisation de tampons.

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;        
}

Récupération des informations d’entrée du cache

La fonction GetUrlCacheEntryInfo vous permet de récupérer la structure INTERNET_CACHE_ENTRY_INFO pour l’URL spécifiée. Cette structure contient la taille de la structure, l’URL des informations mises en cache, le nom du fichier local, le type d’entrée du cache, le nombre d’utilisations, le taux d’accès, la taille, l’heure de la dernière modification, l’expiration, le dernier accès, l’heure de la dernière synchronisation, les informations d’en-tête, la taille des informations d’en-tête et l’extension de nom de fichier.

GetUrlCacheEntryInfo accepte une URL, une mémoire tampon pour une structure INTERNET_CACHE_ENTRY_INFO et la taille de la mémoire tampon. Si l’URL est trouvée, les informations sont copiées dans la mémoire tampon. Sinon, la fonction échoue et GetLastError retourne ERROR_FILE_NOT_FOUND. Si la taille de la mémoire tampon est insuffisante pour stocker les informations d’entrée du cache, la fonction échoue et GetLastError retourne ERROR_INSUFFICIENT_BUFFER. La taille requise pour récupérer les informations est stockée dans la variable de taille de mémoire tampon.

GetUrlCacheEntryInfo n’effectue aucune analyse d’URL, de sorte qu’une URL contenant une ancre (#) ne se trouve pas dans le cache, même si la ressource est mise en cache. Par exemple, si l’URL «https://example.com/example.htm#sample" ; est passé, la fonction retourne ERROR_FILE_NOT_FOUND même si «https://example.com/example.htm" ; est dans le cache.

L’exemple suivant récupère les informations d’entrée de cache pour l’URL spécifiée. La fonction affiche ensuite les informations d’en-tête dans la zone d’édition 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;
    }
        
}

Création d’une entrée de cache

Une application utilise les fonctions CreateUrlCacheEntry et CommitUrlCacheEntry pour créer une entrée de cache.

CreateUrlCacheEntry accepte l’URL, la taille de fichier attendue et l’extension de nom de fichier. La fonction crée ensuite un nom de fichier local pour enregistrer l’entrée de cache qui correspond à l’URL et à l’extension de nom de fichier.

À l’aide du nom de fichier local, écrivez les données dans le fichier local. Une fois les données écrites dans le fichier local, l’application doit appeler CommitUrlCacheEntry.

CommitUrlCacheEntry accepte l’URL, le nom de fichier local, l’expiration, l’heure de la dernière modification, le type d’entrée de cache, les informations d’en-tête, la taille des informations d’en-tête et l’extension de nom de fichier. La fonction met ensuite en cache les données dans le fichier spécifié dans le stockage du cache et les associe à l’URL donnée.

L’exemple suivant utilise le nom de fichier local, créé par un appel précédent à CreateUrlCacheEntry, stocké dans la zone de texte , IDC_LocalFile, pour stocker le texte de la zone de texte , IDC_CacheDump, dans l’entrée de cache. Une fois les données écrites dans le fichier à l’aide de fopen, fprintf et fclose, l’entrée est validée à l’aide de 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;
    }
}

Suppression d’une entrée de cache

La fonction DeleteUrlCacheEntry prend une URL et supprime le fichier de cache qui lui est associé. Si le fichier de cache n’existe pas, la fonction échoue et GetLastError retourne ERROR_FILE_NOT_FOUND. Si le fichier cache est actuellement verrouillé ou en cours d’utilisation, la fonction échoue et GetLastError retourne ERROR_ACCESS_DENIED. Le fichier est supprimé lorsqu’il est déverrouillé.

Récupération des fichiers d’entrée de cache

Pour les applications qui nécessitent le nom de fichier d’une ressource, utilisez les fonctions RetrieveUrlCacheEntryFile et UnlockUrlCacheEntryFile . Les applications qui ne nécessitent pas le nom de fichier doivent utiliser les fonctions RetrieveUrlCacheEntryStream, ReadUrlCacheEntryStream et UnlockUrlCacheEntryStream pour récupérer les informations dans le cache.

RetrieveUrlCacheEntryStream n’effectue aucune analyse d’URL, de sorte qu’une URL contenant une ancre (#) ne se trouve pas dans le cache, même si la ressource est mise en cache. Par exemple, si l’URL «https://example.com/example.htm#sample" ; est passé, la fonction retourne ERROR_FILE_NOT_FOUND même si «https://example.com/example.htm" ; est dans le cache.

RetrieveUrlCacheEntryFile accepte une URL, une mémoire tampon qui stocke la structure INTERNET_CACHE_ENTRY_INFO et la taille de la mémoire tampon. La fonction est récupérée et verrouillée pour l’appelant.

Une fois les informations du fichier utilisées, l’application doit appeler UnlockUrlCacheEntryFile pour déverrouiller le fichier.

Groupes de cache

Pour créer un groupe de cache, la fonction CreateUrlCacheGroup doit être appelée afin de générer un GROUPID pour le groupe de cache. Les entrées peuvent être ajoutées au groupe de cache en fournissant l’URL de l’entrée de cache et l’indicateur INTERNET_CACHE_GROUP_ADD à la fonction SetUrlCacheEntryGroup . Pour supprimer une entrée de cache d’un groupe, transmettez l’URL de l’entrée de cache et l’indicateur INTERNET_CACHE_GROUP_REMOVE à SetUrlCacheEntryGroup.

Les fonctions FindFirstUrlCacheEntryEx et FindNextUrlCacheEntryEx peuvent être utilisées pour énumérer les entrées dans un groupe de caches spécifié. Une fois l’énumération terminée, la fonction doit appeler FindCloseUrlCache.

Gestion des structures avec des informations de taille variable

Le cache peut contenir des informations de taille variable pour chaque URL stockée. Cela se reflète dans la structure INTERNET_CACHE_ENTRY_INFO . Lorsque les fonctions de cache retournent cette structure, elles créent une mémoire tampon qui est toujours de la taille de INTERNET_CACHE_ENTRY_INFO plus toutes les informations de taille variable. Si un membre de pointeur n’a pas la valeur NULL, il pointe vers la zone mémoire immédiatement après la structure. Lors de la copie de la mémoire tampon retournée par une fonction dans une autre mémoire tampon, les membres du pointeur doivent être fixés pour pointer vers l’emplacement approprié dans la nouvelle mémoire tampon, comme le montre l’exemple suivant.

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

Certaines fonctions de cache échouent avec le message d’erreur ERROR_INSUFFICIENT_BUFFER si vous spécifiez une mémoire tampon trop petite pour contenir les informations d’entrée de cache récupérées par la fonction. Dans ce cas, la fonction retourne également la taille requise de la mémoire tampon. Vous pouvez ensuite allouer une mémoire tampon de la taille appropriée et appeler à nouveau la fonction.