ActiveX Controls: Distributing ActiveX Controls

|  Overview |  How Do I |  FAQ |  |  Sample

This article discusses several issues related to redistributing ActiveX controls:

• ANSI or Unicode control versions

• Installing the control and its components

• Registering the ActiveX Control

• List of redistributable files

ANSI or Unicode Control Versions

You must decide whether to ship an ANSI or Unicode version of the control, or both. This decision is based on portability factors inherent in ANSI and Unicode character sets.

ANSI controls, which work on all Win32 operating systems, allow for maximum portability between the various Win32 operating systems. Unicode controls work on only Windows NT (version 3.51 or later), but not on Windows 95. If portability is your primary concern, ship ANSI controls. If your controls will run only on Windows NT, you can ship Unicode controls. You could also choose to ship both and have your application install the version most appropriate for the user’s operating system.

Installing ActiveX Controls and Redistributable DLLs

The setup program you provide with your ActiveX controls should create a special subdirectory of the Windows directory and install the controls’ .OCX files in it.

Tip   Use the Windows GetWindowsDirectory API in your setup program to obtain the name of the Windows directory.

You may want to derive the subdirectory name from the name of your company or product.

The setup program must install the necessary redistributable DLL files in the Windows system directory. If any of the DLLs are already present on the user's machine, the setup program should compare their versions with the versions you are installing. Reinstall a file only if its version number is higher than the file already installed.

Because ActiveX controls can be used only in OLE container applications, there is no need to distribute the full set of OLE DLLs with your controls. You can assume that the containing application (or the operating system itself) has the standard OLE DLLs installed.

Registering Controls

Before a control can be used, appropriate entries must be created for it in the Windows registration database. Some ActiveX control containers provide a menu item for users to register new controls, but this feature may not be available in all containers. Therefore, you may want your setup program to register the controls when they are installed. Visual C++ includes a redistributable program, RegSvr32.exe, which can be used to register controls. Just pass the complete path and filename of the control .OCX file as an argument to RegSvr32. The MFC ActiveX controls sample provides the source code for RegSvr32.EXE. This sample illustrates one method for performing the registration task and can be used as a guide to writing your own registration routine.

If you prefer, you can write your setup program to register the control directly instead.

Use the LoadLibrary Windows API to load the control DLL. Next, use GetProcAddress to obtain the address of the “DllRegisterServer” function. Finally, call the DllRegisterServer function. The following code sample demonstrates one possible method, where hLib stores the handle of the control library, and lpDllEntryPoint stores the address of the “DllRegisterServer” function.

HINSTANCE hLib = LoadLibrary(pszDllName);

if (hLib < (HINSTANCE)HINSTANCE_ERROR)
{
 DisplayMessage(IDS_LOADLIBFAILED, pszDllName); //unable to load DLL
 iReturn = FAIL_LOAD;                   //unable to load DLL
}

// Find the entry point.
(FARPROC&)lpDllEntryPoint = GetProcAddress(hLib,
   _T(“DllRegisterServer”));
if (lpDllEntryPoint != NULL)
 (*lpDllEntryPoint)();
else
   //unable to locate entry point

The advantage of registering the control directly is that you don’t need to invoke and load a separate process (namely, REGSVR32), reducing installation time. In addition, because registration is an internal process, the setup program can handle errors and unforeseen situations better than an external process can.

Note   Before your setup program installs an ActiveX control, it should call OleInitialize. When your setup program is finished, call OleUnitialize. This ensures that the OLE system DLLs are in the proper state for registering an ActiveX control.

When you install and register a control, you should also register OLEPRO32.DLL if you are using Microsoft Windows 95 (or OLEAUT32.DLL if you are using Microsoft Windows NT 4.0 or later). Use the same procedure for registering this DLL as you did for your .OCX file. Perform this registration step only if you need to install OLEPRO32.DLL or OLEAUT32.DLL. If the DLL is installed already, you should assume that it has been registered.

If your control uses one of the stock property pages, you should also register MFCx0.DLL. Unlike OLEPRO32.DLL or OLEAUT32.DLL, you should always register this DLL, even if it is already installed.

List of Redistributable Files

This section lists the files you may redistribute with your ActiveX control. The conditions under which you may or may not redistribute these files are described in the License Agreement included in the product. Visual C++ Setup may install some of these files on your development machine, depending on the options you chose during Setup. When you redistribute any of these files, copy them from the Visual C++ CD to your distribution medium. This ensures that you are redistributing the correct version of the files. The following table lists files that must be redistributed with your ActiveX control.

Redistributable Files