Implementing Internet Component Download

  • Article

The Internet Component Download service is exposed through a single function, CoGetClassObjectFromURL. This system function is called by an application to download, verify, and install code for an OLE component. The function is used in the implementation of Windows Internet Explorer.

The CoGetClassObjectFromURL function returns a factory object for a given REFCLSID. If no class identifier (CLSID) is specified (CLSID_NULL), this function chooses the appropriate CLSID for interpreting the Internet MIME type specified in szContentType. If the desired object is installed on the system, it is instantiated. Otherwise, the necessary code is downloaded and installed from the location specified in szCodeURL or from an object store on the Internet search path (see below).

  • The Download and Install Process
  • The Internet Search Path
    • Internet Search Path Syntax
    • Object Stores
    • Uses for the Internet Search Path

The Download and Install Process

This "download and install" process involves the following steps.

  1. Download the necessary file(s) (.cab, .inf, or .exe) using URL Monikers.
  2. Call WinVerifyTrust to ensure that all downloaded files are safe to install.
  3. Complete self-registration of all Component Object Model (COM) components.
  4. Add registry entries to keep track of downloaded code.
  5. Call CoGetClassObjectFromURL for the desired rclsid.

In the common browser scenario, the values for parameters passed to this function are read directly from an HTML object element. For example, the szCodeURL, dwFileVersionMS, and dwFileVersionLS parameters are specified by the CODEBASE attribute inside an object element as:

<OBJECT ...
    CODEBASE=http://example.microsoft.com/sample.ocx#Version=a,b,c,d>
</OBJECT>

Where CoGetClassObjectFromURL's szCodeURL parameter is "http://example.microsoft.com/sample.ocx", dwFileVersionMS parameter is MAKELONG(b,a), and dwFileVersionLS parameter is MAKELONG(d,c).

Because downloading and installation of code occurs asynchronously, CoGetClassObjectFromURL often returns immediately with a return value of E_PENDING. At this point, the IBindStatusCallback interface is used to communicate the status of the download operation to the client. To participate in this communication, the client must implement IBindStatusCallback and register this interface in the pBindCtx parameter passed into CoGetClassObjectFromURL using RegisterBindStatusCallback. The client can expect to be called with callback notifications for IBindStatusCallback::OnStartBinding (providing an IBinding interface for controlling the download), IBindStatusCallback::OnProgress (reporting progress), IBindStatusCallback::OnObjectAvailable (which returns the desired object interface pointer), and IBindStatusCallback::OnStopBinding (which returns error codes in case of an error).

The Internet Search Path

When Internet Component Download is called to download code, it traverses the Internet search path to look for the desired component. This path is a list of object store servers that will be queried every time components are downloaded using CoGetClassObjectFromURL. This way, even if an object element in an HTML document does not include a CODEBASE attribute indicating the location to download code for an embedded OLE control, the Internet Component Download mechanism will still use the Internet search path to find the necessary code.

Internet Search Path Syntax

The search path is specified in a string in the registry, under the key HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Internet Settings\CodeBaseSearchPath. The value for this key is a string in the following format.

CodeBaseSearchPath = <URL1>; <URL2>; ... <URLm>; CODEBASE; <URLm+1>;
    ... <URLn-1>; <URLn>

In this format, each of URL1 through URLn is an absolute URL pointing to HTTP servers acting as "object stores". When processing a call to CoGetClassObjectFromURL, the Internet Component Download service will first try downloading the desired code from the locations URL1 through URLm, then try the location specified in the szCodeURL parameter (corresponding to the CODEBASE attribute in the object tag), and will finally try the locations specified in locations URLm+1 through URLn.

Note that if the CODEBASE keyword is not included in the CodeBaseSearchPath key, calls to CoGetClassObjectFromURL will never check the szCodeURL location for downloading code. By removing the CODEBASE keyword from the CodeBaseSearchPath key, corporate intranet administrators can effectively disable Internet Component Download for corporate users.

Object Stores

An object store on the Internet search path is an HTTP server that services requests for downloadable code. During a call to CoGetClassObjectFromURL, Internet Component Download will try to download code from the various object stores on the search path. Specifically, an object store will receive an HTTP POST request with data in the following format.

CLSID={class id}
Version=a,b,c,d
MIMETYPE=mimetype

All the values above are optional, although either a CLSID or MIMETYPE must be present. The object store should parse this information, check an internal database, and either fail the call or redirect the HTTP request to the downloadable code cabinet file (.cab), setup script (.inf), or portable executable image (.exe, .dll, .ocx).

The POST parameters should be processed by the object store as follows:

  • If CLSID is provided with no version number, the most recent object matching the CLSID will be returned. If the CLSID is provided with a Version, the object matching the CLSID and with the largest version number greater than or equal to Version will be provided. If no object is available that matches the CLSID and has a large enough version number, a 404 status code will be returned. MIMETYPE will be ignored when CLSID is provided.
  • If no CLSID is provided but MIMETYPE is provided, the first object found in the database that matches the MIMETYPE will be returned. Version, if provided, is treated exactly as above. If neither CLSID nor MIMETYPE is provided, the status code 400 Bad Request will be returned.

In addition to the POST data described above, queries to object stores will also include HTTP headers for Accept (MIME type) and Accept-Language, thus specifying the desired platforms. For more information see Platform Independence and HTTP and language-localized implementation for a component. Note that these HTTP headers are added to all HTTP requests made by Internet Component Download. This allows object stores to serve different code implementations for differing platforms or even different languages.

Note   Internet Component Download uses the first successful response from a server on the Internet search path. Component Download will not continue searching for newer versions of components.

 

Uses for the Internet Search Path

The Internet search path can be used in two ways:

  1. Object store servers at the beginning of the path will be asked for code before checking the location specified in the szCodeURL parameter for CoGetClassObjectFromURL. Servers at the beginning of the search path will thus be checked before trying the location specified in the CODEBASE attribute of an object tag. This is a useful feature for corporate intranets, because it allows intranet administrators to set up a local object store that is used to serve code for download by employees. In fact, it is possible to disable the CODEBASE attribute for object tags by removing the CODEBASE keyword from the search path.
  2. Object store servers at the end of the search path will be asked for code after trying the location specified in the szCodeURL parameter for CoGetClassObjectFromURL, and thus after trying the location specified in the CODEBASE attribute. This allows registration of default object store locations on the World Wide Web, where browsers can find code when no CODEBASE location is explicitly specified.