| Microsoft DirectX 8.1 (C++) |
All objects in the Guide Store are organized in top-level collections that can be retrieved by using the following properties of the GuideStore object:
In addition, many different properties of objects and collections can be used to retrieve collections that are subsets of the top-level collections. For example, you can use ChannelLineup.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 GuideStore.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 an ItemsByKey method that can be used to retrieve a sorted collection of objects sharing a common MetaPropertyType. For example, you might use Programs.ItemsByKey to display a list of programs sorted by title, as shown in the following Visual Basic example, where g_gs is the initialized GuideStore object.
' Visual Basic
Private Function ProgramsByTitle() As Programs
Dim allPrograms As Programs
Dim mpSets As MetaPropertySets
Dim mpType As MetaPropertyType
' Find the standard MetaPropertyType for the key.
Set mpSets = g_gs.MetaPropertySets
Set mpType = mpSets.Lookup("Description.Title")
' Retrieve the complete collection of programs.
Set allPrograms = g_gs.Programs
' Retrieve a subset, sorted by title.
Set ProgramsByTitle = allPrograms.ItemsByKey(mpType, Nothing, _
0, vbVString)
End Function
The ProgramsByTitle function in the following scripting example returns a collection of programs sorted by title. It also displays the name and description of the first ten items in the unsorted collection of programs, and then does the same for the sorted collection. Assume that myGuideStore is an initialized GuideStore object.
<SCRIPT LANGUAGE = "VBScript">
<!--
Function ProgramsByTitle()
Dim allPrograms
Dim mpSets
Dim mpType
' Find the standard MetaPropertyType for the key.
Set mpSets = myGuideStore.MetaPropertySets
Set mpType = mpSets.Lookup("Description.Title")
' Retrieve the complete collection of programs.
Set allPrograms = myGuideStore.Programs
document.write "<h2>All programs, unsorted</h2>"
for x = 0 to 9
document.write allPrograms.Item(x).Title
document.write "<br>"
document.write allPrograms.Item(x).Description
document.write "<p>"
next
' Retrieve a subset, sorted by title.
Set ProgramsByTitle = allPrograms.ItemsByKey(mpType, Nothing, 0, 8)
document.write "<h2>Programs by title</h2>"
for x = 0 to 9
document.write ProgramsByTitle.Item(x).Title
document.write "<br>"
document.write ProgramsByTitle.Item(x).Description
document.write "<p>"
next
End Function
-->
</SCRIPT>
In most cases, the metaproperties of the type specified by the first parameter to ItemsByKey will all contain values of the same variant type. Nonetheless, you must specify the variant type in the last parameter. Any objects that have a different variant type in the metaproperty value are not included in the retrieved collection.
All collections that have an ItemsByKey property also have an ItemWithKey property. This method can be called only on collections created by using 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".
Dim prog As Program
Set prog = ProgramsByTitle.ItemWithKey("Evening News")
The following script example retrieves the same Program object and displays its description.
<SCRIPT LANGUAGE = "VBScript">
<!--
Dim prog
Set prog = ProgramsByTitle.ItemWithKey("Evening News")
document.write prog.Description
-->
</SCRIPT>
An error is raised if no matching item is found.
The ItemWithKey property 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 Item property. Alternatively, you can create a subset of objects that meet a certain condition. For more information, see Comparing Metaproperties (Visual Basic).