ch27.htm

CGI programming is the hottest stuff to look out for in this book

What the control accepts is up to its designers, but some of the
more common things are filenames, filters, and other initialization
parameters that can't be counted on from some INI file somewhere,
so the control has to take all of it into account.
<H3><A NAME="InternetComponentDownload">Internet Component Download</A>
</H3>
<P>
What if the end user doesn't have the ActiveX control for the
thing you want to show them? This has always been the bane of
plug-in developers and the enemy of the end users. When you go
to a cool site, the last thing you really want to do is see a
message that says, essentially, &quot;Oh, you'll need to be running
the Foo plug-in for this to be interesting. Why don't you go to
Foo.Com, download that 1+ meg beastie, get it set up and running,
and then come back here. It'll be worth the effort. Well, we think
it will, anyway...&quot; Would all those who really want to do
that a few dozen times please take one giant step backward in
technology? Thank you.
<P>
Traditionally, plug-in manufacturers had two choices to make that
scenario less painful. First, they could make the plug-in small
and easy to install, in the hopes that it wouldn't frustrate people
too much. Otherwise, they could try to get big companies to bundle
the plug-in with their software, hoping that everyone ends up
with some version or another that may or may not be up to date
with the sites people want to visit. In either case, that's a
lot of hoping and jumping through hoops, and ActiveX doesn't make
you go through any of it. Instead, everything gets automated.
<P>
The Internet Component Download mechanism serves one purpose-if
someone visits your site and he doesn't have the ActiveX component
he needs, it starts sending it to him. The component doesn't come
in a mail message or a file he has to muck around with but instead
arrives as a new container that will deal with the data you want
to send him. If you visit a site that has some cool 3-D stuff,
but you have no 3-D ActiveX control, it recognizes that fact and
says, &quot;Hold on a sec; I'll start giving you what you need.&quot;
Not only that, but it will install and configure it all for you
without any work on your end. If the control is small enough,
you might not even notice that it's all happening-you'll just
get seamless access to the cool stuff.
<H4><TT><FONT FACE="Courier">CODEBASE</FONT></TT></H4>
<P>
To make obtaining an ActiveX Control easy, the <TT><FONT FACE="Courier">OBJECT</FONT></TT>
tag has a <TT><FONT FACE="Courier">CODEBASE</FONT></TT> parameter,
which points to where the ActiveX control is stored on your server.
If the client doesn't have the control, this is where it looks
to get hold of it. Using the standard <TT><FONT FACE="Courier">OBJECT</FONT></TT>
tag, the following code segment shows what it looks like with
a <TT><FONT FACE="Courier">CODEBASE</FONT></TT> parameter added
in:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;object<BR>
classid=&quot;clsid:12345678-1234-1234-1234-123456789012&quot;
<BR>
CODEBASE=&quot;http://myhost.com/activex/mycontrol.ocx &quot;
<BR>
id=MyControl width=50 height=100 align=center&gt;<BR>
</FONT></TT>
</BLOCKQUOTE>
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
If you've experimented with Java before, you might be thinking that the <FONT SIZE=1 FACE="MCPdigital">CODEBASE</FONT> parameter looks suspiciously like the <FONT SIZE=1 FACE="MCPdigital">CODEBASE</FONT> parameter that Java uses to help end users get Java 
classes that they don't have on their system. You'd be exactly right-both <FONT SIZE=1 FACE="MCPdigital">CODEBASE</FONT> tags serve the same purpose and are used the same way. Isn't consistency great?
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
To ensure that end users are always running a current enough version
of the ActiveX control, the <TT><FONT FACE="Courier">CODEBASE</FONT></TT>
parameter accepts an additional parameter: <TT><FONT FACE="Courier">Version</FONT></TT>.
This allows the developer to take different available versions
of the control into account, so that no extra downloads are made
if they're not needed, but no problems arise because of out-of-date
code. The addition of the <TT><FONT FACE="Courier">Version</FONT></TT>
parameter makes a <TT><FONT FACE="Courier">CODEBASE</FONT></TT>
parameter look like this:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">CODEBASE=http://www.wherever.com/myfile.ocx#Version=a,b,c,d</FONT></TT>
</BLOCKQUOTE>
<P>
This causes the client's ActiveX container, such as Internet Explorer,
to search the registry and find out what version already exists
for an installed control. The <TT><FONT FACE="Courier">CODEBASE</FONT></TT>
parameter passes on the version number that it expects to be able
to use, and if that version number is newer than any found in
the registry, the download begins.
<H4>Security Concerns and <TT><FONT FACE="Courier">WinVerifyTrust</FONT></TT>
</H4>
<P>
When software starts downloading itself onto your system and setting
itself up, you might begin to wonder how secure the whole process
can possibly be. After all, what's to stop someone from specifying
some ActiveX control with a really new version to make sure it
gets downloaded and then does something nasty to your system?
Well, it's all a matter of trust. Windows Trust Verification Services,
to be exact.
<P>
Microsoft's model for the Windows Trust Verification Services
involves getting some assurance that the thing you're downloading
from some specified person has been verified by someone who should
logically do so. For example, when you buy food at a supermarket,
you're putting your trust in the food, the store, and whatever
organizations certify that the store meets health guidelines.
It's the &quot;What, Who, and Who Else?&quot; mentality, and it
is usually reasonably effective.
<P>
The way that Internet Component Download takes care of these verifications
is with the <TT><FONT FACE="Courier">WinTrustVerify()</FONT></TT>
procedure. This allows the client's software to perform the necessary
steps to make sure everything's okay before going ahead and installing
or running what's being referenced. Part of the method it uses
to do that is through the existence of a digital signature, which
makes sure the code hasn't been tampered with on its way from
the original source. Somewhat like checksums in electronic file
transmissions, digital signatures keep track of certain elements
and combinations that end up being indicators of whether everything's
as it should be.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Tip</B></TD></TR>
<TR><TD><BLOCKQUOTE>
You can learn more about the <FONT SIZE=1 FACE="MCPdigital">WinVerifyTrust()</FONT> mechanism, as well as digital signatures, in the ActiveX Development Kit and from some of the resources listed later in this chapter. Both the Development Kit and the 
resources provide you with more information on just what places can be trusted, and why, to give you safe code. You can even find such places as VeriSign, and become a trusted vendor yourself.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H4>The Mechanism-<TT><FONT FACE="Courier">CoGetClassObjectFromURL()</FONT></TT>
</H4>
<P>
When a container, such as Internet Explorer, wants to go ahead
and find, verify, download, and install a control, it makes one
big call-<TT><FONT FACE="Courier">CoGetClassObjectFromURL()</FONT></TT>.
This one call does all the steps needed to get the code from one
place to another and make sure nothing goes wrong in between.
It involves the following steps:
<OL>
<LI>Download the file specified in the <TT><FONT FACE="Courier">CODE</FONT></TT>
tag.
<LI>Call the <TT><FONT FACE="Courier">WinVerifyTrust</FONT></TT>
mechanism, and make sure it's safe to go ahead and install.
<LI>Self-register all the OLE components, using either <TT><FONT FACE="Courier">regserver</FONT></TT>
at the command line (for EXEs) or <TT><FONT FACE="Courier">DLLRegisterServer()</FONT></TT>
(for DLLs and OCXs).
<LI>Update the registry.
</OL>
<P>
This is the do-everything call, and it should be, considering
that the function itself is defined as shown in Listing 27.1.
<BR>
<HR>
<BLOCKQUOTE>
<B>Listing 27.1. A definition listing for </B><TT><B><FONT SIZE=2 FACE="Courier">CoGetClassObjectFromURL()</FONT></B></TT><B>.
<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">CoGetClassObjectFromURL (<BR>
 REFCLSID rclsid,<BR>
 LpcWSTR&nbsp;&nbsp;szCodeURL,<BR>
 DWORD dwFileVersionMS,<BR>
 DWORD dwFileVersionLS,<BR>
 LpcWSTR szContentTYPE,<BR>
 LPBINDCTX pBindCtx,<BR>
 DWORD dwClsContext,<BR>
 LPVOID pvReserved,<BR>
 REFIID riid,<BR>
 VOID ***ppv );</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
