A Complete Scriptable ActiveX Web Control Tutorial Using ATL

• Download demo project - 117 KB
• Download source - 16.1 KB

Introduction

ActiveX Control is a term used to denote reusable software components that are based on the Microsoft Component Object Model (COM) that allows developers to create objects or controls that can be used to "activate" content on the World Wide Web.

I have read lots of stuff over the internet but I have not found a complete guideline or example through a process with which I can build an ActiveX control for the web using ATL with VC++6.0. I wrote this article because I couldn't find a unified description of this process anywhere on the web. I am going to present to you a complete example with necessary stuff. Hope this will help you understand how we can build a Scriptable ActiveX control for web using ATL, and also you will get a clear vision of ActiveX security details. It's written with as much detail as possible, but with the assumption that the reader basically knows his stuff.

In this article, I have tried to present to you an example of a Scriptable ActiveX Web Control using ATL which will display a Label control with the current date and time on your Internet Explorer. Also, you will see a guided step by step on creating the control using Microsoft VC++6.0 as safe for Web.

Safety and security

The security concerns associated with an ActiveX control is mainly due to the fact that ActiveX controls can do almost anything that a normal application can. Therefore, both malware and useful ActiveX controls exist; thus the threat level of an ActiveX control can be associated with how trusted its author is.

However, there is a famous case of ActiveX controls safety concern: Internet Explorer. Internet Explorer has the ability to run ActiveX controls within a web page. This is both a blessing and a pain.

ActiveX controls like Adobe Reader, Adobe Flash Player, Apple QuickTime Player, Microsoft Windows Media Player, Real Networks RealPlayer, and Sun Java Virtual Machine are routinely used by Internet surfers every hour of the day all across the globe.

However, opening a web page that contains a harmful ActiveX control, and then allowing Internet Explorer to run that harmful control, would be the same as running a malware on the computer. Fortunately, Internet Explorer 6 and Windows Vista have taken actions to reduce such risks.

Requirements for Scriptable ActiveX Controls

Microsoft has published a document that describes all the aspects of component object safety with regards to scripting ActiveX controls.

Before registering your control as safe for scripting, you must ensure that your control does not take any actions that may be unsafe when used by a scripting client. Unsafe actions include exposing information normally kept private, such as passwords and other sensitive information, executing files, and making dangerous system calls.

Another type of object safety concerns the use of parameters and properties with the control. When used with a scripting client, a safe control must ensure that the control can continue to function with any possible combination of properties defined by the user.

Design a Scriptable ActiveX Control

A scriptable ActiveX control is a control that is constructed so that it is appropriate for use by scripting clients. Scriptable controls are designed to be safe when used in a Web browser, such as Internet Explorer, or by scripts written for the Windows Scripting Host (WSH). Scriptable controls also support mechanisms to simplify passing parameters to the control via a scripting language.

By default, ActiveX controls are not considered safe for scriptable clients. If you have an ActiveX control that could be used by scripting clients, taking a few simple steps can expand the usefulness of your control. If you're using ATL, these changes typically take just a few minutes.

To be scriptable, an ActiveX control must meet the following requirements:

• Be safe when executed by an arbitrary scripting client.
• Be registered as "Safe for Scripting".
• Support the IPersistPropertyBag interface. This is technically not a requirement, but it simplifies the task of passing parameters to the control.

Creating a Scriptable ActiveX Control

To create a Scriptable ActiveX control, use Microsoft Visual C++ 6.0 to perform the following steps:

1. File->New->Projects.
2. In the New Project dialog, as shown in Figure 1, select "ATL COM AppWizard".



Figure 1. New Project dialog
3. Name the project ScriptableActiveX; for Location, enter the working folder for the project's source code, and then click the OK button.
4. You will see a screen, as shown in Figure 2, that gives you several choices. The first choice is "Server Type". We are going to build a server DLL, so make sure that the Server Type is set to "Dynamic Link Library".



Figure 2. ATL COM AppWizard
5. The other three checkboxes below do not concern us in this particular project, so we can ignore them. Press the Finish button to have the Wizard generate the appropriate files for you.
6. A "New Project Information" window, as shown in Figure 3, will appear to tell you what files are going to be created. Press the OK button to accept this.



Figure 3. New Project Information

Creating a new ATL object

1. From the Insert menu, select the "New ATL Object" menu item. The "ATL Object Wizard" window, as shown in Figure 4, will appear.



Figure 4. ATL Object Wizard
2. Select Controls from the wizard's Category list box, and then select Full Control as the control type. Click Next to begin adding the ScriptableLabel control to the project.
3. The "ATL Object Wizard Properties" dialog, as shown in Figure 5, will appear so that you can define your control's properties. For full controls, such as ScriptableLabel, the dialog box offers four tabs.



