# 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. Note that this parameter is only useful when trying to download a viewer for a particular media type, when the MIME type of media is known but the CLSID is not.
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.

##### MIME Types

The following MIME types are used to describe portable executables (.EXE., .DLL, .OCX), cabinet files (.CAB), and setup scripts (.INF):

File Description | MIME Type
Portable executable | application/x-pe-%opersys%-%cpu%
Cabinet files | application/x-cabinet-%opersys%-%cpu%
Setup scripts | application/x-setupscript

##### Registry Settings and Self-Extracting .EXEs

Use self-registering code for Internet Component Download. For security purposes, the .INF format used by Component Download does not provide syntax for changing Registry information. For .OCX, .DLL, and .EXE files marked as OleSelfRegister in the Version resource, Component Download will attempt self-registration. For a .DLL., this means loading the .DLL library and calling the DllRegisterServer entry point, if available. For an .EXE, this implies running the .EXE with the run-time parameter of /RegServer. This ensures that COM objects implemented as local servers (winword.exe, for example) are registered correctly. If an object is not marked as OleSelfRegister and registration is necessary, or if it required ot override the OleSelfRegister flat, add the following to an .INF file:

    [foo.ocx]
    RegisterServer=no; don’t register even if marked OleSelfRegister
        or
    RegisterServer=yes; register even if not marked OleSelfRegister

Code that is downloaded via Internet Component Download can be a self-extracting .EXE file. This is because Component Download ignores the OleSelfRegister flag if the main URL for points directly to an .EXE file. In this case, it is assumed that this is a self-registering .EXE, and this enables self-extracting .EXEs to work correctly as long as the /regsvr command-line parameter is ignored. While self-extracting .EXEs enable complex setup mechanisms to be launched automatically, any components that are installed will not be automatically tracked by Internet Component Download. These components are permanently installed and are not marked for future cleanup.

##### 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_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\InternetSettings\CodeBaseSearchPath

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

    CodeBaseSearchPath=<URL (1) >;<URL (2) >;...<URL (m) >;CODEBASE;<URL (m+1) >;...<URL (n-1) >;<URL (n) >

In the example above, each URL 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 URL (1) through URL (m) , it will then try the location specified in the szCodeURL parameter, and will finally try the locations specified in locations URL (m+1) through URL (n) .

Note If the CODEBASE keyword is not included in the CodeBaseSearchPath key, calls to CoGetClassObjectFromURL will not check the szCodeURL location for downloading code.

##### Internet Search Path Without HTTP

The Internet Search Path assumes that all object stores on the search path are active HTTP servers, capable of handling HTTP POST requests and querying an object database. Support for object stores on FILE or FTP servers is planned for future versions of Internet Component Download.

See Also

IBindStatusCallback, IBindStatusCallback::OnStartBinding, IBindStatusCallback::OnProgress, IBindStatusCallback::OnObjectAvailable, IBindStatusCallback::OnStopBinding, ICodeInstall, RegisterBindStatusCallback