RegisterActiveObject-Funktion (oleauto.h)

Registriert ein -Objekt als aktives Objekt für seine -Klasse.

Syntax

HRESULT RegisterActiveObject(
  IUnknown *punk,
  REFCLSID rclsid,
  DWORD    dwFlags,
  DWORD    *pdwRegister
);

Parameter

punk

Das aktive Objekt.

rclsid

Die CLSID des aktiven Objekts.

dwFlags

Flags, die die Registrierung des Objekts steuern. Mögliche Werte sind ACTIVEOBJECT_STRONG und ACTIVEOBJECT_WEAK.

pdwRegister

Empfängt ein Handle. Dieses Handle muss an RevokeActiveObject übergeben werden, um die aktive status des Objekts zu beenden.

Rückgabewert

Wenn diese Funktion erfolgreich ist, wird S_OK zurückgegeben. Andernfalls wird ein Fehlercode HRESULT zurückgegeben.

Hinweise

Die RegisterActiveObject-Funktion registriert das Objekt, auf das Punk zeigt, als aktives Objekt für die klasse, die durch rclsid gekennzeichnet ist. Die Registrierung bewirkt, dass das Objekt in der ausgeführten Objekttabelle (Running Object Table, ROT) von OLE aufgeführt wird, einer global zugänglichen Nachschlagetabelle, die objekte nachverfolgt, die derzeit auf dem Computer ausgeführt werden. (Weitere Informationen zur Ausgeführten Objekttabelle finden Sie in der COM-Programmiererreferenz.) Der dwFlags-Parameter gibt die Stärke oder Schwäche der Registrierung an, was sich auf die Art und Weise auswirkt, wie das Objekt heruntergefahren wird.

Im Allgemeinen sollten sich ActiveX-Objekte wie folgt verhalten:

• Wenn das Objekt sichtbar ist, sollte es nur als Reaktion auf einen expliziten Benutzerbefehl (z. B. den Befehl Exit im Menü Datei ) oder auf den entsprechenden Befehl eines ActiveX-Clients (Aufrufen der Quit - oder Exit-Methode für das Application-Objekt) heruntergefahren werden.
• Wenn das Objekt nicht sichtbar ist, sollte es nur dann beendet werden, wenn die letzte externe Verbindung mit dem Objekt nicht mehr besteht.

Bei der starken Registrierung wird ein AddRef für das -Objekt ausgeführt, wodurch die Verweisanzahl des Objekts (und des zugeordneten Stubs) in der ausgeführten Objekttabelle erhöht wird. Ein stark registriertes Objekt muss explizit mit RevokeActiveObject aus der Tabelle widerrufen werden. Der Standardwert ist starke Registrierung (ACTIVEOBJECT_STRONG).

Die schwache Registrierung behält einen Zeiger auf das Objekt in der ausgeführten Objekttabelle bei, erhöht jedoch nicht die Verweisanzahl. Wenn also die letzte externe Verbindung mit einem schwach registrierten Objekt verschwindet, gibt OLE den Stub des Objekts frei, und das Objekt selbst ist nicht mehr verfügbar.

Um das gewünschte Verhalten sicherzustellen, berücksichtigen Sie nicht nur die Standardaktionen von OLE, sondern auch Folgendes:

• Obwohl Code ein unsichtbares Objekt erstellen kann, kann das Objekt zu einem späteren Zeitpunkt sichtbar werden. Sobald das Objekt sichtbar ist, sollte es sichtbar und aktiv bleiben, bis es einen expliziten Befehl zum Herunterfahren erhält. Dies kann auftreten, nachdem Verweise aus dem Code nicht mehr vorhanden sind.
• Andere ActiveX-Clients verwenden möglicherweise das -Objekt. Wenn ja, sollte der Code das Herunterfahren des Objekts nicht erzwingen.

Um mögliche Konflikte zu vermeiden, sollten Sie ActiveX-Objekte immer bei ACTIVEOBJECT_WEAK registrieren und bei Bedarf CoLockObjectExternal aufrufen, um sicherzustellen, dass das Objekt aktiv bleibt. CoLockObjectExternal fügt eine starke Sperre hinzu, wodurch verhindert wird, dass die Verweisanzahl des Objekts null erreicht. Ausführliche Informationen zu dieser Funktion finden Sie in der COM-Programmiererreferenz.

In der Regel müssen Objekte CoLockObjectExternal aufrufen, wenn sie sichtbar werden, damit sie aktiv bleiben, bis der Benutzer das Herunterfahren des Objekts anfordert. Im folgenden Verfahren werden die Schritte aufgeführt, die Ihr Code ausführen muss, um ein Objekt ordnungsgemäß herunterzufahren.

So fahren Sie ein aktives Objekt herunter:

1. Wenn das Objekt sichtbar wird, führen Sie den folgenden Aufruf aus, um eine Sperre für den Benutzer hinzuzufügen:

   CoLockObjectExternal(punk, TRUE, TRUE)
   

   Die Sperre bleibt wirksam, bis ein Benutzer explizit das Herunterfahren des Objekts anfordert, z. B. mit einem Befehl "Beenden" oder " Beenden ".

2. Wenn der Benutzer das Herunterfahren des Objekts anfordert, rufen Sie CoLockObjectExternal erneut auf, um die Sperre wie folgt freizugeben:

   CoLockObjectExternal(punk, FALSE, TRUE)
   

3. Rufen Sie RevokeActiveObject auf, um das Objekt inaktiv zu machen.
4. Um alle Verbindungen von Remoteprozessen zu beenden, rufen Sie CoDisconnectObject wie folgt auf:

   CoDisconnectObject(punk,0)
   

   Diese Funktion wird in der COM-Programmiererreferenz ausführlicher beschrieben.

Anforderungen

Anforderung	Wert
Zielplattform	Windows
Kopfzeile	oleauto.h
Bibliothek	OleAut32.lib
DLL	OleAut32.dll

Weitere Informationen

Registrieren des aktiven Objekts mit API-Funktionen

RevokeActiveObject