The actual parameters used by <TT><FONT FACE="Courier">CoGetClassObjectFromURL</FONT></TT>
can be seen in Table 27.1, and they comprise a large number of
details to make sure that what is downloaded is what's really
wanted.
<HR>
<BLOCKQUOTE>
<B>Table 27.1. The parameters used by </B><TT><B><FONT SIZE=2 FACE="Courier">CoGetClassObjectFromURL</FONT></B></TT><B>.</B>
</BLOCKQUOTE>
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><CENTER><I>Parameter</I></CENTER></TD><TD WIDTH=109><CENTER><I>Type</I></CENTER>
</TD><TD WIDTH=315><CENTER><I>Description</I></CENTER></TD></TR>
<TR><TD WIDTH=166>rclsid</TD><TD WIDTH=109><TT><FONT FACE="Courier">REFCLSID</FONT></TT>
</TD><TD WIDTH=315>The ClassID (CLSID) of the object that needs to be installed. If nothing is specified, SzContentType is used to make the determination.
</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">SzCodeURL</FONT></TT>
</TD><TD WIDTH=109><TT><FONT FACE="Courier">LpcWSTR</FONT></TT>
</TD><TD WIDTH=315>The full URL to the object's code, &aacute; l&agrave; the <TT><FONT FACE="Courier">CODEBASE</FONT></TT> tag.
</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">DwFileVersionMS</FONT></TT>
</TD><TD WIDTH=109><TT><FONT FACE="Courier">DWORD</FONT></TT>
</TD><TD WIDTH=315>Major version number for the object.</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">DwFileVersionLS</FONT></TT>
</TD><TD WIDTH=109><TT><FONT FACE="Courier">DWORD</FONT></TT>
</TD><TD WIDTH=315>Minor version number for the object.</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">SzContentType</FONT></TT>
</TD><TD WIDTH=109><TT><FONT FACE="Courier">LpcWSTR</FONT></TT>
</TD><TD WIDTH=315>MIME type that must be understood by the object.
</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">PbindCtx</FONT></TT>
</TD><TD WIDTH=109><TT><FONT FACE="Courier">LPBINDCTX</FONT></TT>
</TD><TD WIDTH=315>A bind context, which should be used to register the client's <TT><FONT FACE="Courier">IBindStatusCallback</FONT></TT> to receive callbacks during the download and installation process.
</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">dwClsContext</FONT></TT>
</TD><TD WIDTH=109><TT><FONT FACE="Courier">DWORD</FONT></TT>
</TD><TD WIDTH=315>Specifies the execution context for the object, based on its Class Context (<TT><FONT FACE="Courier">CLSCTX</FONT></TT>).
</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">PvReserved</FONT></TT>
</TD><TD WIDTH=109><TT><FONT FACE="Courier">LPVOID</FONT></TT>
</TD><TD WIDTH=315>Reserved value, which must be set to <TT><FONT FACE="Courier">NULL</FONT></TT>.
</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">Riid</FONT></TT></TD>
<TD WIDTH=109><TT><FONT FACE="Courier">REFIID</FONT></TT></TD>
<TD WIDTH=315>The interface to obtain on the factory object (typically <TT><FONT FACE="Courier">IClassFactory</FONT></TT>).
</TD></TR>
<TR><TD WIDTH=166><TT><FONT FACE="Courier">Ppv</FONT></TT></TD>
<TD WIDTH=109><TT><FONT FACE="Courier">VOID **</FONT></TT></TD>
<TD WIDTH=315>Pointer in which to store the interface pointer upon return if the call is synchronous.
</TD></TR>
</TABLE></CENTER>
<P>
<P>
<CENTER><B>Table 27.2. Expected returns from </B><TT><B><FONT SIZE=2 FACE="Courier">CoGetClassObjectFromURL</FONT></B></TT><B>.</B></CENTER>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><CENTER><I>Return</I></CENTER></TD><TD WIDTH=443><CENTER><I>Meaning</I></CENTER>
</TD></TR>
<TR><TD WIDTH=147><TT><FONT FACE="Courier">S_OK</FONT></TT></TD>
<TD WIDTH=443>Success. Ppv contains the requested interface pointer.
</TD></TR>
<TR><TD WIDTH=147><TT><FONT FACE="Courier">E_PENDING</FONT></TT>
</TD><TD WIDTH=443>Component code will be downloaded and installed asynchronously. If the client registered itself in pBindCtx, it will get notifications.
</TD></TR>
<TR><TD WIDTH=147><TT><FONT FACE="Courier">E_NOINTERFACE</FONT></TT>
</TD><TD WIDTH=443>The desired interface pointer is not available. It's also possible that this return indicates other CoGetClassObject errors.
</TD></TR>
</TABLE></CENTER>
<P>
<P>
Within the call, a number of other components are executed to
start the download, call out to the <TT><FONT FACE="Courier">WinTrustVerify()</FONT></TT>