IDocHostUIHandler::GetOptionKeyPath Method

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

Syntax

Copy

HRESULT GetOptionKeyPath(
    LPOLESTR *pchKey,
    DWORD dw
);

Parameters

pchKey

[out] A pointer to an LPOLESTR that receives the registry subkey string where the host stores its registry settings.

dw

[in] Reserved. Must be set to NULL.

Return Value

Returns S_OK if successful, or an error value otherwise.

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.

Example

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.

Copy

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;
}

See Also

WebBrowser Customization