Code Examples‎ > ‎HV2 API Explore‎ > ‎

Introduction

This Introduction page of the HV2 API code examples gives an overview of the API calls.
 
See also 

Microsoft.VisualStudio.Help.Runtime.DLL

Once you add a reference to Microsoft.VisualStudio.Help.Runtime.DLL to your .NET project you have full access to the Help Viewer 2 runtime API. Other programming languages can use the registered COM interface. This DLL is installed only with Visual Studio 11.

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.

ICatalog

The main API classes are Catalog (Interface ICatalog) used to Open & Close Help Catalogs.
  • void Open(string path, string[] prioritizedLocales)
  • void OpenMshx(string path)  
  • void Close()  
  • string ContentPath { get; }  
  • bool IsOpen { get; }
  • ICatalogReadWriteLock GetReadWriteLock(string catalogPath)  
  • int IsLanguageSupportAvailable(string lang)

ICatalogRead

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.

Comments