Initializing Property Pages with InitSheetProc

The purpose of the second initialization is to inform the Microsoft Exchange Server Administrator program about the property pages supported by the Administrator extension DLL. The Administrator program calls the InitSheetProc function, which is implemented by the extension DLL, and passes five parameters to the DLL:

• ADMIN_ObjectInfo * poi Input parameter. This structure contains information about the object for which the property page is being displayed. It gives the name of the computer on which the application is running, the distinguished name (DN) of the object being administered, and the DNs of the home server running the Microsoft Exchange Server information store and the home server running the message transfer agent (MTA).

  The ADMIN_ObjectInfo structure contains the field uObjectID. This field contains an object identifier code that specifies the object type whose property sheet is being displayed. If the extension DLL does not support the object type at this point, it should fail to initialize. The property pages provided by the Administrator program will still display, but not the property that the extension DLL would have displayed. The ADMINEXT.H file contains the object identifier codes to which the uObjectID field can be set.

• ULONG fFlags Input parameter. One flag is possible here: fxfReadOnly. The top eight bits of this ULONG can be used by the extension DLL for any purpose. The Administrator program guarantees them to be zero. For example, this parameter is used by an extension DLL that can also be run by another program such as a test application.

  If the fxfReadOnly flag is set, the extension DLL must ensure that it does not expose any functions that would change the directory object. DLL access privileges to other resources such as the Windows NT Registry might also be read-only.

• ADMIN_SheetInfo ** ppsi Output parameter. The DLL must create an array of ADMIN_SheetInfo structures — one element for each property page you're adding to the dialog box. The structure contains the following members:
• hinstance The instance of the DLL. It is the same in each array element.
• iddDialog The resource identifier of the dialog box.
• lpfnDlgProc A pointer to a Windows dialog procedure function. This points to a function in your DLL that processes all windows messages for this dialog box.
• idsName Identifier for a resource string. This gives the administrator the option of changing the property page name on the fly, using a resource editor.
• lParam Any information may be placed in this parameter that fits into four bytes. Later, it is passed to the Windows dialog procedure function when the WM_INITDIALOG message occurs (once per dialog box). For example, you can use this to point to a C++ object that will manage the dialog box.
• UINT * pcsi Output parameter. The number of property pages.
• VOID ** ppvExtensionData Output parameter that can be used for any data you want maintained and passed back to other functions in the interface.

Because the Administrator program knows the resource identifier of the dialog box after these initializations have been performed, it now calls the Windows CreateDialog function for each custom property page. After that function call, the extension DLL receives Windows messages. The Administrator program makes this call only if the tab for the custom property page is selected. If the user never looks at your property page, the Windows dialog procedure is not called.

The Administrator program displays the dialog box that contains extension property pages, but the functions that handle Windows messages to the dialog box are located in the extension DLL. The Administrator program will also communicate with your dialog box by calling the functions that you returned in the ADMIN_Initialize function.

If an error occurs during initialization, returning FALSE causes the Administrator program to display an error message to the user and not display the property pages for the object. If your DLL failed, you may still want to return TRUE and display a reduced (possibly zero) number of custom property pages.

For a list of functions that the DLL passes back to the Administrator program, see Using Administrator Extension Functions (Called by Administrator Program).