GetOverrideKeyPath method

Article
05/02/2017

Gets a registry subkey path that modifies Windows Internet Explorer user preferences.

Syntax

HRESULT retVal = object.GetOverrideKeyPath(pchKey, dw);

Parameters

pchKey [out]
Type: LPOLESTR

A pointer to an LPOLESTR that receives the registry subkey string where the host stores its registry settings.
dw [in]
Type: DWORD

Reserved. Must be set to NULL.

Return value

Type: HRESULT

If this method succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

A WebBrowser Control instance calls IDocHostUIHandler2::GetOverrideKeyPath on the host at initialization so that the host can specify a registry location containing settings that modify the Internet Explorer registry settings for the current user. If the host returns S_FALSE for this method, or if the registry key path returned to the WebBrowser Control in pchKey is NULL or empty, the WebBrowser Control reverts to the registry settings for the current user.

IDocHostUIHandler2::GetOverrideKeyPath provides an alternate mechanism to IDocHostUIHandler::GetOptionKeyPath for a WebBrowser Control host to make changes in the registry settings for the WebBrowser Control. By using IDocHostUIHandler2::GetOverrideKeyPath, your WebBrowser Control instance preserves registry settings for the current user. Any registry changes located at the registry path specified by this method override those located in HKEY_CURRENT_USER/Software/Microsoft/Internet Explorer. Compare this to IDocHostUIHandler::GetOptionKeyPath, which causes a WebBrowser Control instance to default to its original settings before registry changes are applied from the registry path specified by the method.

For example, assume the user has changed the Internet Explorer default text size to the largest font. By implementing IDocHostUIHandler2::GetOverrideKeyPath, that change is preserved—unless the size is specifically overridden in the registry settings located at the registry path specified by the implementation of IDocHostUIHandler2::GetOverrideKeyPath. By implementing IDocHostUIHandler::GetOptionKeyPath, the user's text size change is not preserved. Instead, the WebBrowser Control defaults to its original medium-size font before registry settings are applied from the registry path specified by the IDocHostUIHandler::GetOptionKeyPath implementation.

An implementation of IDocHostUIHandler2::GetOverrideKeyPath must allocate memory for pchKey using CoTaskMemAlloc. The WebBrowser Control is responsible for freeing this memory by using CoTaskMemFree. Even if this method is not implemented, this parameter should be set to NULL.

The key specified by this method must be a subkey of the HKEY_CURRENT_USER key.

Examples

This example points the WebBrowser Control to a registry key located at HKEY_CURRENT_USER/Software/YourCompany/YourApp for user preference overrides. You must set registry keys at this location in the registry for the WebBrowser Control to use them.

HRESULT CBrowserHost::GetOverrideKeyPath(LPOLESTR *pchKey, DWORD dwReserved)
{
    HRESULT hr;
    WCHAR* szKey = L"Software\\MyCompany\\MyApp";
    
    //  cbLength is the length of szKey in bytes.
    size_t cbLength;
    hr = StringCbLengthW(szKey, 1280, &cbLength);
    //  TODO: Add error handling code here.
    
    if (pchKey)
    {
        *pchKey = (LPOLESTR)CoTaskMemAlloc(cbLength + sizeof(WCHAR));
        if (*pchKey)
            hr = StringCbCopyW(*pchKey, cbLength + sizeof(WCHAR), szKey);
    }
    else
        hr = E_INVALIDARG;

    return hr;
}