TOPCACHE.H

// --TopCache.H---------------------------------------------------------------- 
//  
// This module contains functions for maintaining and using a topic cache for  
// SMBAGENT. 
// 
// The cache is essentialy a fixed size array of open topic objects.  The first 
// slot in the cache contains the most recently used topic and the last contains 
// the oldest topic.   
// 
// Each topic item contains a count of the times it was used while in the cache.   
// It also contains an index into the STFolderArray of the folder this topic 
// belongs to.  This index is used to determine if a topic folder is in the  
// cache.  The index is adjusted when an item is inserted or deleted in the  
// STFolderArray. 
// 
// The cache has a DROP ZONE, which is at the end of the cache.  Both the size 
// of the cache and the drop zone are adjustable by the user.  The drop zone is 
// the area of the cache in which items are available for removal.  All slots 
// above the drop zone are safe from being removed, thus giving them some time 
// to accumulate a usage count. 
// 
// To decide which item to remove from the cache we start at the drop zone  
// index and search to the end for the slot whose item has had the least use. 
// If more than one item has the same low usage count then the one with the  
// highest index will be choosen. 
// 
// When the cache is full the last item in the cache will have it's usage count 
// decremented each time the cache is used.  This prevents an item that got a  
// burst of activity, accumulating a high usage count, and then was never used 
// again from remaining in the cache forever. 
// 
// The reason for a drop zone, as opposed to always tossing out the last item,  
// is to give those items that are used a lot, but not always with in the time 
// it takes to move from the top to the bottom of the cache, a chance to stick 
// around long enough to get used again. 
// 
// NOTE: If you want the cache to always toss out the last item set the drop  
//       zone index to the maximum cache size minus one. 
// 
// See TOPCACHE.H for details on the relationship between the STFolderArray, the 
// STopicCache, and the STopic objects. 
// 
// Copyright (C) Microsoft Corp. 1986-1996.  All Rights Reserved. 
// ----------------------------------------------------------------------------- 
 
#ifndef _TOPCACHE_H_ 
#define _TOPCACHE_H_ 
 
#ifndef PROTECTED 
#define PROTECTED  
#endif 
 
//$--STopicCache---------------------------------------------------------------- 
// Topic cache structure.  There will be only one instance of this object. 
// ----------------------------------------------------------------------------- 
 
typedef struct 
{ 
    ULONG   cMaxItems;      // Maximum items cache will hold. 
    ULONG   cTotItems;      // Total items currently in the cache. 
    ULONG   iDropZone;      // The starting index at which items become available  
                            // for removal from the cache.                         
    STopic* lpTopicArray;   // The actual cache array. 
} STopicCache; 
 
// ----------------------------------------------------------------------------- 
// Initialize the topic cache to an empty state. 
// ----------------------------------------------------------------------------- 
 
HRESULT STopicCache_HrInit( 
    IN  ULONG   cMaxTopics, // The maximum number of topics the cache will hold. 
    IN  ULONG   iDropZone); // The starting index at which items become available 
                            // for removal from the cache. 
 
// Release all topic items. 
void STopicCache_ReleaseAll(); 
 
// ----------------------------------------------------------------------------- 
// This function gets the topic associated with the folder specified by the 
// iTFolderArray index.  If the topic is in the cache it moves it to the top and  
// then returns it, otherwise it performs all the operations necessary to open  
// the topic. 
// 
// NOTE: The data pointed to by the returned pointer will be different once this  
//       function is called again for a new pointer.  In this implementation 
//       it will always return a pointer to the first slot in the cache, but 
//       don't depend upon it since the implementation could change. 
// 
// RETURNS: a pointer to the STopic object. 
// ----------------------------------------------------------------------------- 
 
HRESULT STopicCache_HrGetTopic( 
    IN  ULONG       iTFolderArray,  // Index into TFolderArray of topic we want. 
    OUT STopic**    lppTopic);       // We return the topic ptr in this var. 
 
 
#ifdef FRIEND_OF_STOPICCACHE 
 
// ----------------------------------------------------------------------------- 
// Frees the first slot in the cache to be used for a new topic. 
// RETURNS: a pointer to the first slot in the cache. 
// ----------------------------------------------------------------------------- 
 
PROTECTED STopic* STopicCache_FreeFirstTopicSlot(); 
 
// ----------------------------------------------------------------------------- 
// Adjust the index of all topic objects that contain an index that is greater 
// than or equal to iTFolderArray.  This is used when a new folder in inserted 
// into or deleted from the middle of the folder array. 
// ----------------------------------------------------------------------------- 
 
PROTECTED void STopicCache_AdjustIndex( 
    IN  ULONG       iTFolderArray,  // Index into TFolderArray of topic we want. 
    IN  int         nAddSub);        // +1 indicates insert and -1 delete folder. 
 
// ----------------------------------------------------------------------------- 
// Remove the item from the cache and adjust the index in the topic cache that  
// references any index >= iTFolderArray. 
// ----------------------------------------------------------------------------- 
 
PROTECTED void STopicCache_DeleteTopic( 
    IN  ULONG       iTFolderArray);  // Index into TFolderArray of topic we want to delete. 
 
// ----------------------------------------------------------------------------- 
// Free the first topic cache slot and place just the folder interface ptr in the slot. 
// ----------------------------------------------------------------------------- 
 
PROTECTED __inline void STopicCache_SetTopicFolder( 
    IN  ULONG           iTFolderArray, // Index into TFolderArray of topic we want. 
    IN  LPMAPIFOLDER    lpNewFolder,   // An already open folder interface ptr. 
    OUT STopic**        lppTopic)      // We return the topic ptr in this var. 
{ 
    *lppTopic = STopicCache_FreeFirstTopicSlot(); 
    STopic_SetFolder( *lppTopic, iTFolderArray, lpNewFolder); 
} 
 
// ----------------------------------------------------------------------------- 
 
#endif //FRIEND_OF_STOPICCACHE 
// ----------------------------------------------------------------------------- 
 
#endif // _TOPCACHE_H_