A Complete ActiveX Web Control Tutorial

Figure 5. ActiveX Control Pad – Insert ActiveX Control

Two dialog boxes will be displayed in the ActiveX Control Pad, enabling you to modify the control. The Propertiesdialog is for modifying properties of the control, the Edit ActiveX Control dialog is for manually editing the control. You can close both of these dialogs as we can make any further changes necessary by manually editing the HTML code. You should now find an OBJECT ID tag inserted in the HTML code, similar to that shown in Figure 6. Change the size parameters of the control by changing to “WIDTH=350” and “HEIGHT=50” in the OBJECT ID tag. Save the HTML file for the web page to the file myactivex.htm in the root folder wwwroot of IIS web server.

Figure 6. ActiveX Control Pad – MyActiveX ActiveX Control

To test the ActiveX control, load the web page http://localhost/myactivex.htm with Internet Explorer. If you get any warning messages, just click OK to proceed. This should result in a progress bar animated GIF displayed within the web page. If not, or if you get a red X displayed where the ActiveX control should be, then it is most likely due to the security settings of the browser which is preventing the ActiveX control from loading and running. To correct this, modify the security settings in Internet Explorer to change all the settings that have to do with ActiveX to enabled.

Figure 7. MyActiveX Control in Internet Explorer

Next, we need to build the ActiveX control so loading it from Internet Explorer browser does not result in annoying error messages complaining that it is an unsigned or unsafe control.

Building a Signed ActiveX Control

To create a signed ActiveX control, you must purchase a Code Signing Certificate from one of the certificate providers such as Thawte, Verisign, or GeoTrust. With this service, they will verify your identity and provide you certificate files you use to sign the ActiveX application. I chose Thawte for a Code Signing Certificate, who provided two files for signing the application, mycert.spc and mykey.pvk.

To sign the ActiveX application, we package the components of the application into a CAB file, which is downloaded from the web site and the ActiveX control is installed on the system. Part of installing the ActiveX control requires registering the control. To enable that to happen, the control must be built with the OLESelfRegister value defined in the VERSIONINFO structure of the ActiveX control. Versions of Microsoft Visual Studio up to VS 2003 inserted this entry, but Visual Studio 2005 does not. To add the entry, edit the resource file myactivex.rc to add theOLESelfRegister value, as shown below:

 Collapse | Copy Code

VS_VERSION_INFO VERSIONINFO  FILEVERSION 1,0,0,1  PRODUCTVERSION 1,0,0,1  FILEFLAGSMASK 0x3fL #ifdef _DEBUG  FILEFLAGS 0x1L #else  FILEFLAGS 0x0L #endif  FILEOS 0x4L  FILETYPE 0x2L  FILESUBTYPE 0x0L BEGIN     BLOCK "StringFileInfo"     BEGIN         BLOCK "040904e4"         BEGIN             VALUE "CompanyName", "TODO: "             VALUE "FileDescription", "TODO: "             VALUE "FileVersion", "1.0.0.1"             VALUE "InternalName", "MyActiveX.ocx"             VALUE "LegalCopyright",                    "TODO: (c) . All rights reserved."             VALUE "OLESelfRegister", "\0"             VALUE "OriginalFilename", "MyActiveX.ocx"             VALUE "ProductName", "TODO: "             VALUE "ProductVersion", "1.0.0.1"         END     END     BLOCK "VarFileInfo"     BEGIN         VALUE "Translation", 0x409, 1252     END END

Before signing the application, the ActiveX control should be packaged into a CAB file. This CAB file will also contain an INF file that is used for installing your ActiveX control. To build a CAB file, you need the cabarc.exe tool available in the Microsoft Cabinet Software Development Kit. The following is an example of a simple INF file that can be used for packaging the MyActiveX control into a CAB file. For the CLSID line item, you should change the value to the same value as that in the OBJECT ID tag in the HTML web page you created earlier with the ActiveX Control Pad.

 Collapse | Copy Code

