exadmin.h

vc6.0完整版

// -----------------------------------------------------------------------------
// ExAdmin.H: Declaration of the classes necessary to create an Exchange 
//            Administration Extension DLL.
//              
// NOTE:      When we refer to "admin" we mean the Exchange Administration program.
//
// Copyright 1986 - 1998 Microsoft Corporation.  All Rights Reserved.
// -----------------------------------------------------------------------------

#ifndef _EXADMIN_H_
#define _EXADMIN_H_

// -----------------------------------------------------------------------------

#include <mapix.h>
#include "retcode.h"
#include "adminext.h"

// -----------------------------------------------------------------------------
// NOTE: Your resource file MUST define these two control ids with these exact 
//       numbers.  If you don't you will get a compile time error telling you 
//       that you are redefining a macro.  Just go into your resource.h file and
//       change those definitions to these values.
// -----------------------------------------------------------------------------

#define IDC_ADMINICON                   1000
#define IDC_TITLE                       1001

// -----------------------------------------------------------------------------
// The following macros and the SInitPropValue structure give the user the 
// ability to easily create a property value array.  This is intended to make
// it easier to use the CAdminDialog::HrSetExtProps() function.
//
// See usage example that follows.
// -----------------------------------------------------------------------------

#define MAKE_PROP_VALUE( cnt, ptr) ((LONGLONG) ((((LONGLONG) ((ULONG) (ptr))) << 32) + ((LONGLONG) ((ULONG) (cnt)))))
#define BINARY_PROP_VALUE( bin)  MAKE_PROP_VALUE( sizeof( bin), &bin)
#define MULTI_VALUE_PROP( array) MAKE_PROP_VALUE( ARRAY_CNT( array), array)

typedef struct
{
    ULONG    ulPropTag;
    ULONG    dwAlignPad;
    LONGLONG ll;    
} SInitPropValue, *LPSInitPropValue;

//::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
// Usage example:
//::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
#ifdef  _USAGE_EXAMPLE_
#ifndef _USAGE_EXAMPLE_
    // Example of a binary structure that could be used by the property value array.
    typedef struct
    {
        CHAR    ch[20];
        LPSTR   lpsz;
        ULONG   ul;
        BOOL    flag;
    } ExampleStruct;

    // Example data that could go in the property value array.
    ExampleStruct BinData     = { "Binary Data", "A STRING", 3752789, TRUE};
    LONG          LongArray[] = { 92314535, 2231223, 111, 424242312};

    // The example property value array.
    static SInitPropValue ExtensionProps[] =
    {
        { PT_STRING8, 0, (ULONG)"Topic Folder"}, 
        { PT_LONG,    0, 0},      
        { PT_BOOLEAN, 0, FALSE},  
        { PT_BINARY,  0, BINARY_PROP_VALUE( BinData)},
        { PT_MV_LONG, 0, MULTI_VALUE_PROP( LongArray)},
    };
    
    // Somewhere in your OnInitDialog() function make the following call.
    hr = HrSetExtProps( ARRAY_CNT( ExtensionProps), ExtensionProps);
#endif
#endif

// -----------------------------------------------------------------------------
// This is called once per standard property sheet.  Not at all for our property
// sheets.  If you want to disable some or all of the standard property sheets 
// Then define this function in your code.  Your function will need to return 
// FALSE to disable a default property sheet.
// -----------------------------------------------------------------------------

BOOL PASCAL bShowPage( UINT iddAdminPage);

// -----------------------------------------------------------------------------
// This function is called once durring initialization.  Return -1 to cause the 
// first standard property sheet to be displayed.  Or return the index of one of 
// our property sheets to have it come up first.  The user can override this 
// function by simply defining their own function in their code.
// -----------------------------------------------------------------------------

INT PASCAL iStartPage( void);

// -----------------------------------------------------------------------------
// Class to initialize the DLL for both Windows and MFC.
// -----------------------------------------------------------------------------

class CInitDLL : public CWinApp
{
public:
    ~CInitDLL();
	virtual BOOL InitInstance(); // Initialization
	virtual int ExitInstance();  // Termination (WEP-like code)

	// Nothing special for the constructor.
	CInitDLL(LPCSTR pszAppName) : CWinApp(pszAppName) {}
};

// -----------------------------------------------------------------------------
// This dialog class allows easy subclassing of controls.
// -----------------------------------------------------------------------------

class CADialog : public CDialog
{
protected:    
    CADialog() : CDialog() {}   // Constructor.
    CADialog( LPCSTR lpszTemplateName, CWnd* pParentWnd = NULL) : CDialog( lpszTemplateName, pParentWnd) {}
    CADialog( UINT nIDTemplate, CWnd* pParentWnd = NULL) : CDialog( nIDTemplate, pParentWnd) {}

    // To make subclassing controls to CWnd derived objects easier.
    HRESULT HrSubclassWindow( 
        int   nID,  // Id of a control in this dialog.
        CWnd& Wnd); // Reference to MFC CWnd object to connect to Windows control.
};

// -----------------------------------------------------------------------------
// Derive your dialog class from this class to have it become an automatic
// property sheet of the Exchange Administration application.
//
// NOTE: In your derived dialog you MUST NOT release a MAPI interface in the 
//       destructor, this will cause a deadlock hang.  Use the OnDestroy() method
//       of the dialog to ULRELEASE() any MAPI Interface objects.
//
//       The problem is that the destructor does not get called until the DLL is
//       unloading.  This is a single threaded opperation in NT.  The ULRELEASE
//       process needs to run multi-threaded and waits INFINITELY for threads to
//       terminate.  The threads can't terminate until the DLL exits, and the DLL
//       can't exit until the threads terminate resulting in a deadlock.
// -----------------------------------------------------------------------------

