There is an equivalent interface provided by Windows 8 help (registered in the GAC) called Windows.Help.Runtime.dll
. So you have choice of using the VS 11 help run-time or the Windows 8 help run-time.
CatalogRead (Interface ICatalogRead) gives us access to a catalog's data (Search/Index/TOC/Files etc).
These CatalogRead methods take an open catalog object as their first parameter.
- IStream GetIndexedTopic(ICatalog catalog, string topicId, IHelpFilter filter)
- ITopic GetIndexedTopicDetails(ICatalog catalog, string topicId, IHelpFilter filter)
- IKeywordCollection GetKeywords(ICatalog catalog, [bool useCache = true])
- IStream GetLinkedAsset(ICatalog catalog, string packageName, string path, string locale)
- ITopicCollection GetSearchResults(ICatalog catalog, string query, IHelpFilter filter, SearchOptions options, int pageSize, int pageNumber, out int totalSearchResults)
- ITopicCollection GetTableOfContents(ICatalog catalog, string topicId, IHelpFilter filter, TocReturnDetail returnDetail)
- ITopic GetTopicDetailsForF1Keyword(ICatalog catalog, string[] prioritizedF1Keywords, IHelpFilter filter)
- IStream GetTopicForF1Keyword(ICatalog catalog, string[] prioritizedF1Keywords, IHelpFilter filter)
And that's it. All the other classes and enums (see below) are used by these main API calls.
Simple Example:
This simple example show how straight forward it is to use the HV2 API.
using Microsoft.VisualStudio.Help.Runtime;
...
private Catalog _catalog = new Catalog();
private CatalogRead _catalogRead = new CatalogRead();
// Open an English Catalog
String catalogPath = @"C:\ProgramData\Microsoft\HelpLibrary2\Catalogs\VisualStudio11";
String locale = "en-US";
_catalog.Open(catalogPath, new String[] { locale });
// Get top level TOC topics
ITopicCollection topics = _catalogRead.GetTableOfContents(_catalog, "-1", null, TocReturnDetail.TocRootNodes);
for (int i = 0; i < topics.Count; i++)
{
topics.MoveTo(i);
Topic topic = (Topic) topics.Current;
....
}
// Close catalog
if (_catalog.IsOpen)
_catalog.Close();
MemoryIStream, FileIStream and HelpReader
MemoryIStream, FileIStream and HelpReader are used internally and exposed via COM. Most developers won't use these.
ICatalog.ICatalogReadWriteLock
Object returned by calling ICatalog.GetReadWriteLock(CatalogPath).
Use the object to get or set a catalogs read/write locks.
IHelpFilter, IHelpKeyValuePair
Various ICatalogRead methods expect an IHelpFilter list of IHelpKeyValuePair items.
This is how catalog filtering is achieved. The Key is not case sensitive. A key/value pair may look something like this: "topiclocale","en-US". Just pass in null if filtering is not required.
IKeywordCollection, IKeyword
The ICatalogRead.GetKeywords() call returns an IKeywordCollection collection of Ikeyword items.
ITopicCollection, ITopic
ICatalogRead.GetTableOfContents() & ICatalogRead.GetSearchResults() methods return a collection of ITopic objects.
enum SearchOptions
This is an enumeration used by ICatalogRead.GetSearchResults().
- none=0; // Default processing.
- SearchTermHighlight=1; // Apply highlighting to search hits.
- OrSearchOverride=2; // "OR" search query terms instead of "AND" (the default).
enum TocReturnDetail
This is an enumeration used by ICatalogRead.GetTableOfContents().
- TocChildren=0; // Get only children.
- TocSiblings=1; // Get only siblings.
- TocAncestors=2; // Get only ancestors.
- TocRootNodes=3; // Get only root list.
- TocDescendants=4; // Get only descendants.