[Add.Code] myactivex.ocx=myactivex.ocx myactivex.inf=myactivex.inf   [myactivex.ocx] file=thiscab clsid={36299202-09EF-4ABF-ADB9-47C599DBE778} RegisterServer=yes FileVersion=1,0,0,0   [myactivex.inf] file=thiscab

To create a CAB file, run cabarc as shown below. Important: Make sure the OCX and INF files are in same directory where you are running cabarc.exe, otherwise the CAB will not be extracted correctly after downloading from the web server. This is one of the problems that will cause a red X on the web page where the ActiveX control should be.

 Collapse | Copy Code

cabarc -s 6144 N myactivex.cab myactivex.ocx myactivex.inf

To sign the CAB file you created, you need the signcode.exe tool from Microsoft MSDN. Refer to the “Signing and Checking with Authenticode” reference at the end of this article. You use the signcode tool with the certificate files you obtained from purchasing a Coding Signing Certificate to sign the CAB file. The following is an example use of signcodeto sign myactivex.cab:

 Collapse | Copy Code

signcode -n "myactivex" -i     http://www.myactivex.com -spc mycert.spc -v mykey.pvk -t     http://timestamp.verisign.com/scripts/timstamp.dll myactivex.cab

In the above example, http://www.myactivex.com should be replaced with a web page that provides users further information about your signed ActiveX control.

To use the signed CAB file in your web page, first copy the myactivex.cab to a folder on your web site, then you must modify the OBJECT ID tag on your web page with a CODEBASE parameter to reference this CAB file. Refer to Figure 8 for an example. If you load this page in Internet Explorer, it should download the CAB file and install your ActiveX control with no warning about an unsigned ActiveX control.

Figure 8. ActiveX Control Pad – MyActiveX with CODEBASE

Building a Safe ActiveX Control

To make a control that will load in Internet Explorer with no unsafe control warning or error messages, you must implement code that ensures safe initialization and safe scripting for an ActiveX control. Detailed information for doing that can be found in the article “Safe Initialization and Scripting for ActiveX Controls” on Microsoft MSDN. Refer to References at the end of this article for details. I found omissions and mistakes in this article that I have corrected for presentation in this article. Basically, all that needs to be done is to add code to the DllRegisterServer andDllUnregisterServer methods. The following is a step-by-step guide for making your ActiveX control safe:

