CoGetClassObjectFromURL

CoGetClassObjectFromURL

Returns a factory object for a given rclsid. If no CLSID is specified (CLSID_NULL), this function will choose the appropriate CLSID for interpreting the Internet mail extensions (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.

STDAPI CoGetClassObjectFromURL(

    REFCLSID

rclsid,                 //CLSID of the ActiveX object to be installed

    LPCWSTR szCodeURL,               //URL pointing to the code for the ActiveX object

    DWORD dwFileVersionMS,           //Major version number for object to be installed

    DWORD dwFileVersionLS,           //Minor version number for object to be installed

    LPCWSTR szContentType,           //Mime type to be understood by the installed ActiveX object

    LPBINDCTX pBindCtx,              //Bind context to use for downloading/installing component code

    DWORD dwClsContext,              //Specifies the execution context for the class object

    LPVOID pvReserved,               //Reserved, must be set to NULL

    REFIID riid,                     //Interface to obtain on the factory object

    VOID ppv * *                     //For synchronous calls, pointer to store the interface pointer upon return

);

Parameters

rclsid

[in] The CLSID of the ActiveX object to be installed. If the value is CLSID_NULL, szContentType is used to determine the CLSID.

szCodeURL

[in] The URL pointing to the code for the ActiveX object. This can point to a ôportable executableö (.OCX, .DLL, .EXE), to an .CAB (cabinet) file, or to a .INF file. If this value is NULL, the Internet Component Download will still attempt to download the desired code from an Object Store on the Internet Search Path.

dwFileVersionMS

[in] The major version number for the object to be installed. If this value and the value for dwFileVersionLS are both 0xFFFFFFFF, then it is assumed that the latest version of the code is always desired. This means that Internet Component Download will always attempt to download new code.

dwFileVersionLS

[in] The minor version number for the object to be installed. If this value and the value for dwFileVersionMS are both 0xFFFFFFFF, then it is assumed that the latest version of the code is always desired. This means that Internet Component Download will always attempt to download new code.

szContentType

[in] The MIME type to be understood by the installed ActiveX object. If rclsid is CLSID_NULL, this string is used to determine the CLSID of the object to be installed.

pBindCtx

[in] The bind context to use for downloading/installing component code. Register IBindStatusCallback in this bind context to receive callbacks during the download and installation process.

dwClsContext

[in] Values taken from the CLSCTX enumeration specifying the execution context for the class object.

pvReserved

[in] Reserved, must be set to NULL.

riid

[in] The interface to obtain on the factory object. Usually, this interface is IClassFactory.

ppv

[out] Upon return for synchronous calls, the pointer in which to store the interface pointer.

Return Values

S_OK

The function was successful; the ppv contains the requested interface pointer.

MK_S_ASYNCHRONOUS

Component code will be downloaded and installed asynchronously. The client will receive notifications through the IBindStatusCallback interface registered on pBindCtx.

E_NOINTERFACE

The desired interface pointer is not available.

Remarks

Because this function was designed to enable component download in Web browsers, the parameters passed to CoGetClassObjectFromURL closely match the values expressed in the HTML OBJECT tag. For example, szCodeURL, dwFileVersionMS, and dwFileVersionLS are specified inside an OBJECT tag as:

code=http:-/-/www.foo.com/bar.ocx#Version=a,b,c,d

where:

szCodeURL is HTTP://WWW.FOO.COM/BAR.OCX

cdFileVersionMS is MAKELONG(B,A)

dwFileVersionLS is MAKELONG(D,C)

If the pBindCtx parameter to the function is an asynchronous bind context created by CreateAsyncBindContext, downloading and installation of code occurs asynchronously, and CoGetClassObjectFromURL will return immediately with a return value of MK_S_ASYNCHRONOUS. Then, the IBindStatusCallback registered on the asynchronous bind context is used to communicate the status of the download operation to the client. By implementing the ICodeInstall callback, the client can participate in further negotiation for the download process. To participate in this communication, implement IBindStatusCallback and register this interface in pBindCtx passed to CoGetClassObjectFromURL using RegisterBindStatusCallback. Callback notifications will occur from the following:

IBindStatusCallback::OnStartBinding

Provides an IBinding for controlling the download process.

IBindStatusCallback::OnProgress

Reports progress on the download process.

IBindStatusCallback::QueryInterface

Requests additional interfaces (for example, ICodeInstall) for further negotiation.

IBindStatusCallback::OnObjectAvailable

Returns the desired object interface pointer.

IBindStatusCallback::OnStopBinding

Returns any error codes.

Note The initial implementation of CoGetClassObjectFromURL does not support system-wide simultaneous downloading of the same code. Similarly, it will not support cases by which different but simultaneous downloading refers to the same piece of dependent code.

Packaging Component Code for Automatic Download

There are three ways to package code for download:

As a single PE (portable executable) format file

By using a .CAB file

By using a stand-alone .INF file

A single PE is the simplest way to package a single-file OLE control. This single file is downloaded, installed, and registered in one operation. Note, however, that this method will not use file compression and it will not be platform independent, except with HTTP. No packaging is done with this method, the control is simply placed on a server.

Another alternative to the PE method is to package the control in a .CAB file. Cabinet files are archives of one or more files compressed using Lempel-Ziv compression. Using a .CAB file offers two advantages over the PE format method. .CAB files are compressed, which reduces the time required to download the control. In addition, multiple files can be downloaded. To package the control in a .CAB file, collect all the required files and write an .INF file to provide further installation instructions. The .INF file refers to files in the .CAB and to files at other URLs.

The third method of packaging is to specify the .INF file that contains directions for downloading and installing the control, rather than specifying the .OCX file directly or by specifying a .CAB file. The primary advantage of this method is that it provides platform independence. The .INF file is downloaded first. It is possible to specify files to download for different target platforms in the .INF file. When the .INF file is interpreted, the appropriate set of files can be downloaded. Using .INF files also offers the most flexibility in downloading the minimum amount of code required to get the control to work. Note, however, that this method does not provide the compression offered by the .CAB method. The following example is used to create a platform-independent .INF file:

[circ3.ocx]

file_win32_x86=file://products/release/circ3/x86/circ3.cab

file_win32_mips=file://products/release/circ3/mips/circ3.cab

file_mac_ppc=ignore

In the example above, the specified component circ3.ocx (CLSID, Version) needs to be installed on the system. If not already in existence, it can be downloaded from the given location (a .CAB). The ignore keyword indicates that this file is not needed for this platform.

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. In this way, even if an OBJECT tag in an HTML document does not specify a CODEBASE location to download code for an embedded OLE control, the Internet Component Download will still use the Internet Search Path to find the required code. The Internet Search Path provides a great deal of flexibility in determining how files get downloaded. By setting up URLs in the path before the CODEBASE keyword, files can be installed from local intranet caches of common components. By removing the CODEBASE keyword from the path completely, component download from the internet is effectively disabled. By setting up URLs in the path after the CODEBASE keyword, files can be installed from standard distribution points, even if the server specified is not available.

The version number is also considered when locating files. If a version number is specified, the download service will only try to download and install the file if the version number specified is more recent that any version currently installed on the system. If the version number specified is -1, -1,-1,-1, the download service will always try to locate the latest version of the file for download. When searching the Internet Search Path, each Object Store receives an HTTP POST request containing the CLSID or MIME type and, optionally, a version number in the following format:

CLSID={class id}

Version=a,b,c,d

MIMETYPE=mimetype

All of the values are optional, however, either CLSID or MIMETYPE must be present. The Object Store parses this information, checks the internal database of available files, and redirects the HTTP request to the appropriate downloadable file.

The search path is specified in a string in the Registry, under the following key:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\InternetSettings\CodeBaseSearchPath

The value for this key is a string in the following format:

CodeBaseSearchPath=<URL (