INFO: The CorBindToRuntimeHost API (815630)

MORE INFORMATION

The CorBindToRuntimeHost API is similar to the CorBindToRunTimeEx API that enables unmanaged hosts to load the common language runtime to a process. However, the CorBindToRuntimeHost API specifies the host configuration file (pwszHostConfigFile parameter) so that binding can be redirected to a type that is in a specific version of an assembly, as in the following prototype:

STDAPI CorBindToRuntimeHost  (  LPCWSTR    pwszVersion,  
  LPCWSTR    pwszBuildFlavor,  
  LPCWSTR    pwszHostConfigFile,  
  VOID *    pReserved,  
  DWORD    startupFlags,  
  REFCLSID    rclsid,  
  REFIID    riid,  
  LPVOID FAR *    ppv 
 )  

Parameters

The list of API parameters is:

• pwszVersion: [IN] A string that describes the version of the common language runtime that you want to load.
• pwszBuildFlavor: [IN] A string that describes whether the server (SVR) build or the workstation (WKS) build of the common language runtime must be loaded. The valid values are WKS and SVR. The server build is optimized to take advantage of multiple processors while the server build performs garbage collection. This behavior occurs when the workstation build is optimized for client applications that run on a single processor computer.
• pwszHostConfigFile: [IN] A configuration file that has additional information for the version policy.
• pReserved: [IN] Reserved for future use. This parameter must be set to zero.
• startupFlags: [IN] A set of flags that controls concurrent garbage collection, domain-neutral code, and the behavior of the pwszVersion parameter. The following list contains the valid values:
  • STARTUP_CONCURRENT_GC: Specifies that concurrent garbage collection must be used. If the caller requests the SVR build and the concurrent garbage collection on a single processor computer, WKS and non-concurrent garbage collection run instead.
  • STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN: No assemblies are loaded domain-neutral.
  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN: All assemblies are loaded domain-neutral.
  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST: All strong-named assemblies are loaded domain-neutral.
  • STARTUP_LOADER_SAFEMODE: Specifies that the exact version of the common language runtime that is passed as pwszVersion is loaded. The shim does not evaluate policy to determine what the latest compatible version is.
  • Single domain is the default if none of the STARTUP_LOADER_ flags are set.
• rclsid: [IN] The class identifier (CLSID) of the coclass that implements the interface that you are looking for. The supported values for the initial release of the common language runtime are CLSID_CorRuntimeHost or NULL.
• riid: [IN] The ID of the interface that you request. The supported values for the initial release of the common language runtime are IID_ICorRuntimeHost or NULL.
• ppv: [OUT] The returned interface pointer (used to obtain an interface pointer to ICorRuntimeHost that you can use to set additional options that allow a host to configure an instance of the common language runtime before it is started).

Return Values

The following list describes the return values of the API. This API supports the standard return value E_INVALIDARG and the following values:

• S_OK: The API returns the version information when the API is successful.
• ERROR_INSUFFICIENT_BUFFER: The output buffer is too small to hold the whole string.
• REGDB_E_CLASSNOTREG: The class is not registered.

Requirements

To use the CorBindToRuntimeHost API, include the following header file and library file:

• Header file: Include Mscoree.h
• Library file: Link with Mscoree.lib