Custom Guide Store Objects (C++)

This topic applies to Windows XP Home Edition and Windows XP Professional only.

The Guide Store is fully extensible. Applications can define their own object types and store these in the repository.

Custom objects can be generic objects that do not have unique methods or data. To create a collection of such objects, first retrieve a top-level collection of objects by calling IGuideStore::get_Objects. You can now add objects to this collection by calling IObjects::get_AddNew.

A generic object is not useful until you attach data to it, which can be done by adding metaproperties. To associate metaproperties with an object, retrieve the metaproperties of the generic object by using IGuideStore::get_MetaPropertiesOf. Add an existing MetaProperty object to this collection by using IMetaProperties::Add, or create a new, initialized MetaProperty by using IMetaProperties::get_AddNew.

The following sample code creates a generic object to represent a writer, and assigns the writer's name as a metaproperty. For simplicity, error-checking is omitted.

void MakeNewWriter(VARIANT varName)
{
    HRESULT hr;
 
  // Create or retrieve the MetaPropertyType.
 
  IMetaPropertyType* pMPType;
  IMetaPropertySets* pMPSets;
  hr = g_pGuideStore->get_MetaPropertySets(&pMPSets);
  hr = pMPSets->get_Lookup(_bstr_t("Writer.Name"), &pMPType);
 
  // Create a metaproperty of that type. If you don't need to
  // ensure that the new generic object is unique, you can skip
  // this step and add the metaproperty to the object later by 
  // using IMetaProperties::get_AddNew instead of 
  // IMetaProperties::Add.
  
  IMetaProperty* pMP;
  hr = pMPType->get_New(0, varName, &pMP);
 
  // Get the collection of all objects.
 
  IObjects* pAllObjects;
  hr = g_pGuideStore->get_Objects(&pAllObjects);

  // See if an object with the metaproperty already exists.

  IObjects* pMatchingObjects;
  hr = pAllObjects->get_ItemsWithMetaProperty(
          pMP, &pMatchingObjects);
  long count;
  hr = pMatchingObjects->get_Count(&count);
  pMatchingObjects->Release();

  // If it doesn't, create it and give it the metaproperty.

  if (count == 0)
  {
    // Create a generic object.
 
    IUnknown* pUnkWriter;
    hr = pAllObjects->get_AddNew(&pUnkWriter);
 
    // Get a collection of the metaproperties of the new object.
    // This is an empty collection.
    
    IMetaProperties* pMPs;
    hr = g_pGuideStore->get_MetaPropertiesOf(pUnkWriter, &pMPs);
      pUnkWriter->Release();

    // Add the writer's name to the object's collection 
    // of metaproperties.
 
    hr = pMPs->Add(pMP);
    pMPs->Release();
 
  }
  // Clean up.
 
  pAllObjects->Release();
  pMPType->Release();
  pMP->Release();
  pMPSets->Release();

} 

Custom objects can also be application-defined COM objects. To create a collection of such objects, pass the class GUID (CLSID) to IObjects::get_ItemsWithType. The object must be aggregable, and if it contains persistent data, it must support either IPersistStream or IPersistPropertyBag. If persistence is handled by IPersistPropertyBag, data is stored as metaproperties and can be accessed by standard Guide Store methods. The name of the MetaPropertySet is the CLSID of the object, and the name of the MetaPropertyType is the name of the property as set by IPropertyBag::Write.

You can also create custom collections for custom objects. To associate the collection class with an object class, register the CLSID of the collection as the "CollectionCLSID" value in the registry key of the object under HKEY_CLASSES_ROOT/CLSID/<clsid>, where <clsid> is the CLSID of the objects in the collection.