TOPICS.H

// --Topics.h------------------------------------------------------------------- 
//  
// This module contains functions for maintaining and using a topic object for  
// SMBAGENT.  A topic has a folder, an introductory message, and a list of  
// subscribers.   
// 
// The list of subscribers are contained in the introductory  
// message as the "TO" recipient list.  The introductory message is contained in 
// the topic folder.  The topic folder is contained in a root topics folder. 
// 
// These functions all take as their first parameter a "THIS" pointer which is a 
// pointer to the instance of the STopic object to work with. 
// 
// 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 _TOPICS_H_ 
 
#ifdef THIS 
#undef THIS 
#endif 
#define THIS    // Defined to do nothing but comment a function parameter. 
 
#ifndef PROTECTED  
#define PROTECTED  
#endif 
 
//$--STopic--------------------------------------------------------------------- 
// The following structure contains a single item of the topic cache. 
// ----------------------------------------------------------------------------- 
 
typedef struct  
{ 
    ULONG           iTFolderArray;      // Index into folder row set of this folder. 
    ULONG           cUsageCnt;          // Number of times this topic was used while in the cache. 
    LPMAPIFOLDER    lpFolder;           // Ptr to open folder interface. 
    LPMESSAGE       lpIntroMsg;         // Ptr to open intro msg interface. 
    LPSRowSet       lpSubscriberRowSet; // Ptr to row set of subscribers. 
    LPSRow          lpCurSubscriber;    // Ptr to the current subscriber being accessed. 
    LPSRow          lpLastSubscriber;   // Ptr to the last subscriber that can be accessed. 
    LPMAPITABLE     lpSubTable;         // Ptr to subscriber table interface. 
} STopic; 
 
// ----------------------------------------------------------------------------- 
// Find the sender as a subscriber in the topic object and places its index or  
// NOT_FOUND in lpiSubscriber. 
// 
// RETURNS: HRESULT error only on failure. NOT_FOUND is NOT an error! 
// ----------------------------------------------------------------------------- 
 
HRESULT STopic_HrFindSubscriber( 
    THIS STopic* lpTopic,       // The topic object we are working on. 
    OUT ULONG*   lpiSubscriber);// Index of subscriber. 
 
// ----------------------------------------------------------------------------- 
// Subscriber row functions and macros. 
// ----------------------------------------------------------------------------- 
 
// RETURN the first subscriber's row of properties. 
LPSRow STopic_GetFirstSubscriber( THIS STopic* lpTopic); 
 
// RETURN the next subscriber's row of properties. 
LPSRow STopic_GetNextSubscriber( THIS STopic* lpTopic); 
 
// Indexes of subscriber properties. 
typedef enum 
{ 
    IDX_DISPLAY_NAME = 0, 
    IDX_ENTRYID,          
    IDX_ADDRTYPE,         
    IDX_EMAIL_ADDRESS,    
    IDX_RECIPIENT_TYPE,   
    IDX_ROWID,            
} SubscriberPropIndexes; 
 
#define GetDispName()   lpProps[IDX_DISPLAY_NAME].Value.LPSZ      // USAGE: lpsz = lpRow->GetDispName(); 
#define GetEmailAddr()  lpProps[IDX_EMAIL_ADDRESS].Value.LPSZ     // USAGE: lpsz = lpRow->GetEmailAddr(); 
 
// ----------------------------------------------------------------------------- 
// Modifies the list of subscribers in the intro message and in memory.  You  
// should use STopic_HrAddSubscriber() and not this function directly. 
// 
// NOTE: The Subscriber list will be invalid after this call. 
// ----------------------------------------------------------------------------- 
 
HRESULT STopic_HrModifySubscriberList( 
    THIS STopic*    lpTopic,    // The topic object we are working on. 
    IN   LPADRLIST  lpAdrList,  // The address list to add or remove. 
    IN   ULONG      ulFlags);   // MODRECIP_ADD or MODRECIP_REMOVE 
 
// Use this to add a subscriber. 
__inline HRESULT STopic_HrAddSubscriber( STopic* lpTopic, LPADRLIST lpAdrList) 
{ 
    return( STopic_HrModifySubscriberList( lpTopic, lpAdrList, MODRECIP_ADD)); 
} 
 
// ----------------------------------------------------------------------------- 
// Delete the subscriber from the recipient list of the Introductory message and 
// then free the subscriber list so that next time we work with this topic we 
// will get a fresh list with updated row ids. 
// ----------------------------------------------------------------------------- 
 
HRESULT STopic_HrDeleteSubscriber( 
    THIS STopic*    lpTopic,            // The topic object we are working on. 
    IN   ULONG      iSubscriber);       // The index of the subscriber to delete. 
 
