IDisplayHelp::ShowTopic-Methode (mmc.h)
Die IDisplayHelp::ShowTopic-Methode zeigt das angegebene HTML-Hilfethema in der zusammengeführten MMC-HTML-Hilfedatei an.
Syntax
HRESULT ShowTopic(
[in] LPOLESTR pszHelpTopic
);
Parameter
[in] pszHelpTopic
Ein Zeiger auf eine NULL-endende Zeichenfolge, die das Thema angibt, das in der zusammengeführten MMC-HTML-Hilfedatei angezeigt werden soll. Die Zeichenfolge muss das folgende Format aufweisen:
helpfilename::topicfilename
dabei ist helpfilename der Datei der HTML-Hilfedatei (CHM) des Snap-Ins, die MMC in die MMC-HTML-Hilfesammlungsdatei zusammengeführt hat (dies ist nur der Dateiname, nicht der Pfad zur ursprünglichen HTML-Hilfedatei), und topicfilename ist der interne Pfad zur Themendatei innerhalb der CHM-Datei des Snap-Ins. Der Autor der HTML-Hilfedatei des Snap-Ins bestimmt, ob eine interne Verzeichnisstruktur für die HTML-Themendateien vorhanden ist oder ob sich alle HTML-Themendateien im Stammverzeichnis der CHM-Datei befinden.
Ein Snap-In informiert MMC über seine CHM-Datei in der Implementierung der ISnapinHelp2::GetHelpTopic-Methode .
Wenn das Snap-In beispielsweise die HTML-Hilfedatei mysnapin.chm in die MMC-HTML-Hilfesammlungsdatei und eine HTML-Themendatei mit dem internen Dateipfad htm/help01.htm zusammengeführt würde, hätte die Zeichenfolge die folgende Form:
mysnapin.chm::htm/help01.htm
Wenn sich stattdessen die help01.htm Themendatei im Stammverzeichnis der Hilfedatei mysnapin.chm befindet, sollte die Zeichenfolge die folgende Form aufweisen:
mysnapin.chm::/help01.htm
Die Unterstützung für numerische IDs für Themen ist in Version 1.2 und früher nicht enthalten.
Rückgabewert
Diese Methode kann einen dieser Werte zurückgeben.
Hinweise
Die MMC-Versionen 1.0 und 1.1 erforderten, dass pszHelpTopic der COM-API-Funktion CoTaskMemAlloc zugeordnet wurde, und dass MMC die Zeichenfolge dann freigibt. Dadurch wurde gegen die COM-Regeln für die Zuordnung von In-Parametern verstoßen, die erfordern, dass sie sowohl vom Aufrufer (dem Snap-In) zugeordnet als auch freigegeben werden. In MMC 1.2 und MMC 2.0 ist es nicht mehr erforderlich, dass pszHelpTopicmit CoTaskMemAlloc zugeordnet wird. Der Aufrufer kann jede beliebige Speicherverwaltung verwenden. Wenn der Aufrufer CoTaskMemAlloc verwendet, ist er auch für den Aufruf von CoTaskMemFree verantwortlich, um die Zeichenfolge frei zu geben.
Ein Snap-In kann Kontexthilfe für das ausgewählte Element bereitstellen, indem die MMCN_CONTEXTHELP Benachrichtigung in der IComponent::Notify-Methode behandelt und IDisplayHelp::ShowTopic aufgerufen wird.
Für Eigenschaftenseiten sollte das Snap-In MMCPropertyHelp anstelle von IDisplayHelp::ShowTopic aufrufen. Da ein MMC-Eigenschaftenblatt in der Regel in einem separaten Thread ausgeführt wird, kann die Eigenschaftenseite die IDisplayHelp-Schnittstelle nicht direkt verwenden. Stattdessen kann die Eigenschaftenseite MMCPropertyHelp aus der MMC-Bibliothek aufrufen, um das gleiche Ergebnis zu erzielen. MMCPropertyHelp verwendet den gleichen Themenzeichenfolgenparameter wie IDisplayHelp::ShowTopic und verarbeitet das Marshallen der Anforderung an den Standard MMC-Thread.
Wenn das Snap-In die MMCN_CONTEXTHELP Benachrichtigung verarbeitet, erwartet MMC, dass das Snap-In ein Hilfethema für das ausgewählte Element angibt. Folglich verfügt das Snap-In im Benachrichtigungshandler für die MMCN_CONTEXTHELP-Benachrichtigung über zwei Optionen:
- Sie kann IDisplayHelp::ShowTopic oder MMCPropertyHelp aufrufen, um das Hilfethema anzugeben und dann S_OK zurückzugeben, um den Erfolg anzuzeigen. Beachten Sie, dass das Snap-In nur dann S_OK zurückgeben sollte, wenn es ein Hilfethema angibt. Wenn das Snap-In S_OK ohne Angabe eines Hilfethemas zurückgibt, wird kein Hilfethema angezeigt.
- Es kann S_FALSE an die Benachrichtigung zurückgeben. MMC zeigt dann die Hilfesammlungsdatei mit ausgewähltem MMC-Standardthema an.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows Vista |
| Unterstützte Mindestversion (Server) | Windows Server 2008 |
| Zielplattform | Windows |
| Kopfzeile | mmc.h |
| DLL | Mmcndmgr.dll |