Figure 5. ATL Object Wizard Properties
4. All component types present a Names property page that contains naming attributes for ATL components. You only need to fill in the Short Name property for ScriptableLabel and the other fields are filled in automatically.
5. The second tab, as shown in Figure 6, for most component types is the Attributes property page, which is used to collect information about the component. All these values are the default options, except the "Support Connection Points" properties for the component. Connection points are used to supply events to a control's container.



Figure 6. ATL Object Wizard Properties (Attributes)
6. The third tab, as shown in Figure 7, is the Miscellaneous tab. It contains attributes specific to the ActiveX controls.



Figure 7. ATL Object Wizard Properties (Miscellaneous)
7. The final tab, as shown in Figure 8, in the dialog box is Stock Properties. It contains a list of all stock properties that can be implemented by an ActiveX control.



Figure 8. ATL Object Wizard Properties (Stock Properties)
8. The ScriptableLabel control uses the following stock properties:
• Background Color
• Caption
• Font
• Foreground Color

After you select the stock properties listed here, click OK to close the dialog box. The ATL New Object Wizard then generates the necessary code and adds it to your project.

Modify control attributes

The default handler for OnCreate will superclass a default instance of the Windows CStatic class. Apply the following window styles changes to the OnCreate() member function to the ScriptableLabel control:

m_ctlStatic.Create( m_hWnd,
                    rc, 
                    _T("Static"),
                    WS_CHILD|WM_PAINT);

Retrieving ambient properties

When the control is initially loaded, it collects the current foreground color, background color, and font from its container. A good time to collect ambient properties is when the control and its container negotiate the client site. Add the following source code to the ScriptableLabel.cpp source file. This function overrides the base class implementation of SetClientSite() and stores the ambient values of these three properties.

STDMETHODIMP CScriptableLabel::SetClientSite(LPOLECLIENTSITE pSite)
{
    HRESULT hr = CComControlBase::IOleObject_SetClientSite(pSite);
    if(!m_pFont && pSite)
    {
        hr = GetAmbientFontDisp(&m_pFont);
    }
    GetAmbientBackColor(m_clrBackColor);
    GetAmbientForeColor(m_clrForeColor);
    return hr;
}

Add the following member function declaration to the CScriptableLabel class:

STDMETHOD(SetClientSite)(LPOLECLIENTSITE pSite);

Drawing the control

The OnDraw() function is called by the ATL framework, passing in a structure that contains various bits of information needed to actually paint information on the screen. Our implementation isn’t much more complicated than it would be if we were simply displaying the current date and time. Add the following drawing code for the control to the ScriptableLabel.h header file.

void DrawString( HDC hdc, RECT* rc, BSTR caption )
{
    USES_CONVERSION;        
    TCHAR* pCaption = OLE2T(caption);

    DrawText( hdc,
             pCaption,
             lstrlen( pCaption ),
             rc,
             DT_WORDBREAK );
}

HRESULT OnDraw(ATL_DRAWINFO& di)
{
    RECT& rc  = *(RECT*)di.prcBounds;
    HDC   hdc = di.hdcDraw;

    COLORREF clrFore, clrBack;
    OleTranslateColor(m_clrForeColor, NULL, &clrFore);
    OleTranslateColor(m_clrBackColor, NULL, &clrBack);
    SetTextColor(hdc, m_clrForeColor);
    HBRUSH hbrBtn = CreateSolidBrush(m_clrBackColor);

    FillRect(hdc, &rc, hbrBtn);        
    DrawString(hdc, &rc, m_bstrCaption);    

    DeleteObject(hbrBtn);
    return 0;
}

Implementing IPersistPropertyBag


To simplify the use of ScriptableLabel in a scripting client, such as Internet Explorer, the control must support the 
IPersistPropertyBag interface. The ATL class library includes a class, IPersistPropertyBagImpl, that provides a default implementation 
of IPersistPropertyBag that is sufficient in most cases.




Add the following line to your class derivation list:


public IPersistPropertyBagImpl<CScriptableLabel>


Add the following lines to your COM_MAP:


COM_INTERFACE_ENTRY(IPersistPropertyBag)




Marking the control safe for scriptable clients


You can easily add support for marking the control safe for scriptable clients by implementing the IObjectSafety interface. This is done by deriving 
your control from the default ATL implementation, IObjectSafetyImpl.


You can use two methods to mark a control as safe for scripting clients:




