Installing the Administrator Extension DLL

To add property pages to a directory object, you install an Administrator extension DLL by adding and configuring an Admin-Extension object in the directory. You assign a name to this Administrator extension by setting its Extension-Name attribute. You may, for instance, set it to match the service name. The Administrator program builds a Common-Name attribute for the extension from the Extension-Name attribute and the hardware platform designation, in this way:

<extension-name>:<hardware-platform>

For example, you may assign the name GWSample to the Extension-Name attribute for a service called GWSample. If the platform is i386 (Intel), the Common-Name is set to GWSample:i386.

An Administrator extension DLL is associated with a directory object when the <extension-name> part of the Admin-Extension object's common name is written into the Extension-Name attribute of the directory object. The name of the extension DLL file is recorded in the Admin-Extension-DLL attribute of the Admin-Extension object.

Determining the Destination Directory for the Administrator Extension DLL

The installation program also must copy the new Administrator extension DLL into a subdirectory of the ADD-INS directory share, which is created when Microsoft Exchange Server is installed. This subdirectory is determined as follows:

\\SERVER\ADD-INS \<extension-name>\<hardware-platform>

Example: the MS Mail Connector

When the MS Mail Connector is installed, it creates an Admin-Extension directory object in the Add-Ins container, with the common name MS:i386. Through its Admin-Extension-DLL attribute, this object points to a DLL file called CONADMIN.DLL in the \\SERVER\ADD-INS\MS\I386 directory on the Server computer. The MS Mail Connector itself is represented by a directory object in the Connections container, whose Extension-Name attribute is set to the value MS.

Example: GWSample

For an Admin-Extension object whose Extension-Name attribute is GWSample, you would copy extension DLLs into one or more the following directories, depending on the platform:

You need both an Administrator extension DLL and a new Admin-Extension object for each supported platform. For this example, you would install the Admin-Extension objects for the i386 and MIPS platforms into the following locations in the DIT:

Example: Installation locations for Admin-Extension objects

The procedure for installing a new Administrator extension DLL is different than that for replacing an installed Administrator extension DLL with a newer version:

To install a new Administrator extension DLL

1. While the Administrator extension DLL is on the distribution media, get its file version. First, call the HrGetFileVersionInfo function. Then, extract the actual file version from the data returned by HrGetFileVersionInfo using functions such as the Win32 function VerQueryValue.
2. Copy the Administrator extension DLL into the appropriate directory for the platform.
3. Install the Admin-Extension object by calling the HrInstallAdminExtension function and passing the DLL file version. This call creates the Admin-Extension object in the directory and sets the following properties on it: Admin-Display-Name, Common-Name, Admin-Extension-DLL, File-Version.

To install a newer version of an existing Administrator extension DLL

1. While the Administrator extension DLL is on the distribution media, get its file version. First, call the HrGetFileVersionInfo function. Then, extract the actual file version from the data returned by HrGetFileVersionInfo using functions such as the Win32 function VerQueryValue.
2. If the installed version is newer than the one that the setup program would install, display a dialog box asking the administrator whether to copy the Administrator extension DLL from the distribution media onto the server. If the answer is no, end the setup procedure for this Admin-Extension object. If the answer is yes, continue with the following steps.
3. Use the HrAdminExtensionExists function to determine whether an Administrator extension with the same name is already installed. If so, remove it using the function HrRemoveAdminExtension.
4. Delete the existing Administrator extension DLL by using the following steps. This procedure is necessary to ensure deletion of an Administrator extension DLL that may be in use. The steps in this example assume that your existing Administrator extension DLL is named AE.DLL.
   • Ensure that no file with a backup name from a previous attempted installation exists. In this example, delete AE.DLL.BAK.
   • Rename the existing extension DLL by giving it the extension .BAK. For example, if your extension DLL is called AE.DLL, rename it to AE.DLL.BAK.
   • Delete the file with the backup name. In this case, delete AE.DLL.BAK.
5. Copy the new Administrator extension DLL into the appropriate directory for the platform.
6. Install the Admin-Extension object by calling the HrInstallAdminExtension function and passing the DLL file version. This call creates the Admin-Extension object in the directory and sets the following properties on it: Admin-Display-Name, Common-Name, Admin-Extension-Dll, File-Version.

The following sample code is from the GWSETUP.C file in the directory \SAMPLES\DbMsg\EXCHANGE\GWSETUP. It performs several of the steps needed to install an Administrator extension DLL.

//$--DoInstall----------------------------------------------------------
//  Install the application.
// --------------------------------------------------------------------
void DoInstall(                         // RETURNS: nothing
    void)                               // no arguments
{
    //
    // Check if admin extension object exists
    //

    sprintf(szLocalExtensionDll,  "%s\\%s", szSourcePath,  EXTENSION_DLL);
    sprintf(szRemoteExtensionDll, "%s\\%s", szExtnDestDir, EXTENSION_DLL);
    sprintf(szBackupExtensionDll, "%s.bak", EXTENSION_DLL);
    sprintf(szRemoveExtensionDll, "%s\\%s.bak", szExtnDestDir, EXTENSION_DLL);

    hr = HrVerifyAdminExtensionVersion(        szLocalExtensionDll,
        szServer,
        szSite,
        ADD_INS_TYPE,
        MACHINE_TYPE,
        &dwExtnVersionMS,
        &dwExtnVersionLS,
        &fInstallAdminExt,
        &fDeleteAdminExt);

    //
    // Remove admin extension object
    //

    if((fInstallAdminExt == TRUE) && (fDeleteAdminExt == TRUE))
    {
        hr = HrRemoveAdminExtension(
            szServer,
            szSite,
            ADD_INS_TYPE,
            MACHINE_TYPE);

        RemoveFile(szRemoveExtensionDll, cmoForce);
        RenameFile(szRemoteExtensionDll, szBackupExtensionDll);
        RemoveFile(szRemoveExtensionDll, cmoForce);
    }

    //
    // Add server files to copy list
    //

    ClearCopyList();

    if(fInstallAdminExt == TRUE)
    {
        AddSectionFilesToCopyList(SECTION_EXTENSION, szSourcePath, szExtnDestDir);
    }

    if(fInstallAddrType == TRUE)
    {
        AddSectionFilesToCopyList(SECTION_ADDRESS,   szSourcePath, szAddrDestDir);
    }

    //
    // Copy server files
    //

    if((fInstallAdminExt == TRUE) || (fInstallAddrType == TRUE))
    {
        CopyFilesInCopyList();
    }

    //
    // Install admin extension object
    //

    if(fInstallAdminExt == TRUE)
    {
        hr = HrInstallAdminExtension(
            szServer,
            szSite,
            ADD_INS_DISPLAY_NAME,
            ADD_INS_TYPE,
            dwExtnVersionMS,
            dwExtnVersionLS,
            EXTENSION_DLL,
            MACHINE_TYPE);

    }
}