class CAdminDialog : public CADialog
{
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
// You may find the following information useful for creating your dialog.
// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
protected:
    // Protected constructor insures that you must derive a class from CAdminDialog
    // in order to use it.  You may NOT instantiate directly from this class.
    //
    // To override the show page function you must pass in the pfnShowPage parameter.
    // Your function will be called once for each default property sheet and will 
    // receive an id of the sheet.  Your function must return TRUE if you want it 
    // to show.
    CAdminDialog( 
        UINT iddDialog,     // The resource ID of your dialog.
        UINT idsName,       // The resource ID of the string containing the name
                            // used by admin for the tab of your property sheet.
        LPSTR lpszBlobName = NULL);// Name of extension data blob.

    ~CAdminDialog();

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Functions to make displaying of message boxes easier. 
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    // If the caller does not pass in the lpszCaption then use the title of the 
    // parent window for the default title of our message box.
    int MessageBox( LPCSTR lpszText, LPCSTR lpszCaption = NULL, UINT nType = MB_OK);
    int MessageBox2( int IDText, int IDCaption = NULL, UINT nType = MB_OK);
    CString m_sMsgBoxCaption;   // This will contain the title of the parent window.

    // Displays a message box with a resource string for invalid entries.  After
    // the user presses OK the appropriate control gets focus.
    void InvalidEntry( int nResourceStrID, CWnd& wndCtrl);

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Use this function to create child dialog box templates.  It will ensure that 
    // the correct language and fonts are used.  Then use the CDialog::InitModalIndirect()
    // function to create the dialog
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

public:
    const HGLOBAL LoadDialogTemplate( UINT iddDialog);

    static int LoadStringA(UINT wID, LPSTR szBuf,  int cchBuf);
	static int LoadStringW(UINT wID, LPWSTR wzBuf, int cchBuf);

    // Free the template loaded with the above function.
    void FreeDialogTemplate( HGLOBAL* lphDlgTemplate)  { m_pAdminFunctions->pfnFreeDialogResource( (LPBYTE*) lphDlgTemplate);}

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Override these virtual functions in your derived class if you want them to do
    // something.
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
protected:    
    // Called when a different property sheet has been selected or when either the
    // OK or APPLY NOW button is pressed.  This saves the data to a memory buffer 
    // inside of admin.  Even if the user just switches to a different property sheet
    // this needs to be done so that other property sheets can read any changes that 
    // may have been made to the data.
    // Return TRUE if data has been validated and saved.  Default return is TRUE.
    virtual BOOL bSaveData();
    
    // Called when either the OK or APPLY NOW button is pressed and after bSaveData().
    // Return TRUE if data has been committed.  This saves the extension data and returns
    // TRUE if it was successful.
    virtual BOOL bCommitData();
    
    // Called so that your property sheet can refresh with data that may have been changed
    // by another property sheet.  You say you don't have more than one property sheet that
    // modifies the same data fields.  Ahh, but the Exchange SDK provides a sample that 
    // lets an Administrator view and modify any Exchange SDK packed extension data array.
    virtual void Refresh();

    // Called to determine if you supply help.  Return TRUE if you do, defaults to FALSE.
    virtual BOOL bHasHelp();
    
    // Called to start help.  Default does nothing.
    virtual VOID DoHelp();

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    
    // Call this to inform admin that the data has changed.
    void DataHasChanged() { m_pAdminFunctions->pfnInfoHasChanged( GetSafeHwnd());}

    // Get the count of extension data properties.
    ULONG GetExtCount() { return( m_cExtProps);}

    // Set the extension data properties to an existing property value array.  This
    // can be used to create a blob for the first time.  To do this initialized the
    // lpExtProps array with just property types and no real data.  Then use the 
    // CAdminDialog::HrMod...() functions to set the values.
    HRESULT HrSetExtProps(
        ULONG        cExtProps,     // Count of extension data properties.
        LPSPropValue lpExtProps);   // Array of properties to set extension data to.
    
    // Overloaded function to convert our property initialization structure to
    // the real MAPI property structure.  (This is temporary until MAPI changes
    // their _UPV union definition.)
    HRESULT HrSetExtProps(
        ULONG        cExtProps,     // Count of extension data properties.
        LPSInitPropValue lpExtProps)// Array of properties to set extension data to.
    {
        return( HrSetExtProps( cExtProps, (LPSPropValue) lpExtProps));
    }

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Functions to get extension data.
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    // Use this to get a binary extension data property.
    LPSBinary GetExtBinary(
        ULONG iProp);       // Index of property.

    // Use this to get a string extension data property.
    LPSTR GetExtString(
        ULONG iProp);       // Index of property.

    // Use this to get a long extension data property.
    LONG GetExtLong(
        ULONG iProp);       // Index of property.

    // Use this to get a double word extension data property.
    DWORD GetExtDWord(
        ULONG iProp)        // Index of property.
    {
        return( (DWORD) GetExtLong( iProp));
    }

    // Use this to get a boolean extension data property.
    BOOL GetExtBool(
        ULONG iProp);       // Index of property.

    // Use this to get a system time extension data property.
    FILETIME GetExtSysTime(
        ULONG iProp);       // Index of property.

    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    // Functions to modify extension data.
    // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

    // Use this to modify a binary extension data property.
    HRESULT HrModExtBinary(
        IN ULONG  iProp,    // Index of property
        IN ULONG  cb,       // Count of new data bytes.
        IN const LPBYTE lpNew);   // New data bytes.