1. Edit MyActiveX.cpp and add the following code. The value of CLSID_SafeItem should be taken fromIMPLEMENT_OLECREATE_EX in the MyActiveXCtrl.cpp source file or the equivalent for your ActiveX control. It will also be the same value as the CLSID in the OBJECT ID tag on the HTML page with your ActiveX control.
    Collapse | Copy Code

   #include "comcat.h" #include "strsafe.h" #include "objsafe.h"   // CLSID_SafeItem - Necessary for safe ActiveX control // Id taken from IMPLEMENT_OLECREATE_EX function in xxxCtrl.cpp   const CATID CLSID_SafeItem = { 0x36299202, 0x9ef, 0x4abf,{ 0xad, 0xb9, 0x47, 0xc5, 0x99, 0xdb, 0xe7, 0x78}};   // HRESULT CreateComponentCategory - Used to register ActiveX control as safe   HRESULT CreateComponentCategory(CATID catid, WCHAR *catDescription) {     ICatRegister *pcr = NULL ;     HRESULT hr = S_OK ;       hr = CoCreateInstance(CLSID_StdComponentCategoriesMgr,              NULL, CLSCTX_INPROC_SERVER, IID_ICatRegister, (void**)&pcr);     if (FAILED(hr))         return hr;       // Make sure the HKCR\Component Categories\{..catid...}     // key is registered.     CATEGORYINFO catinfo;     catinfo.catid = catid;     catinfo.lcid = 0x0409 ; // english     size_t len;     // Make sure the provided description is not too long.     // Only copy the first 127 characters if it is.     // The second parameter of StringCchLength is the maximum     // number of characters that may be read into catDescription.     // There must be room for a NULL-terminator. The third parameter     // contains the number of characters excluding the NULL-terminator.     hr = StringCchLength(catDescription, STRSAFE_MAX_CCH, &len);     if (SUCCEEDED(hr))         {         if (len>127)           {             len = 127;           }         }        else         {           // TODO: Write an error handler;         }     // The second parameter of StringCchCopy is 128 because you need      // room for a NULL-terminator.     hr = StringCchCopy(catinfo.szDescription, len + 1, catDescription);     // Make sure the description is null terminated.     catinfo.szDescription[len + 1] = '\0';       hr = pcr->RegisterCategories(1, &catinfo);     pcr->Release();       return hr; }   // HRESULT RegisterCLSIDInCategory - //      Register your component categories information   HRESULT RegisterCLSIDInCategory(REFCLSID clsid, CATID catid) { // Register your component categories information.     ICatRegister *pcr = NULL ;     HRESULT hr = S_OK ;     hr = CoCreateInstance(CLSID_StdComponentCategoriesMgr,                  NULL, CLSCTX_INPROC_SERVER, IID_ICatRegister, (void**)&pcr);     if (SUCCEEDED(hr))     {        // Register this category as being "implemented" by the class.        CATID rgcatid[1] ;        rgcatid[0] = catid;        hr = pcr->RegisterClassImplCategories(clsid, 1, rgcatid);     }       if (pcr != NULL)         pcr->Release();                  return hr; }   // HRESULT UnRegisterCLSIDInCategory - Remove entries from the registry   HRESULT UnRegisterCLSIDInCategory(REFCLSID clsid, CATID catid) {     ICatRegister *pcr = NULL ;     HRESULT hr = S_OK ;       hr = CoCreateInstance(CLSID_StdComponentCategoriesMgr,              NULL, CLSCTX_INPROC_SERVER, IID_ICatRegister, (void**)&pcr);     if (SUCCEEDED(hr))     {        // Unregister this category as being "implemented" by the class.        CATID rgcatid[1] ;        rgcatid[0] = catid;        hr = pcr->UnRegisterClassImplCategories(clsid, 1, rgcatid);     }       if (pcr != NULL)         pcr->Release();       return hr; }

