Tricks of the Windows Gam…ming Gurus (2nd Edition)/Disc2.iso/vc98/include/edkcfg.h

C/C++ Source or Header | 1998-04-25 | 9.6 KB | 202 lines

// --edkcfg.h-------------------------------------------------------------------
//
//  EDK Gateway Configuration Routines
//
// Copyright 1986 - 1998 Microsoft Corporation.  All Rights Reserved.
//
// -----------------------------------------------------------------------------

#ifndef _EDKCFG_H_
#define _EDKCFG_H_

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

//
// Type Definitions
//

//$--ADVISECALLBACK-------------------------------------------------------------
//  Function type for routine to be called when a binary blob changes.
// -----------------------------------------------------------------------------
typedef HRESULT (ADVISECALLBACK) (
    LPVOID              lpvUserContext,
    LPWSTR              lpwszOwnerTag,
    ULONG               cProps,
    LPSPropValue        lpProps);

typedef ADVISECALLBACK *LPADVISECALLBACK;

//$--ADVISENOTIFY---------------------------------------------------------------
//  Object attached to an ADVISEOBJ, which represents a single blob and the
//  callback routine to call when it is modified.
// -----------------------------------------------------------------------------
typedef struct _AdviseNotify {
    struct _AdviseNotify * lpNext;
    LPSTR              lpszOwnerTag;
    LPWSTR              lpwszOwnerTag;
    LPBYTE              lpbBlob;
    ULONG               cbBlob;
    LPADVISECALLBACK    lpfnCallback;
    LPVOID              lpvUserContext;
    BOOL                fFirstTime;
} ADVISENOTIFY, *LPADVISENOTIFY;

//$--ADVISEOBJ------------------------------------------------------------------
//  Object representing a MAPI session whose extension data is being monitored.
// -----------------------------------------------------------------------------
typedef struct {
    LPMAPISESSION       lpSession;
    LPMAPIPROP          lpCurrentObject;
    ULONG               nPollInterval;
    ULONG               ulUSNChangedPropTag;
    ULONG               ulExtensionDataPropTag;
    CRITICAL_SECTION    csCriticalSection;
    HANDLE              hPollThreadStop;
    HANDLE              hPollThread;
    ULONG               ulPollThreadID;
    ULONG               ulUSNChanged;
    LPSPropValue        lpExtensionData;
    LPADVISENOTIFY      lpNotifyList;
} ADVISEOBJ, *LPADVISEOBJ;

//
// Function Prototypes
//

//$--HrCfgCreateAdviseObj-------------------------------------------------------
//  Begin monitoring of a MAPI session for changes to extension data.
//  This routine should be called once to create an advise object for a MAPI
//  session that is being monitored.  Then, HrCfgAdvise() should be called
//  once for each extension data section that is being monitored.
//  If nPollInterval == 0 then no monitoring thread is created, and the user
//  must do polling manually by calling HrCfgPollAdviseObj().
// -----------------------------------------------------------------------------
HRESULT HrCfgCreateAdviseObj(               // RETURNS: HRESULT
    IN  LPMAPISESSION       lpSession,      // MAPI session to monitor
    IN  ULONG               nPollInterval,  // milliseconds between polling
    OUT LPADVISEOBJ *       lppAdviseObj);  // created advise object

//$--HrCfgPollAdviseObj---------------------------------------------------------
//  Checks an advise object against what is stored in the DSA.  Calls the
//  notification routines if there are any changes.
// -----------------------------------------------------------------------------
HRESULT HrCfgPollAdviseObj(                 // RETURNS: HRESULT
    IN  LPADVISEOBJ     lpAdviseObj);       // advise object to poll

//$--HrCfgDestroyAdviseObj------------------------------------------------------
//  End monitoring of a MAPI session.  This routine calls HrCfgUnadvise() for
//  any extension data sections that are actively being monitored.
// -----------------------------------------------------------------------------
HRESULT HrCfgDestroyAdviseObj(              // RETURNS: HRESULT
    IN  LPADVISEOBJ         lpAdviseObj);   // advise object to destroy

//$--HrCfgAdvise----------------------------------------------------------------
//  Begin monitoring of an extension data section.  When the extension data
//  changes, the specified callback routine is called.  Note: The callback
//  routine will be called once from hrCfgAdvise() to set the initial extension
//  data values.
// -----------------------------------------------------------------------------
HRESULT HrCfgAdvise(                        // RETURNS: HRESULT
    IN  LPADVISEOBJ         lpAdviseObj,    // advise object
    IN  LPSTR               lpszSection,    // name of extension data section
    IN  LPADVISECALLBACK    lpfnCallback,   // function to call on changes
    IN  LPVOID              lpvUserContext); // user-defined context

