GetOptionKeyPath method

Article
05/02/2017

Gets a registry subkey path that overrides the default Windows Internet Explorer registry settings.

Syntax

HRESULT retVal = object.GetOptionKeyPath(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 GetOptionKeyPath on the host at initialization so that the host can specify a registry location containing settings that override the default Internet Explorer registry settings. 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 default Internet Explorer registry settings.

GetOptionKeyPath and IDocHostUIHandler2::GetOverrideKeyPath provide two alternate mechanisms for a WebBrowser Control host to make changes in the registry settings for the WebBrowser Control. By using GetOptionKeyPath, a WebBrowser Control instance defaults to its original settings before registry changes are applied from the registry path specified by the method. By using GetOptionKeyPath, a 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.

For example, assume that 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 GetOptionKeyPath. By implementing 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 GetOptionKeyPath implementation.

An implementation of GetOptionKeyPath must allocate memory for pchKey using CoTaskMemAlloc. The WebBrowser Control is responsible for freeing this memory using CoTaskMemFree. Even if this method is not implemented, the 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 Internet Explorer registry overrides. You must set registry keys at this location in the registry for the WebBrowser Control to use them.

HRESULT CBrowserHost::GetOptionKeyPath(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;
}

Partager via