//$--STopic_GetCopyOfSubscriberRowSet------------------------------------------- 
// Returns a copy of the subscriber's row set as andress list this MUST be freed 
// using FREEPROWS when the user is done with it. 
// ----------------------------------------------------------------------------- 
 
HRESULT STopic_GetCopyOfSubscriberRowSet(  
    THIS STopic*    lpTopic,    // The topic object we are working on. 
    OUT  LPADRLIST* lppAdrList);// Ptr to LPADRLIST that we will return. 
 
// ----------------------------------------------------------------------------- 
// The following are inline functions that opperate on the topic cache item. 
// ----------------------------------------------------------------------------- 
 
// Returns the topic folder's interface pointer. 
__inline LPMAPIFOLDER STopic_GetFolder( STopic* lpTopic) 
{ 
    return( lpTopic->lpFolder); 
} 
 
// Returns the topic introduction message interface pointer. 
__inline LPMESSAGE STopic_GetIntroMsg( STopic* lpTopic) 
{ 
    return( lpTopic->lpIntroMsg); 
} 
 
// Call this to set only the message interface pointer of a topic object 
// to the open introductory message. 
__inline void STopic_SetIntroMsg( STopic* lpTopic, LPMESSAGE lpIntroMsg) 
{ 
    lpTopic->lpIntroMsg = lpIntroMsg; 
} 
 
//  Returns the total number of subscribers to this topic. 
__inline ULONG STopic_GetSubscriberCount( STopic* lpTopic) 
{ 
    return( lpTopic->lpSubscriberRowSet->cRows); 
} 
 
// ----------------------------------------------------------------------------- 
// These functions are protected to be used only by STopicCache. 
// ----------------------------------------------------------------------------- 
 
#ifdef FRIEND_OF_STOPIC 
 
// Initialize a topic cache item, setting it to an empty state. 
PROTECTED void STopic_Init( THIS STopic* lpTopic); 
 
// Release and free any open interfaces or buffers in the topic cache object and 
// re-initialize to an empty state. 
PROTECTED void STopic_Release( THIS STopic* lpTopic); 
 
// ----------------------------------------------------------------------------- 
// Open all interface pointers and load the subscriber list for this topic cache  
// item.  Some things may already be opened or loaded while others may not. 
// ----------------------------------------------------------------------------- 
 
PROTECTED HRESULT STopic_HrOpen(  
    THIS   STopic*  lpTopic,        // The topic object we are working on. 
    IN     ULONG    iTFolderArray); // Index into folder array used to initialize this topic. 
 
// ----------------------------------------------------------------------------- 
// Protected inline functions. 
// ----------------------------------------------------------------------------- 
 
// Returns the index into TFolderArray of the folder for this topic. 
PROTECTED __inline ULONG STopic_GetFolderIndex( STopic* lpTopic) 
{ 
    return( lpTopic->iTFolderArray); 
} 
 
// Call this to set the index of the topic within the TFolderArray. 
PROTECTED __inline void STopic_SetFolderIndex( STopic* lpTopic, ULONG iTFolderArray) 
{ 
    lpTopic->iTFolderArray = iTFolderArray; 
} 
 
// Returns the cUsageCnt. 
PROTECTED __inline ULONG STopic_GetUsageCnt( STopic* lpTopic) 
{ 
    return( lpTopic->cUsageCnt); 
} 
 
// Call this to increment the cUsageCnt. 
PROTECTED __inline void STopic_IncUsageCnt( STopic* lpTopic) 
{ 
    lpTopic->cUsageCnt ++; 
} 
 
// Call this to decrement the cUsageCnt. 
PROTECTED __inline void STopic_DecUsageCnt( STopic* lpTopic) 
{ 
    lpTopic->cUsageCnt --; 
} 
 
// Call this to set both the folder index and folder interface  
// pointer of a topic object to an open folder interface. 
PROTECTED __inline void STopic_SetFolder( STopic* lpTopic, ULONG iTFolderArray, LPMAPIFOLDER lpFolder) 
{ 
    lpTopic->iTFolderArray = iTFolderArray; 
    lpTopic->lpFolder = lpFolder; 
} 
 
// This will free the subscriber row set causing it to be reloaded the next time 
// the topic is used. 
PROTECTED __inline void STopic_FreeSubscriberList( STopic* lpTopic) 
{ 
    FREEPROWS( lpTopic->lpSubscriberRowSet); 
} 
 
#endif // FRIEND_OF_STOPIC 
 
// ----------------------------------------------------------------------------- 
 
#endif // _TOPICS_H_