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
);
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:
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.
There are three ways to package code for download:
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.
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 |
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.
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.
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.
IBindStatusCallback, IBindStatusCallback::OnStartBinding, IBindStatusCallback::OnProgress, IBindStatusCallback::OnObjectAvailable, IBindStatusCallback::OnStopBinding, ICodeInstall, RegisterBindStatusCallback