Méthode IRunningObjectTable ::Register (objidl.h)

Article
08/25/2023

Inscrit un objet et son moniker d’identification dans la table d’objets en cours d’exécution (ROT).

Syntaxe

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

Paramètres

[in] grfFlags

Spécifie si la référence du ROT à punkObject est faible ou forte et contrôle l’accès à l’objet via son entrée dans le ROT. Pour plus d'informations, consultez la section Notes.

Valeur	Signification
ROTFLAGS_REGISTRATIONKEEPSALIVE	Une fois défini, indique une inscription forte pour l’objet.
ROTFLAGS_ALLOWANYCLIENT	Lorsqu’il est défini, n’importe quel client peut se connecter à l’objet en cours d’exécution via son entrée dans le ROT. Lorsqu’il n’est pas défini, seuls les clients de la station de fenêtre qui ont inscrit l’objet peuvent s’y connecter.

[in] punkObject

Pointeur vers l’objet inscrit comme en cours d’exécution.

[in] pmkObjectName

Pointeur vers le moniker qui identifie punkObject.

[out] pdwRegister

Identificateur de cette entrée ROT qui peut être utilisé dans les appels suivants à IRunningObjectTable ::Revoke ou IRunningObjectTable ::NoteChangeTime. L’appelant ne peut pas spécifier NULL pour ce paramètre. Si une erreur se produit, *pdwRegister est défini sur zéro.

Valeur retournée

Cette méthode peut retourner les valeurs de retour standard E_INVALIDARG et E_OUTOFMEMORY, ainsi que les valeurs suivantes.

Code de retour	Description
S_OK	La commande s'est correctement terminée.
MK_S_MONIKERALREADYREGISTERED	La paire moniker/objet a été correctement inscrite, mais un autre objet (peut-être le même objet) a déjà été inscrit avec le même moniker.

Remarques

Cette méthode inscrit un pointeur vers un objet sous un moniker qui identifie l’objet. Le moniker est utilisé comme clé lorsque la table est recherchée avec IRunningObjectTable ::GetObject.

Lorsqu’un objet est inscrit, le ROT appelle toujours AddRef sur l’objet. Pour une inscription faible (ROTFLAGS_REGISTRATIONKEEPSALIVE non définie), le ROT libère l’objet chaque fois que la dernière référence forte à l’objet est publiée. Pour une inscription forte (ROTFLAGS_REGISTRATIONKEEPSALIVE ensemble), le ROT empêche la destruction de l’objet jusqu’à ce que l’inscription de l’objet soit explicitement révoquée.

Un serveur inscrit en tant que LocalService ou RunAs peut définir l’indicateur ROTFLAGS_ALLOWANYCLIENT dans son appel sur Inscrire pour permettre à n’importe quel client de s’y connecter. Un serveur qui définit ce bit doit avoir son nom exécutable dans la section AppID du Registre qui fait référence à l’AppID pour l’exécutable. Un serveur « activer en tant qu’activateur » (non inscrit en tant que LocalService ou RunAs) ne doit pas définir cet indicateur dans son appel à Inscrire. Pour plus d’informations sur l’installation des services, consultez Installation en tant qu’application de service.

L’inscription d’un deuxième objet avec le même moniker ou la réinscription du même objet avec le même moniker crée une deuxième entrée dans le ROT. Dans ce cas, Register retourne MK_S_MONIKERALREADYREGISTERED. Chaque appel à Inscrire doit être mis en correspondance par un appel à IRunningObjectTable ::Revoke , car même les entrées en double ont des identificateurs pdwRegister différents. Un problème avec les inscriptions en double est qu’il n’existe aucun moyen de déterminer quel objet sera retourné si le moniker est spécifié dans un appel ultérieur à IRunningObjectTable ::IsRunning.

Notes aux appelants

Si vous êtes un fournisseur de moniker (c’est-à-dire que vous donnez des monikers identifiant vos objets pour les rendre accessibles à d’autres personnes), vous devez appeler la méthode Register pour inscrire vos objets lorsqu’ils commencent à s’exécuter. Vous devez également appeler cette méthode si vous renommez vos objets pendant leur chargement.

Le type le plus courant de fournisseur de moniker est une source de lien de document composé. Cela inclut les applications serveur qui prennent en charge la liaison à leurs documents (ou parties d’un document) et les applications conteneur qui prennent en charge la liaison à des incorporations dans leurs documents. Les applications serveur qui ne prennent pas en charge la liaison peuvent également utiliser le ROT pour coopérer avec les applications conteneur qui prennent en charge la liaison à des incorporations.

Si vous écrivez une application serveur, vous devez inscrire un objet auprès du ROT lorsqu’il commence à s’exécuter, généralement dans votre implémentation de IOleObject ::D oVerb. L’objet doit être inscrit sous son moniker complet, ce qui nécessite d’obtenir le moniker de son document conteneur à l’aide de IOleClientSite ::GetMoniker. Vous devez également révoquer et réinscrire l’objet dans votre implémentation de IOleObject ::SetMoniker, qui est appelé si le document conteneur est renommé.

Si vous écrivez une application conteneur qui prend en charge la liaison à des incorporations, vous devez inscrire votre document auprès du ROT lors de son chargement. Si votre document est renommé, vous devez le révoquer et le réinscrire auprès du ROT et appeler IOleObject ::SetMoniker pour tous les objets incorporés dans le document afin de leur donner la possibilité de se réinscrire eux-mêmes.

Les objets inscrits dans le ROT doivent être explicitement révoqués lorsque l’objet n’est plus en cours d’exécution ou lorsque son moniker change. Cette révocation est importante, car il n’existe aucun moyen pour le système de supprimer automatiquement les entrées du ROT. Vous devez mettre en cache l’identificateur écrit via pdwRegister et l’utiliser dans un appel à IRunningObjectTable ::Revoke pour révoquer l’inscription. Pour une inscription forte, une référence forte est publiée lorsque l’inscription d’objets est révoquée.

À partir de Windows Server 2003, s’il existe des entrées obsolètes qui restent dans le ROT en raison de problèmes de serveur inattendus, COM supprime automatiquement ces entrées obsolètes du ROT.

L’implémentation de Register par le système appelle IMoniker ::Reduce sur le paramètre pmkObjectName pour s’assurer que le moniker est entièrement réduit avant l’inscription. Si un objet est connu par plusieurs monikers entièrement réduits, il doit être inscrit sous tous ces monikers.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	objidl.h

Voir aussi

IRunningObjectTable

Partager via