2. Modify the DllRegisterServer method to add the highlighted code as shown:
    Collapse | Copy Code

   STDAPI DllRegisterServer(void) {     HRESULT hr;    // HResult used by Safety Functions       AFX_MANAGE_STATE(_afxModuleAddrThis);       if (!AfxOleRegisterTypeLib(AfxGetInstanceHandle(), _tlid))       return ResultFromScode(SELFREG_E_TYPELIB);       if (!COleObjectFactoryEx::UpdateRegistryAll(TRUE))       return ResultFromScode(SELFREG_E_CLASS);       // Mark the control as safe for initializing.                                                   hr = CreateComponentCategory(CATID_SafeForInitializing,           L"Controls safely initializable from persistent data!");     if (FAILED(hr))       return hr;       hr = RegisterCLSIDInCategory(CLSID_SafeItem,           CATID_SafeForInitializing);     if (FAILED(hr))         return hr;       // Mark the control as safe for scripting.       hr = CreateComponentCategory(CATID_SafeForScripting,                                   L"Controls safely  scriptable!");     if (FAILED(hr))         return hr;       hr = RegisterCLSIDInCategory(CLSID_SafeItem,                          CATID_SafeForScripting);     if (FAILED(hr))         return hr;       return NOERROR; }

3. Modify the DllUnregisterServer method to add the highlighted code as shown:
    Collapse | Copy Code

   STDAPI DllUnregisterServer(void) {     HRESULT hr;    // HResult used by Safety Functions       AFX_MANAGE_STATE(_afxModuleAddrThis);       if (!AfxOleUnregisterTypeLib(_tlid, _wVerMajor, _wVerMinor))       return ResultFromScode(SELFREG_E_TYPELIB);       if (!COleObjectFactoryEx::UpdateRegistryAll(FALSE))       return ResultFromScode(SELFREG_E_CLASS);       // Remove entries from the registry.       hr=UnRegisterCLSIDInCategory(CLSID_SafeItem,                       CATID_SafeForInitializing);     if (FAILED(hr))       return hr;       hr=UnRegisterCLSIDInCategory(CLSID_SafeItem,                          CATID_SafeForScripting);     if (FAILED(hr))       return hr;       return NOERROR; }

ActiveX Control Properties, Methods, and Events

Communication between an ActiveX control and a web page is done through ActiveX control properties, methods, and events. In order to demonstrate these concepts, we will create a simple web page with a form entry to enter a text string. When a Submit button is pressed, the text entered is passed to the ActiveX control through an input parameter custom property. A method of the control is called which copies this text to an output parameter custom property, and then fires an event for this text to be displayed on the web page. Simply follow these steps in Visual Studio to implement this:

1. First, we will create the custom properties for passing text to and from the ActiveX control. In Class View, expand the element MyActiveXLib to select _DMyActiveX. Right click on _DMyActiveX, then Add, Add Property. In the Add Property Wizard dialog as shown in Figure 9, select BSTR for Property type, and enter “InputParameter” for Property name. The wizard will fill other fields automatically for you with “m_InputParameter” for Variable name and “OnInputParameterChanged” for Notification function. Click the Finish button where the wizard will automatically create the code to support this property. Do the same for Property name“OutputParameter” with the same Property type BSTR.

   

   Figure 9. Add Property Wizard

2. Next, we will create a method to enable the web page to notify the control to transfer the text string input parameter to the output parameter. In Class View, expand the element MyActiveXLib to select _DMyActiveX. Right click on _DMyActiveX, then Add, Add Method. In the Add Property Wizard dialog, as shown in Figure 9, select void for Return type and enter “LoadParameter” for Method name. The wizard will automatically enter “LoadParameter” for Internal name. Click Finish where the wizard will automatically create the code to support this method.

   

   Figure 10. Add Method Wizard

3. Now, we will create an event that enables the ActiveX control to notify the web page that it is completed transferring the text from the input parameter to the output parameter. Code in the web page will react to this event and respond by displaying the text in the output parameter to verify that this transfer has occurred by the ActiveX control. In Class View, right click on CMyActiveXCtrl, select Add, Add Event. In the Add Event Wizard, as shown in Figure 11, enter “ParameterLoaded” for Event name and change Internal name to “FireParameterLoaded”. Click Finish for the wizard to create the default code to support this event.

   

   Figure 11. Add Event Wizard

With the above, the wizard has created a majority of the code for you. We only need to add two lines of code to implement the functionality for the ActiveX control to copy the text and notify the web page code through an event. Edit the source file MyActiveXCtrl.cpp, and add the following code to the LoadParameter method.

 Collapse | Copy Code

// Copy text from the input parameter to the output parameter m_OutputParameter = m_InputParameter; // Fire an event to notify web page FireParameterLoaded();

To test, use the ActiveX Control Pad to create the following HTML code:

 Collapse | Copy Code

Save this HTML code to your web server, and run it. You should see a web page with a progress bar displayed and a form entry to enter the Input Parameter text. Enter text in the field, and press Submit. This should result in a new page with “The parameter you entered is: ”, followed by the text you entered on the next line. A brief explanation of the HTML code follows.

When you press the Submit button, the JavaScript function PassParameter is invoked. This function copies text from the StringInput form field to the InputParameter property of the ActiveX control. It then calls theLoadParameter method of the control which copies the text from InputParameter to OutputParameter and callsFireParameterLoaded() to cause an ActiveX event. The following HTML code then responds to this event:

 Collapse | Copy Code

References:

1. Add GIF-animation to your MFC and ATL projects with the help of CPictureEx and CPictureExWnd by Oleg Bykov, CodeProject.
2. Packaging ActiveX Controls, Microsoft.
3. Signing and Checking with Authenticode, Microsoft.
4. Safe Initialization and Scripting for ActiveX Controls, Microsoft.

License