Make appropriate entries directly in the System Registry.


Implement the IObjectSafety interface.




Microsoft recommends that you use new controls to implement the IObjectSafety interface instead of making Registry entries. 
IObjectSafety enables the control to apply much finer-grained safety policies than possible using the Registry.


ATL provides a default implementation of IObjectSafety that you easily can take advantage of by deriving your class from the 
IObjectSafetyImpl class.




Add the following line to your class derivation list:


public IObjectSafetyImpl<CScriptableLabel, 
                        INTERFACESAFE_FOR_UNTRUSTED_CALLER | 
                        INTERFACESAFE_FOR_UNTRUSTED_DATA>


Two template arguments are passed to IObjectSafetyImpl:




The name of the class deriving from IObjectSafetyImpl.


The type of safety to be applied to the control.




Two values may be passed for the safety options:




INTERFACESAFE_FOR_UNTRUSTED_CALLER specifies that your control can be used safely by a scripting client and does not violate any of Microsoft's security or safety guidelines.


INTERFACESAFE_FOR_UNTRUSTED_DATA specifies that your control will work (or at least degrade gracefully) in the presence of any possible set of paramaters.




Add the following lines to your COM_MAP:


COM_INTERFACE_ENTRY(IObjectSafety)




Compiling the scriptable ActiveX control


Compile the ScriptableActiveX project. The compiler will register your new DLL in the Registry so that other programs can make use of it. You can test the control 
in a variety of control containers, including Visual Basic and Visual C++. You will find lots of examples using Visual Basic and Visual C++. Better! we consider as web control.


Because the ScriptableLabel control is scriptable, you can also use the control on an HTML page with Internet Explorer. Let's try it out.


Building a signed ActiveX control


To use your control on web pages, it is very convenient to distribute it as a .cab (cabinet file). This is a compressed archive - the classic use is to put 
the .cab file on a web server, and refer to it from web pages that host the control. Internet Explorer is smart enough to download and install the control if 
it is not already installed on the client machine, and to selectively update any files that are newer in the .cab file. Microsoft provides CABARC.EXE for creating and editing 
.cab files.


The contents of a CAB file


A CAB file contains at least two files in the archive: an ActiveX component file (.EXE, .DLL, or .OCX file), and an .INF file.




Component file (.EXE, .DLL, or .OCX): The type of ActiveX component you create determines the file extension of the file included here. 
All ActiveX controls have a .OCX extension. Other ActiveX components are either .EXEs or .DLLs. This file is your ActiveX component being installed.


.INF: This is the information file that contains information about what other files your ActiveX component depends on (dependency files), 
where to get copies of those files, and how to install those files.




Creating a CAB file


This section describes creating CAB files for distributing ATL and MFC controls over the Internet.


To create a CAB file:




Create an INF file.


Run the CABARC utility.




1. Creating an INF file


The INF file is a text file that specifies the files (such as DLLs or other OCXs) that need to be present or downloaded for your control to run. An INF file 
allows you to bundle all the needed files in one compressed CAB file. By default, files with the same version numbers as existing files on the user's hard disk will not be downloaded.


As an example, the following INF file will be used to create a CAB file for the ScriptableActiveX control.


; Sample INF file for SCRIPTABLEACTIVEX.DLL
[version] 
; version signature (same for both NT and Win95) do not remove
signature="$CHICAGO$"
AdvancedINF=2.0  

[Add.Code]
ScriptableActiveX.dll=ScriptableActiveX.dll
ScriptableActiveX.inf=ScriptableActiveX.inf

[ScriptableActiveX.dll]
file-win32-x86=thiscab
clsid={B8748B60-E34D-42AA-9309-8012CA4964AC} 
FileVersion=1,0,0,1 
RegisterServer=yes

[ScriptableActiveX.inf]
file=thiscab
; end of INF file


clsid is the CLSID of the control to be installed.


2. Running the CABARC Utility


Once you have created an INF file, run the CABARC utility to create the CAB file. You should run CABARC in the directory that contains your source files. 
On the command line, put the source files in the order they appear in the INF and the INF file last. For example, to make a CAB file for the Polygon control 
from the INF above, use the following command:


CABARC -s 6144 n ScriptableActiveX.cab ScriptableActiveX.dll ScriptableActiveX.inf


The -s option reserves space in the cabinet for code signing. The n command specifies that you want to create a CAB file.


Code signing tools


Microsoft provides code signing tools as part of the "Microsoft .NET Framework Software Development Kit (SDK) 1.1". To download the SDK, visit the following 
Microsoft website: .NET Framework SDK Version 1.1. 
After you install the SDK, you will be able to find the code signing files in the following location on your PC: "\Program Files\Microsoft.NET\SDK\v1.1\Bin". 
From the many files found in the above BIN directory, the following are of interest to us:




