Metodo IRunningObjectTable::Register (objidl.h)

Articolo
08/25/2023

Registra un oggetto e il relativo moniker di identificazione nella tabella degli oggetti in esecuzione (ROT).

Sintassi

HRESULT Register(
  [in]  DWORD    grfFlags,
  [in]  IUnknown *punkObject,
  [in]  IMoniker *pmkObjectName,
  [out] DWORD    *pdwRegister
);

Parametri

[in] grfFlags

Specifica se il riferimento del ROT a punkObject è debole o forte e controlla l'accesso all'oggetto tramite la relativa voce nel ROT. Per informazioni dettagliate, vedere la sezione Osservazioni.

Valore	Significato
ROTFLAGS_REGISTRATIONKEEPSALIVE	Se impostato, indica una registrazione complessa per l'oggetto .
ROTFLAGS_ALLOWANYCLIENT	Se impostato, qualsiasi client può connettersi all'oggetto in esecuzione tramite la relativa voce nel ROT. Se non impostata, solo i client nella stazione finestra che hanno registrato l'oggetto possono connettersi.

[in] punkObject

Puntatore all'oggetto registrato come in esecuzione.

[in] pmkObjectName

Puntatore al moniker che identifica punkObject.

[out] pdwRegister

Identificatore per questa voce ROT che può essere utilizzata nelle chiamate successive a IRunningObjectTable::Revoke o IRunningObjectTable::NoteChangeTime. Il chiamante non può specificare NULL per questo parametro. Se si verifica un errore, *pdwRegister è impostato su zero.

Valore restituito

Questo metodo può restituire i valori restituiti standard E_INVALIDARG e E_OUTOFMEMORY, nonché i valori seguenti.

Codice restituito	Descrizione
S_OK	Metodo completato correttamente.
MK_S_MONIKERALREADYREGISTERED	La coppia moniker/oggetto è stata registrata correttamente, ma che un altro oggetto (possibilmente lo stesso oggetto) è già stato registrato con lo stesso moniker.

Commenti

Questo metodo registra un puntatore a un oggetto in un moniker che identifica l'oggetto . Il moniker viene usato come chiave quando viene eseguita la ricerca della tabella con IRunningObjectTable::GetObject.

Quando un oggetto viene registrato, il ROT chiama sempre AddRef sull'oggetto . Per una registrazione debole (ROTFLAGS_REGISTRATIONKEEPSALIVE non impostata), il ROT rilascia l'oggetto ogni volta che viene rilasciato l'ultimo riferimento sicuro all'oggetto. Per una registrazione complessa (ROTFLAGS_REGISTRATIONKEEPSALIVE impostata), il ROT impedisce che l'oggetto venga eliminato definitivamente finché la registrazione dell'oggetto non viene revocata in modo esplicito.

Un server registrato come LocalService o RunAs può impostare il flag di ROTFLAGS_ALLOWANYCLIENT nella chiamata a Register per consentire a qualsiasi client di connettersi. Un'impostazione del server di questo bit deve avere il nome eseguibile nella sezione AppID del Registro di sistema che fa riferimento all'AppID per l'eseguibile. Un server "activate as activator" (non registrato come LocalService o RunAs) non deve impostare questo flag nella chiamata a Register. Per informazioni dettagliate sull'installazione dei servizi, vedere Installazione come applicazione di servizio.

La registrazione di un secondo oggetto con lo stesso moniker o la nuova registrazione dello stesso oggetto con lo stesso moniker, crea una seconda voce nel ROT. In questo caso, Register restituisce MK_S_MONIKERALREADYREGISTERED. Ogni chiamata a Register deve essere abbinata da una chiamata a IRunningObjectTable::Revoke perché anche le voci duplicate hanno identificatori pdwRegister diversi. Un problema con le registrazioni duplicate è che non è possibile determinare quale oggetto verrà restituito se il moniker viene specificato in una chiamata successiva a IRunningObjectTable::IsRunning.

Note ai chiamanti

Se si è un provider di moniker, ovvero si assegnano moniker che identificano gli oggetti per renderli accessibili ad altri utenti, è necessario chiamare il metodo Register per registrare gli oggetti all'avvio dell'esecuzione. È inoltre necessario chiamare questo metodo se si rinominano gli oggetti mentre vengono caricati.

Il tipo più comune di provider di moniker è un'origine di collegamento a documenti composti. Sono incluse le applicazioni server che supportano il collegamento ai documenti (o parti di un documento) e alle applicazioni contenitore che supportano il collegamento a incorporamenti all'interno dei documenti. Le applicazioni server che non supportano il collegamento possono anche usare rot per collaborare con le applicazioni contenitore che supportano il collegamento a incorporamenti.

Se si sta scrivendo un'applicazione server, è necessario registrare un oggetto con il ROT all'inizio dell'esecuzione, in genere nell'implementazione di IOleObject::D oVerb. L'oggetto deve essere registrato con il moniker completo, che richiede il recupero del moniker del documento contenitore usando IOleClientSite::GetMoniker. È anche necessario revocare e registrare nuovamente l'oggetto nell'implementazione di IOleObject::SetMoniker, che viene chiamato se il documento contenitore viene rinominato.

Se si sta scrivendo un'applicazione contenitore che supporta il collegamento agli incorporamenti, è necessario registrare il documento con il ROT quando viene caricato. Se il documento viene rinominato, è necessario revocarlo e registrarlo nuovamente con il ROT e chiamare IOleObject::SetMoniker per tutti gli oggetti incorporati nel documento per offrire loro la possibilità di ripetere la registrazione.

Gli oggetti registrati in ROT devono essere revocati in modo esplicito quando l'oggetto non è più in esecuzione o quando viene modificato il relativo moniker. Questa revoca è importante perché non c'è modo per il sistema di rimuovere automaticamente le voci dal ROT. È necessario memorizzare nella cache l'identificatore scritto tramite pdwRegister e usarlo in una chiamata a IRunningObjectTable::Revoke per revocare la registrazione. Per una registrazione complessa, viene rilasciato un riferimento sicuro quando viene revocata la registrazione degli oggetti.

A partire da Windows Server 2003, se sono presenti voci non aggiornate che rimangono nel ROT a causa di problemi imprevisti del server, COM rimuove automaticamente queste voci non aggiornate dal ROT.

L'implementazione del sistema di Register chiama IMoniker::Reduce nel parametro pmkObjectName per assicurarsi che il moniker venga completamente ridotto prima della registrazione. Se un oggetto è noto da più moniker completamente ridotti, deve essere registrato in tutti questi moniker.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	objidl.h

Vedi anche

IRunningObjectTable

Share via