IRunningObjectTable::Register-Methode (objidl.h)
Registriert ein Objekt und seinen identifizierenden Moniker in der ausgeführten Objekttabelle (ROT).
Syntax
HRESULT Register(
[in] DWORD grfFlags,
[in] IUnknown *punkObject,
[in] IMoniker *pmkObjectName,
[out] DWORD *pdwRegister
);
Parameter
[in] grfFlags
Gibt an, ob der Verweis des ROT auf punkObject schwach oder stark ist, und steuert den Zugriff auf das Objekt über seinen Eintrag in der ROT. Weitere Informationen finden Sie im Abschnitt Hinweise.
[in] punkObject
Ein Zeiger auf das Objekt, das als ausgeführt registriert wird.
[in] pmkObjectName
Ein Zeiger auf den Moniker, der punkObject identifiziert.
[out] pdwRegister
Ein Bezeichner für diesen ROT-Eintrag, der in nachfolgenden Aufrufen von IRunningObjectTable::Revoke oder IRunningObjectTable::NoteChangeTime verwendet werden kann. Der Aufrufer kann für diesen Parameter nicht NULL angeben. Wenn ein Fehler auftritt, wird *pdwRegister auf 0 (null) festgelegt.
Rückgabewert
Diese Methode kann die Standardrückgabewerte E_INVALIDARG und E_OUTOFMEMORY sowie die folgenden Werte zurückgeben.
| Rückgabecode | BESCHREIBUNG |
|---|---|
|
Die Methode wurde erfolgreich abgeschlossen. |
|
Das Moniker/Objekt-Paar wurde erfolgreich registriert, aber ein anderes Objekt (möglicherweise dasselbe Objekt) wurde bereits mit demselben Moniker registriert. |
Hinweise
Diese Methode registriert einen Zeiger auf ein Objekt unter einem Moniker, der das Objekt identifiziert. Der Moniker wird als Schlüssel verwendet, wenn die Tabelle mit IRunningObjectTable::GetObject durchsucht wird.
Wenn ein Objekt registriert wird, ruft rot immer AddRef für das Objekt auf. Bei einer schwachen Registrierung (ROTFLAGS_REGISTRATIONKEEPSALIVE nicht festgelegt) gibt rot das Objekt frei, wenn der letzte starke Verweis auf das Objekt freigegeben wird. Bei einer starken Registrierung (ROTFLAGS_REGISTRATIONKEEPSALIVE festgelegt) verhindert rot, dass das Objekt zerstört wird, bis die Registrierung des Objekts explizit widerrufen wird.
Ein Server, der entweder als LocalService oder RunAs registriert ist, kann das ROTFLAGS_ALLOWANYCLIENT-Flag in seinem Aufruf von Register festlegen, damit jeder Client eine Verbindung mit ihm herstellen kann. Ein Server, der dieses Bit festlegt, muss seinen ausführbaren Namen im Abschnitt AppID der Registrierung aufweisen, der auf die AppID für die ausführbare Datei verweist. Ein "Activateor"-Server (nicht als LocalService oder RunAs registriert) darf dieses Flag in seinem Aufruf von Register nicht festlegen. Ausführliche Informationen zum Installieren von Diensten finden Sie unter Installieren als Dienstanwendung.
Wenn Sie ein zweites Objekt mit demselben Moniker registrieren oder dasselbe Objekt erneut mit demselben Moniker registrieren, wird ein zweiter Eintrag in der ROT-Datei erstellt. In diesem Fall gibt Register MK_S_MONIKERALREADYREGISTERED zurück. Jeder Aufruf von Register muss durch einen Aufruf von IRunningObjectTable::Revoke abgeglichen werden, da selbst doppelte Einträge unterschiedliche pdwRegister-Bezeichner aufweisen. Ein Problem bei doppelten Registrierungen besteht darin, dass es keine Möglichkeit gibt, zu bestimmen, welches Objekt zurückgegeben wird, wenn der Moniker in einem nachfolgenden Aufruf von IRunningObjectTable::IsRunning angegeben wird.
Hinweise für Anrufer
Wenn Sie ein Monikeranbieter sind (d. h., Sie geben Moniker aus, die Ihre Objekte identifizieren, um sie für andere zugänglich zu machen), müssen Sie die Register-Methode aufrufen, um Ihre Objekte zu registrieren, wenn sie mit der Ausführung beginnen. Sie müssen diese Methode auch aufrufen, wenn Sie Ihre Objekte umbenennen, während sie geladen werden.Der am häufigsten verwendete Monikeranbieter ist eine Verbunddokument-Linkquelle. Dies umfasst Serveranwendungen, die das Verknüpfen mit ihren Dokumenten (oder Teilen eines Dokuments) unterstützen, und Containeranwendungen, die das Verknüpfen von Einbettungen in ihre Dokumente unterstützen. Serveranwendungen, die verknüpfungen nicht unterstützen, können auch rot verwenden, um mit Containeranwendungen zusammenzuarbeiten, die das Verknüpfen mit Einbettungen unterstützen.
Wenn Sie eine Serveranwendung schreiben, sollten Sie ein Objekt bei rot registrieren, wenn die Ausführung beginnt, in der Regel in Ihrer Implementierung von IOleObject::D oVerb. Das Objekt muss unter seinem vollständigen Moniker registriert werden, was das Abrufen des Monikers des Containerdokuments mithilfe von IOleClientSite::GetMoniker erfordert. Sie sollten auch das Objekt in Ihrer Implementierung von IOleObject::SetMoniker widerrufen und neu registrieren, das aufgerufen wird, wenn das Containerdokument umbenannt wird.
Wenn Sie eine Containeranwendung schreiben, die das Verknüpfen mit Einbettungen unterstützt, sollten Sie Ihr Dokument beim Laden bei rot registrieren. Wenn Ihr Dokument umbenannt wird, sollten Sie es widerrufen und erneut bei rot registrieren und IOleObject::SetMoniker für alle eingebetteten Objekte im Dokument aufrufen, um ihnen die Möglichkeit zu geben, sich selbst erneut zu registrieren.
Objekte, die im ROT registriert sind, müssen explizit widerrufen werden, wenn das Objekt nicht mehr ausgeführt wird oder sich sein Moniker ändert. Dieser Widerruf ist wichtig, da es für das System keine Möglichkeit gibt, Einträge automatisch aus dem ROT zu entfernen. Sie müssen den Bezeichner zwischenspeichern, der über pdwRegister geschrieben wird, und ihn in einem Aufruf von IRunningObjectTable::Revoke verwenden, um die Registrierung zu widerrufen. Bei einer starken Registrierung wird ein starker Verweis freigegeben, wenn die Objektregistrierung widerrufen wird.
Wenn ab Windows Server 2003 veraltete Einträge aufgrund unerwarteter Serverprobleme in der ROT-Datei verbleiben, entfernt COM diese veralteten Einträge automatisch aus dem ROT.
Die Systemimplementierung von Register ruft IMoniker::Reduce für den parameter pmkObjectName auf, um sicherzustellen, dass der Moniker vor der Registrierung vollständig reduziert wird. Wenn ein Objekt durch mehr als einen vollständig reduzierten Moniker bekannt ist, sollte es unter allen solchen Monikern registriert werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | objidl.h |