signcode.exe


makecert.exe


cert2spc.exe


chktrust.exe




Recently, with the introduction of "Studio 2005", Microsoft has released a new set of tools. The new set of tools is provided as part of the "Visual Studio 2005" 
and in the "Platform SDK". To download the "Platform SDK", visit the following Microsoft 
website: Platform SDK full download. 
After you install the SDK, you will be able to find the code signing files in the following location on your PC: "\Program Files\Microsoft Platform SDK\Bin". 
From the many files found in the above BIN directory, the following are of interest to us:




signtool.exe


makecert.exe


cert2spc.exe




All the above mentioned tools are actually small console programs that should be run from a command prompt. When run, each program expects command-line parameters 
in a special syntax. Now, we will demonstrate how to do it in this article.


Signing a CAB file


Security is becoming increasingly important for software and media developers. "Code Signing" enables end users of your software to verify that the code you provide 
comes from the rightful source and that it has not been maliciously altered or accidentally corrupted.


Code signing technology has been available for many years, but many software vendors refrained from using it because of the complexity involved in the process. 
However, since the release of "Windows XP Service Pack 2", code signing can not be ignored any more.


With XP SP2, when downloading an unsigned program with Internet Explorer and choosing to open it (or even if saved to a file and later opened via Windows Explorer), 
the browser will display the "Security Warning" dialog. But when downloading a signed program, the browser does not result in annoying error messages complaining 
that it is an unsigned or unsafe control.


You have two options to sign your code:




Option 1: Using a test certificate


Option 2: Using a public certificate




Option 1: Using a test certificate


Before you start with the process, it is highly recommended that you create a "Test certificate" and use it to sign your program as a test run. 
A program signed by this certificate must not be distributed on the net.


Use the following steps to sign and validate the .cab file:




Type the following at a command prompt to create a private key file, Mycert.pvk.


makecert -sv "mycert.pvk" -n "CN=My Company" mycert.cer


The file created in this step, Mycert.cer, is used to create a .spc file. Type the password in the dialog box.


Create a .spc file from the certificate file with the correct password. To do so, type the following line at a command prompt:


cert2spc mycert.cer mycert.spc


Note that this step involves creation of a test private key. Alternatively, valid certificates can be created through a Microsoft Certificate Server 
for Intranet use or purchased from external vendors for Internet use.


Create a Personal Information Exchange file. This step is optional. You will need it only if you select to sign your code using SIGNTOOL.EXE as described above. 
The following command line may be used to create a "Personal Information Exchange" (PFX) file:


pvk2pfx -pvk mycert.pvk -pi Pass1 -spc mycert.spc -pfx mycert.pfx -po Pass2 -f




PVK2PFX.EXE expects two passwords:




Pass1: Provide the same password you used when creating the private and public keys.


Pass2: Provide a new password to protect the PFX file.




Once signed, you can distribute the ActiveX component to any user, but the user must install the certificate chain. If you want users to install an ActiveX component 
without the Root and Intermediate certificates, then buy a public code-signing certificate.


Option-2: Using a public certificate


To be able to sign your code, you will need a certificate. Certificates are issued by special Internet organizations called CA (Certificate Authority). 
There are many such organizations, the most prominent ones are: verisign.com and tawthe.com.


You can get a full list of CAs by going to: Microsoft Root Certificate Program Members.


However, acquiring a certificate is quite a tedious and time consuming process. (The CA has to identify you or your organization before it can issue a certificate.) 
And you should expect to pay a few hundred of dollars for the certificate.


Finishing touches


Now, use the key information to sign the .cab file:


signcode -v mycert.pvk -spc mycert.spc ScriptableActiveX.cab -t [Timestamp server URL]


Or, the following commands may be used to sign your code using SIGNTOOL.EXE:


signtool sign /f mycert.pfx /p Pass2 /v ScriptableActiveX.cab /t [Timestamp server URL]


Pass2: Enter here the second password you used when creating the PFX file.


Note: Specify the timestamp server URL at this step. The timestamp server URL provides a place to enter or edit the location of a timestamp server. 
A timestamp server validates the date and time that the cabinet file was signed. Certificate files can expire after a certain period of time. 
Contact your certificate file provider (certificate authority) for the location of their timestamp server. 
The URL of a time stamping service is provided for free by verisign.com: http://timestamp.verisign.com/scripts/timstamp.dll.


Validate a CAB file


