Guide Store Object Relationships (C++)

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

Many objects in the Guide Store repository have an implicit relationship with one another. For example, programs are related to schedule entries. Every schedule entry is associated with a program, and a program may be associated with one or more schedule entries.

Relationships are defined by metaproperties. In the case of schedule entries and programs, the relationship is defined by the standard MetaPropertyType object named "Program" in the standard MetaPropertySet object named "ScheduleEntry". In the shorthand used throughout the Guide Store, this MetaPropertyType object is called "ScheduleEntry.Program", and it can be obtained by using the IMetaPropertySets::get_Lookup method.

There are two kinds of relationships: direct and inverse. The kind of relationship is determined by the way the data is added to the repository. If object B is added to the collection of objects that are directly related to object A, then object A is inversely related to object B. Nothing in the metaproperty itself defines the direction of the relationship.

In the case of programs and schedule entries, the Program object is directly related to the ScheduleEntry object, and the ScheduleEntry object is inversely related to the Program object.

The following function retrieves a collection of Program objects related to the ScheduleEntry object represented by pEntry. The retrieved collection normally contains a single item, because only one program can be scheduled at a time.

// Assume that g_pGuideStore is the IGuideStore interface of an open
// Guide Store database.
 
IPrograms* ProgramsFromEntry(IScheduleEntry *pEntry)
{
 // Get the MetaPropertyType for the relationship.
 
  IMetaPropertyType* pMPType;
  IMetaPropertySets* pMPSets;
  g_pGuideStore->get_MetaPropertySets(&pMPSets);
  CComBSTR DescTitle= "ScheduleEntry.Program";
  pMPSets->get_Lookup (DescTitle, &pMPType);
 
  // Get the collection of all programs.
 
  IPrograms* pAllPrograms;
  g_pGuideStore->get_Programs(&pAllPrograms);
 
  // Get the IObjects interface.
 
  IObjects* pAllProgramsObj;
  pAllPrograms->QueryInterface(__uuidof(IObjects), (void **) &pAllProgramsObj);
 
  // Find programs related to a schedule entry.
 
  IObjects *pObjRelated;
  IPrograms* pProgRelated;
 
  pAllProgramsObj->get_ItemsRelatedToBy(pEntry, pMPType, &pObjRelated);
  pObjRelated->QueryInterface(__uuidof(IPrograms), 
          (void **) &pProgRelated);
  return pProgRelated;
  
}

Similarly, the following function retrieves a collection of ScheduleEntry objects inversely related to the given Program object.

IScheduleEntries* EntriesFromProgram(IProgram *pProg)
{
 // Get the MetaPropertyType for the relationship.
  
  IMetaPropertyType* pMPType;
  IMetaPropertySets* pMPSets;
  g_pGuideStore->get_MetaPropertySets(&pMPSets);
  CComBSTR DescTitle= "ScheduleEntry.Program";
  pMPSets->get_Lookup (DescTitle, &pMPType);

  // Get the collection of all schedule entries.
  
  IScheduleEntries* pAllScheduleEntries;
  g_pGuideStore->get_ScheduleEntries(&pAllScheduleEntries);
  
  // Get the IObjects interface.
  
  IObjects* pAllScheduleEntriesObj;
  pAllScheduleEntries->QueryInterface(__uuidof(IObjects), 
          (void **) &pAllScheduleEntriesObj);
    
  // Find ScheduleEntries related to a Program.

  IObjects *pObjRelated;
  IScheduleEntries* pEntriesRelated;

  pAllScheduleEntriesObj->get_ItemsInverseRelatedToBy(
          pProg, pMPType, &pObjRelated);
  pObjRelated->QueryInterface(__uuidof(IScheduleEntries), 
          (void **) &pEntriesRelated);
  return pEntriesRelated;
  
}

These examples are solely for the purpose of illustration and are not very useful. For standard relationships, you can retrieve related objects more easily by using methods such as IScheduleEntry::get_Program. Relationships are of more interest for custom objects. For example, you might create a Person object type representing an artist, and define relationships between persons and programs by metaproperties such as "Role.Actor" and "Role.Director". Given a Person object that has been added to the database, you could establish a direct relationship between this artist and a Program object as follows:

1. Create a MetaPropertyType object that defines the relationship, and add this to the database. For example, this could be "Role.Actor". You can create this object, or obtain it if it already exists, by using IMetaPropertySets::get_Lookup, as in the previous example.
2. Obtain the IPrograms interface to the collection of all Program objects in the database by using IGuideStore::get_Programs.
3. Obtain the IObjects interface by using IPrograms::QueryInterface.
4. Using the IObjects interface obtained in the previous step, obtain a collection of all programs that have the specified relationship to the Person object, by passing the IUnknown interfaces of the MetaPropertyType and Person objects to IObjects::get_ItemsRelatedToBy. This collection might be empty, but that doesn't matter.
5. Use IObjects::AddAt to add the Program object to the collection of related objects. This establishes the relationship between the program and the actor, and also establishes an inverse relationship between the actor and the program.

   Note   You cannot establish an inverse relationship in any other way. Attempting to add an item to a collection returned by IObjects::get_ItemsInverseRelatedToBy results in an error.