//$--HrCfgUnadvise--------------------------------------------------------------
//  End monitoring of an extension data section.
// -----------------------------------------------------------------------------
HRESULT HrCfgUnadvise(                      // RETURNS: HRESULT
    IN  LPADVISEOBJ         lpAdviseObj,    // advise object
    IN  LPSTR               lpszSection);   // name of extension data section

//$--HrCfgPackData--------------------------------------------------------------
//  Take a configuration name and a set of MAPI properties and pack them into
//  a binary buffer suitable to be saved in the directory information tree for
//  the gateway or other object.
// -----------------------------------------------------------------------------
HRESULT HrCfgPackDataA(                        // RETURN: HRESULT
    IN    LPSTR            lpszOwnerTag,        // name of configuration (or NULL)
    IN    ULONG            cProps,                // number of MAPI properties
    IN    LPSPropValue    lpProps,            // MAPI properties for this config.
    OUT    ULONG *            lpcbConfigData,        // size of resulting binary struct.
    OUT    LPBYTE *        lppbConfigData);    // resulting binary structure

HRESULT HrCfgPackDataW(                        // RETURN: HRESULT
    IN    LPWSTR            lpwszOwnerTag,        // name of configuration (or NULL)
    IN    ULONG            cProps,                // number of MAPI properties
    IN    LPSPropValue    lpProps,            // MAPI properties for this config.
    OUT    ULONG *            lpcbConfigData,        // size of resulting binary struct.
    OUT    LPBYTE *        lppbConfigData);    // resulting binary structure

#ifdef UNICODE
#define HrCfgPackData HrCfgPackDataW
#else
#define HrCfgPackData HrCfgPackDataA
#endif

//$--HrCfgUnpackData------------------------------------------------------------
//  Take a packed binary buffer and unpack it to yield a configuration name,
//  number of properties, and an array of MAPI properties.  If the number of
//  properties is zero then NULL is returned for the array of properties.
// -----------------------------------------------------------------------------
HRESULT HrCfgUnpackDataA(                    // RETURNS: HRESULT
    IN    ULONG            cbConfigData,        // size of of binary structure
    IN    LPBYTE            lpbConfigData,        // pointer to binary structure
    OUT    LPSTR *            lppszOwnerTag,      // name of configuration (or NULL)
    OUT    ULONG *            lpcProps,            // number of MAPI properties
    OUT    LPSPropValue *    lppProps);            // MAPI properties for this config.

HRESULT HrCfgUnpackDataW(                    // RETURNS: HRESULT
    IN    ULONG            cbConfigData,        // size of of binary structure
    IN    LPBYTE            lpbConfigData,        // pointer to binary structure
    OUT    LPWSTR *        lppwszOwnerTag,     // name of configuration (or NULL)
    OUT    ULONG *            lpcProps,            // number of MAPI properties
    OUT    LPSPropValue *    lppProps);            // MAPI properties for this config.

#ifdef UNICODE
#define HrCfgUnpackData HrCfgUnpackDataW
#else
#define HrCfgUnpackData HrCfgUnpackDataA
#endif

//$--HrOpenSiteContainer-----------------------------------------------------------------
//  Takes a pointer to a MAPI session and returns an IMAPIProp interface for
//  the current site object.
// -----------------------------------------------------------------------------
HRESULT HrOpenSiteContainer(                            // RETURNS: HRESULT
    IN    LPMAPISESSION    lpSession,            // MAPI session
    OUT    LPMAPIPROP *    lppSite);           // current site

//$--HrOpenSiteContainerAddressing-------------------------------------------------------
//  Takes a pointer to a MAPI session and returns an IMAPIProp interface for
//  the current site addressing object.
// -----------------------------------------------------------------------------
HRESULT HrOpenSiteContainerAddressing(               // RETURNS: HRESULT
    IN    LPMAPISESSION    lpSession,          // MAPI session
    OUT    LPMAPIPROP *    lppSiteAddressing); // current site addressing

//$--HrOpenSessionObject--------------------------------------------------------
//  Takes a pointer to a MAPI session and returns an IMAPIProp interface for
//  the current object that the session is logged in as.
// -----------------------------------------------------------------------------
HRESULT HrOpenSessionObject(                // RETURNS: HRESULT
    IN    LPMAPISESSION    lpSession,            // MAPI session
    OUT    LPMAPIPROP *    lppCurrentObject);    // current object

//$--HrCfgPropertyTagFromNameId----------------------------------------------------
//  Takes a pointer to an IMAPIProp interface and a name ID, and returns the
//  MAPI property tag that represents the given name ID for that interface.
// -----------------------------------------------------------------------------
HRESULT HrCfgPropertyTagFromNameId(            // RETURNS: HRESULT
    IN    LPMAPIPROP        lpMAPIProp,            // IMAPIProp interface
    IN  LONG            lNameID,            // Name ID
    OUT    ULONG *            lpulPropTag);        // MAPI property tag of name ID

#ifdef __cplusplus
}
#endif

#endif