Follow this procedure to validate a .cab file:


Option-A: Using CHKTRUST




Type the following at a command prompt to run SETREG.EXE on the client system with the TRUE value so that the test certificates are recognized:


setreg -q 1 TRUE


Run CHECKTRUST.EXE to ensure that the CAB file is signing correctly:


chktrust ScriptableActiveX.cab


Expected results:


ScriptableActiveX.cab: Succeeded




Option-B: Using SIGNTOOL


Run SIGNTOOL.EXE to verify the signing:


signtool verify /v /a ScriptableActiveX.cab


Expected results:


ScriptableActiveX.cab: Succeeded


Option-C: Using properties


You can also use the following method to verify your digital signature:




Open Explorer.
 

Browse to the file you just signed.
 

Right click the file name and select "Properties".




Explorer will present you with the Properties dialog of the file. This Properties dialog will include a new tab "Digital Signatures". 
You can now read the details of the signature in this tab.


Embedding a signed CAB file on a web page


ATL and MFC controls are embedded in web pages using the <OBJECT> tag. Within the 
<OBJECT> tag, you need to specify three attributes for the control:


<OBJECT classid=B8748B60-E34D-42AA-9309-8012CA4964AC
    id=ScriptableLabelControl
    CODEBASE ="ScriptableActiveX.cab#version=1,0,0,1">
</OBJECT>


The ID parameter refers to the name of the control. The CLASSID parameter refers to the CLSID of the control. And, the 
CODEBASE parameter refers to the location from which to download the control. Note: that CODEBASE can point at a number of different file types successfully.


If you include the optional version number with a CAB file, the version number should refer to the control being downloaded. 
For example, since ScriptableActiveX.dll has a version number of 1, 0, 0, 1, the version for the CAB is also 1, 0, 0, 1.


If you do not include the version number, older versions of the same control will not be replaced if they are found on the client machine.


Testing the Scriptable ActiveX Web Control


Adding controls by hand is not a simple process. The CLSID numbers are unwieldy to type, and it can be difficult to visualize the effects 
of the parameter settings on the control. To help with these difficulties, Microsoft created the ActiveX Control Pad, which can be obtained from their website 
at Microsoft ActiveX Control Pad.


To test the Scriptable ActiveX Web Control with JavaScript, you may use ActiveX Control Pad to create one or you may find it easier to lay out your page 
in your preferred HTML editor as the following HTML code:


<HTML>
<HEAD>
<TITLE>Scriptable ActiveX Web Control</TITLE>
<SCRIPT LANGUAGE="JavaScript">
    function NotifyActiveX(e)
    {
        if ( e.readyState != 4 ) return;
        window.setInterval("document.all.ScriptableLabelControl.caption=(new Date()).toString()",1000);
    }
</SCRIPT>
<STYLE TYPE="text/css">
#ScriptableLabelControl {
    width: 250px;
    height: 27px;
    padding: 10px;
    border: thin solid #408080;
    margin-left: 10em;
}
</STYLE>
</HEAD>

<BODY>
<OBJECT 
  ID="ScriptableLabelControl"
  onReadyStateChange="NotifyActiveX(this)"
  CLASSID="CLSID:B8748B60-E34D-42AA-9309-8012CA4964AC"
  CODEBASE="ScriptableActiveX.cab">
</OBJECT>
</BODY>
</HTML>


Save this HTML code in your web server, and browse it!


Internet Explorer will prompt the user before downloading and installing the ActiveX control. If Internet Explorer is attempting to install the Signed ActiveX control 
automatically, it shows a prompt as shown in Figure 9.





Figure 9. Install ActiveX


When prompted with a certificate, please accept it. When the downloading and installation process is finished, the current date and time should appear, as shown in Figure 10.





Figure 10. Scriptable ActiveX control


If you see the current date and time displayed properly in your browser, congratulations! ActiveX and scripting are working properly.


Note:




If you see a date and time but it isn't the right time, your PC's clock is set wrong! Double-click the time in the system tray to correct it.


If you see a blank space, ActiveX is probably working properly, but not scripting.


If you see the message ActiveX is not supported, then your browser doesn't recognize ActiveX at all. Netscape, Opera, or other browsers usually do not support ActiveX.


When you think you've corrected any problem you are having with this, simply refresh the page [press F5] to try again.




Conclusion


For a control to be scriptable, it must follow Microsoft's object safety guidelines and be marked as safe for scripting. In this article, you examined the 
IObjectSafety interface and learned how a control built using ATL can take advantage of IObjectSafety. 
An example of a safely scriptable ActiveX control helped you explore this topic.