ICreatePropBagOnRegKey::Create

The Create method creates a property bag that can store information in the system registry.

Syntax

HRESULT Create(
  HKEY  hkey,
  LPCOLESTR  subkey,
  DWORD  ulOptions,
  DWORD  samDesired,
  REFIID  iid,
  LPVOID*  ppBag
);

Parameters

  hkey

[in]  Specifies a handle to the registry key.

  subkey

[in]  Specifies the subkey.

  ulOptions

[in]  Reserved; must be zero.

  samDesired

[in]  Specifies the desired access rights to the key. The value can be any combination of flags from the samDesired parameter in the Win32 RegOpenKeyEx function.

  iid

Specifies the interface identifier (IID) of a property bag interface. Use the value IID_IPropertyBag or IID_IPropertyBag2.

  ppBag

[out]  Address of a variable that receives the interface specified by the iid parameter.

Return Values

Returns an HRESULT value. Possible values include the following.

Remarks

This method creates a property bag and returns a pointer to the IPropertyBag or IPropertyBag2 interface, depending on the value of the iid parameter. The returned property bag can access the specified registry key, using the access rights given in the samDesired parameter. The various property bag methods require different access rights, as follows:

If you write a value of VT_EMPTY or VT_NULL the property is removed from the bag and the corresponding registry values are deleted.

Example Code

To create a default tune request in the registry, first create a tune request object and query it for the IPersistPropertyBag interface. Then call IPersistPropertyBag::Save with a pointer to the property bag:

ICreatePropBagOnRegKey *pCreateRegBag;
IPropertyBag *pRegBag;
IPersistPropertyBag *pPersist;
ITuneRequest *pTuneReq;

// Create an instance of the CreatePropBagOnRegKey object
// and obtain a pointer to the interface.
HRESULT hr = CoCreateInstance(CLSID_CreatePropBagOnRegKey, NULL, CLSCTX_INPROC_SERVER,
    IID_ICreatePropBagOnRegKey, (void**)&pCreateRegBag);
if (SUCCEEDED(hr))
{
    //Create the property bag.
    hr = pCreateRegBag->Create(HKEY_CURRENT_USER,
        OLESTR("SOFTWARE\\Microsoft\\MSVidCtl\\DefaultTuneRequest"),
        0, KEY_READ | KEY_WRITE, IID_IPropertyBag, (void**)&pRegBag);
    if (SUCCEEDED(hr))
    {
        // Assume pTuneReq is a pointer to a valid tune request, which was 
        // created as specified elsewhere in this documentation.
        pTuneReq->QueryInterface(IID_IPersistPropertyBag, (void**)&pPersist);
        // Save the property bag to the registry.
        pPersist->Save(pRegBag, FALSE, TRUE);

        pRegBag->Release();
        pPersist->Release();
    }
    pCreateRegBag->Release();
}

The following example loads the default tune request and returns an ITuneRequest interface pointer:

HRESULT LoadDefaultTuneReq(ITuneRequest **ppTuneReq)
{
    HRESULT hr;
    *ppTuneReq = NULL;
    CComPtr<ICreatePropBagOnRegKey> pCreateRegBag;
    hr = pCreateRegBag.CoCreateInstance(CLSID_CreatePropBagOnRegKey, 
        NULL, CLSCTX_INPROC_SERVER);
    if (FAILED(hr)) return hr;

    //Create the property bag.
    CComPtr<IPropertyBag> pRegBag;
    hr = pCreateRegBag->Create(HKEY_CURRENT_USER,
        OLESTR("SOFTWARE\\Microsoft\\MSVidCtl"), 0, KEY_READ,
        IID_IPropertyBag, reinterpret_cast<void**>(&pRegBag));
    if (FAILED(hr)) return hr;

    // Read the default tune request from the property bag.
    CComVariant var;
    hr = pRegBag->Read(OLESTR("DefaultTuneRequest"), &var, NULL);
    if (FAILED(hr)) return hr;
    
    // Make sure we got a tune request object.
    CComQIPtr<ITuneRequest> pTune;
    switch (var.vt)
    {
    case VT_UNKNOWN:
        pTune = var.punkVal;
        break;
    case VT_DISPATCH:
        pTune = var.pdispVal;
        break;
    }
    if (pTune)
    {
        *ppTuneReq = pTune.Detach();
        return S_OK;
    }
    return E_FAIL; 
}

See Also

• ICreatePropBagOnRegKey Interface