Initializing Connections with ADMIN_Initialize

This first initialization establishes connections for the DLL and informs the Administrator program of the available functions within the DLL. This initialization is performed by calling the ADMIN_Initialize function in the extension DLL.

Important This initialization is not the same as the one performed with the Win32 DLLMain function.

The function name must be ADMIN_Initialize (verbatim) and exported from the DLL. It is the only function that must be exported from the DLL. The Administrator program calls the function, passing two input parameters and one output parameter. Parameters passed include:

• ADMIN_AdministratorConnections * pAdminConnections Ιnput parameter. This structure gives information on connections, the MAPI session pointer, the Address Book pointer, and the Address Book container pointer.
• ADMIN_AdministratorFunction * pAdminFunctions Ιnput parameter. This structure is a list of function pointers in the Administrator program. The Administrator program is informing the DLL of a set of functions that it can use. For a list of functions provided by the Administrator program, see Using the Administrator Extension Functions.
• ADMIN_ExtensionFunction ** ppExtensionFunctions Output parameter. This structure contains pointers to functions. Your extension DLL must set its elements to point to functions that you support. For a list of functions you need to provide, see the information about DLL functions in Using the Administrator Extension Functions.

As a result of the ADMIN_Initialize function call, the Administrator program passes a MAPI Address Book interface pointer to the extension DLL. The extension DLL can use this pointer to display an address selection user interface or any other MAPI functionality implemented by the Address Book object. For example, your application might be a mailbox agent that can mail a daily status report to a certain recipient. By having a handle to the Address Book object, your extension DLL can support the ability to let an administrator select a destination for these messages.

If you plan to use any of the MAPI interface pointers contained in the ADMIN_AdministratorConnections structure, you will need to make a copy of these pointers and make a call to the interface's AddRef function. You must do this in your DLL's ADMIN_Initialize function. You need to copy only the pointers that you will be using. Remember to call the MAPI Release function for each pointer when you finish using it.

The ADMIN_Initialize function returns void, so any errors must be handled internally by your DLL. If a severe error occurs, the InitSheetProc call can return an error.

The following is an example of an ADMIN_Initialize function:

// $--ADMIN_Initialize()----------------------------------------------
// Exported function. This is the first function called by Admin after 
// the DLL has been initialized by Windows.
// -------------------------------------------------------------------

extern "C" VOID PASCAL ADMIN_Initialize(
    IN  ADMIN_AdministratorConnections* pAdminConnections,  
    IN  ADMIN_AdministratorFunction*    pAdminFunctions,    
    OUT ADMIN_ExtensionFunction**       ppExtensionFunctions)
{
    if( we want to use the MAPI session handle)
    {   // Keep a global copy of the MAPI session handle pointer.
        pMAPISession = pAdminConnections->psesMapi;
        pMAPISession->AddRef();
    }

    // Tell Admin where it can find the rest of our 
    // functions that it needs.
    *ppExtensionFunction = &extensionFunctions;  
}
// ---------------------------------------------------------------------