Working with Guide Store Collections (C++)

Microsoft DirectX 8.1 (C++)

Working with Guide Store Collections (C++)

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

All objects in the Guide Store are organized in top-level collections that can be retrieved by using the following methods:

In addition, many different methods of objects and collections can be used to retrieve collections that are subsets of the top-level collections. For example, you can use IChannelLineup::get_Channels to retrieve a collection of channels associated with a particular channel lineup. The objects in this collection are not new objects; they are simply a subset of the collection retrieved by IGuideStore::get_Channels.

Note Do not use any of the Remove methods to narrow down collections of objects. These methods permanently delete the specified object from the database. To remove unwanted objects from a collection, obtain a subset of the collection.

Most collection objects have a get_ItemsByKey method that can be used to retrieve a sorted collection of objects sharing a common MetaPropertyType. For example, you might use IPrograms::get_ItemsByKey to display a list of programs sorted by title, as shown in the following example, where g_pGuideStore is an initialized IGuideStore interface pointer.

IPrograms* ProgramsByTitle()
{
  IPrograms* pProgs = NULL;
  IPrograms* pProgsByTitle = NULL;
  IMetaPropertySets* pMPSets = NULL;
  IMetaPropertyType* pMPType = NULL;
  HRESULT hr;
 
  // Find the standard MetaPropertyType for the key.
  if (SUCCEEDED(hr = g_pGuideStore->get_MetaPropertySets(&pMPSets)))
  {
    if (SUCCEEDED(hr = pMPSets->get_Lookup(_bstr_t("Description.Title"),
          &pMPType))) 
    {
    // Retrieve all programs.
      if (SUCCEEDED(hr = g_pGuideStore->get_Programs(&pProgs))) 
      {
        // Retrieve programs sorted by title.
        hr = pProgs->get_ItemsByKey(pMPType, NULL, 0, VT_BSTR,
                    &pProgsByTitle);
      }
    }
  }
  if (pProgs) pProgs->Release();
  if (pMPSets) pMPSets->Release();
  if (pMPType) pMPType->Release();

  if (FAILED(hr)) return NULL;
 
  return pProgsByTitle;
}

In most cases, the metaproperties of the type specified by the first parameter to get_ItemsByKey will all contain values of the same variant type. Nonetheless, you must specify the variant type in the fourth parameter. Any objects that have a different variant type in the metaproperty value are not included in the retrieved collection.

All collections that have a get_ItemsByKey method also have a get_ItemWithKey method. This method can be called only on collections created by using get_ItemsByKey. It retrieves the first item whose key metaproperty has a value exactly matching the one specified in the parameter. For example, the following code retrieves a Program object from the collection created in the previous example, where the key metaproperty is of type "Title".

IProgram* pProg;
VARIANT index;
index.vt = VT_BSTR;
index.bstrVal = _bstr_t("Evening News");
 
HRESULT hr = pProgsByTitle->get_ItemWithKey(index, &pProg);

The call to get_ItemWithKey returns E_INVALIDARG if no matching item is found.

The get_ItemWithKey method retrieves only the first matching item. To locate multiple matching items, such as different episodes of a program, you must iterate through the collection by using the get_Item property. Alternatively, you can create a subset of objects that meet a certain condition. For more information, see Comparing Metaproperties (C++).