TFLDRARY.H

// --TFldrAry.h---------------------------------------------------------------- 
//  
// This module contains functions for maintaining and using a topic folder  
// array for SMBAGENT. 
// 
// The array is essentialy a dynamicly expanding row set of properties of all  
// topic folders.  Each row contains a Display Name and an Entry Id.  The array  
// is sorted by display name. 
// 
// 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 _TFLDRARY_H_ 
#define _TFLDRARY_H_ 
 
#ifndef PROTECTED 
#define PROTECTED  
#endif 
 
//$--STFolderArray-------------------------------------------------------------- 
// Topic folder array structure.  There will be only one instance of this object. 
// ----------------------------------------------------------------------------- 
 
typedef struct 
{ 
    ULONG       cAllocatedRows;   // Count of actual number of slots in lpRows->aRow[]. 
    LPSRowSet   lpRows;     // MAPI allocated buffer. 
} STFolderArray; 
 
#define NOT_FOUND (ULONG) ~0L   // Index when something is not found. 
 
// Do NOT use this directly, use the helper or inline functions listed below. 
extern STFolderArray TFolderArray; 
 
// ----------------------------------------------------------------------------- 
// This MUST be called only once at the begining before using the topic folders 
// or the topic cache functions.  Be sure to use STFolderArray_Destroy() when 
// done with the array. 
// 
// Initialize the global topic folder array by filling it with the display name  
// and entry id of all folders under the topics folder. 
// ----------------------------------------------------------------------------- 
 
HRESULT STFolderArray_HrInit(); 
 
// ----------------------------------------------------------------------------- 
// Find a topic folder in the global topic folder array. 
// RETURNS: The index of the topic or NOT_FOUND. 
// ----------------------------------------------------------------------------- 
 
ULONG STFolderArray_Find(  
    IN LPTSTR lpszTFolderName);    // The name of the topic folder you want to find. 
 
// ----------------------------------------------------------------------------- 
// Create a new topic folder and insert into the array so that the array remains 
// sorted by PR_DISPLAY_NAME and we keep the entry id.  This will also place 
// this folder in the topic cache with just the folder open. 
// 
// OUTPUT:  lppNewFolder    Open folder interface ptr.  Do NOT release this. 
//          lppTopic        Open Topic cache object pointer. 
// ----------------------------------------------------------------------------- 
 
HRESULT STFolderArray_HrCreateFolder(  
    IN  LPTSTR          lpszTFolderName,    // The name of the topic folder you want to create. 
    OUT LPMAPIFOLDER*   lppNewFolder,       // Open folder interface ptr. 
    OUT STopic**        lppTopic);          // Open Topic cache object pointer. 
 
// ----------------------------------------------------------------------------- 
// Deletes a topic folder from the MAPI store and the TFolderArray. This also  
// removes it from the topic cache and adjusts the indexed references to this array. 
// 
// NOTE: Use STFolderArray_HrDeleteFolderSZ() if you only have the topic folder  
//       name and not the index. 
// ----------------------------------------------------------------------------- 
 
HRESULT STFolderArray_HrDeleteFolder( 
    IN ULONG iTFolderArray);     // Index of folder to be deleted. 
 
// ----------------------------------------------------------------------------- 
// Topic folder array inline supporting "member" functions.  Since there is only  
// one topic folder array we don't pass in a "this" type of pointer. 
// ----------------------------------------------------------------------------- 
 
// Free the global topic folder array. 
__inline void STFolderArray_Destroy() 
{ 
    FREEPROWS( TFolderArray.lpRows); 
    TFolderArray.cAllocatedRows = 0; 
} 
 
// Delete the topic folder taking the name of the folder as a string. 
__inline HRESULT STFolderArray_HrDeleteFolderSZ( LPTSTR lpszTFolderName) 
{ 
    return( STFolderArray_HrDeleteFolder( STFolderArray_Find( lpszTFolderName))); 
} 
 
// Return a count of the topic folders in the global topic folder array. 
__inline ULONG STFolderArray_GetCount() 
{ 
    return( TFolderArray.lpRows->cRows); 
} 
 
// Return the name of a topic folder based on its index. 
__inline LPTSTR STFolderArray_GetName( ULONG iTFolderArray) 
{ 
    if( iTFolderArray >= STFolderArray_GetCount()) 
        return( NULL); 
    return( TFolderArray.lpRows->aRow[ iTFolderArray].lpProps[0].Value.LPSZ); 
} 
 
// ----------------------------------------------------------------------------- 
// Used only by the STopicCache and STopic objects. 
// ----------------------------------------------------------------------------- 
 
#ifdef FRIEND_OF_STFOLDERARRAY 
 
// Return the count of bytes of the entry id of a topic folder based on its index. 
PROTECTED __inline ULONG STFolderArray_GetCbEID( ULONG iTFolderArray) 
{ 
    if( iTFolderArray >= STFolderArray_GetCount()) 
        return( 0); 
    return( TFolderArray.lpRows->aRow[ iTFolderArray].lpProps[1].Value.bin.cb); 
} 
 
// Return the entry id of a topic folder based on its index. 
PROTECTED __inline LPENTRYID STFolderArray_GetEID( ULONG iTFolderArray) 
{ 
    if( iTFolderArray >= STFolderArray_GetCount()) 
        return( 0); 
    return( (LPENTRYID) TFolderArray.lpRows->aRow[ iTFolderArray].lpProps[1].Value.bin.lpb); 
} 
 
// Inline function to simplify deleting a topic folder. 
PROTECTED __inline HRESULT HrDeleteTopicFolder( ULONG cbEID, LPENTRYID lpEID) 
{ 
    return( MAPICALL( lpTopicsFolder)->DeleteFolder( lpTopicsFolder, cbEID, lpEID,  
            0, NULL, DEL_MESSAGES | DEL_FOLDERS));  
} 
 
// ----------------------------------------------------------------------------- 
// Used by search routines to compare a search key to the display name which is 
// the first property of a row in a SRowSet. 
// 
// This helper function is globaly available. 
// RETURNS: -1 if Search Key < Display Name 
//           0 if Search Key = Display Name 
//           1 if Search Key > Display Name 
// ----------------------------------------------------------------------------- 
 
PROTECTED int Compare_DispName( const void* lpszSrchKey, const void* lpRow); 
 
#endif // FRIEND_OF_STFOLDERARRAY 
 
// ----------------------------------------------------------------------------- 
 
#endif  //_TFLDRARY_H_