feuilles de propriétés Utilisateurs et ordinateurs Active Directory

Le composant logiciel enfichable MMC Utilisateurs et ordinateurs Active Directory est conçu pour afficher une feuille de propriétés pour différents objets dans un serveur Active Directory. La feuille de propriétés contient une ou plusieurs pages utilisées pour afficher et modifier des données d’objet. Différents types d’objets ont différents ensembles de pages affichés pour eux. Le composant logiciel enfichable MMC Utilisateurs et ordinateurs Active Directory permet également aux fournisseurs tiers d’ajouter des pages personnalisées à la feuille de propriétés pour un type spécifique d’objet. Pour plus d’informations, consultez Pages de propriétés à utiliser avec les spécificateurs d’affichage.

Certaines applications, autres que le composant logiciel enfichable MMC Utilisateurs et ordinateurs Active Directory, doivent fournir à l’utilisateur la possibilité d’afficher et de modifier les attributs d’un objet dans un serveur Active Directory. L’application peut implémenter ses propres feuilles de propriétés, mais il est préférable d’offrir une interface utilisateur cohérente pour réduire la confusion et le temps d’apprentissage. Heureusement, le composant logiciel enfichable MMC Utilisateurs et ordinateurs Active Directory permet à toute application OLE COM d’afficher une feuille de propriétés pour un objet identique à la feuille de propriétés qui serait affichée par le composant logiciel enfichable MMC Utilisateurs et ordinateurs Active Directory pour le même Objet.

Pour plus d’informations et un exemple de code qui héberge une feuille de propriétés Utilisateurs et ordinateurs Active Directory, consultez l’exemple PropSheetHost dans le Kit de développement logiciel (SDK) de plateforme.

Public de développeurs

Cette documentation suppose que le lecteur est familiarisé avec l’opération COM et le développement de composants à l’aide de C++. Actuellement, il n’est pas possible de créer une extension de feuille de propriétés Active Directory à l’aide de Visual Basic.

Hébergement d’une feuille de propriétés Utilisateurs et ordinateurs Active Directory

Pour afficher une feuille de propriétés pour un objet dans un serveur Active Directory

1. Créez une fenêtre qui peut être utilisée pour traiter les messages. Il peut s’agir d’une fenêtre existante ou d’une fenêtre à usage spécial. C’est ce qu’on appelle la fenêtre masquée.

2. Créez un objet OLE COM dérivé d’IDataObject. Cet objet de données doit prendre en charge les formats de données suivants :

   • CFSTR_DSOBJECTNAMES Ce format de données contient un DSOBJECTNAMES qui identifie l’objet auquel la feuille de propriétés s’applique. Lors de l’hébergement d’une feuille de propriétés, les membres les plus significatifs de la structure DSOBJECTNAMES sont affichés dans la liste suivante.

     clsidNamespace Réservés au. Définissez cette valeur sur un GUID pour votre application ici au cas où il sera utilisé à l’avenir.

     aObjects Contient un tableau de structures DSBOJECT . Chaque structure DSBOJECT représente un objet de répertoire unique. Le membre cItems contient le nombre d’éléments dans le tableau. Seul le premier objet de ce tableau est utilisé. Les autres objets sont ignorés.

   • CFSTR_DSDISPLAYSPECOPTIONS Ce format de données contient une structure DSDISPLAYSPECOPTIONS qui contient des données qui seront utilisées par les pages de propriétés, telles que l’emplacement à partir duquel charger les pages de propriétés, le serveur et les informations d’identification à utiliser, etc. Les membres les plus importants de DSDISPLAYSPECOPTIONS sont indiqués dans la liste suivante.

     offsetAttribPrefix La chaîne de préfixe d’attribut détermine où la liste des pages de propriétés est obtenue. Celui-ci doit contenir l’une des chaînes suivantes.

     Chaîne de préfixe d’attribut	Description
     « admin »	Les pages de propriétés sont chargées à partir de l’attribut adminPropertyPages .
     « shell »	Les pages de propriétés sont chargées à partir de l’attribut shellPropertyPages .

   • CFSTR_DS_PROPSHEETCONFIG Ce format de données contient une structure PROPSHEETCFG qui contient des données d’hôte de feuille de propriétés. Lors de l’hébergement d’une feuille de propriétés, les membres les plus importants de la structure PROPSHEETCFG contiennent les données affichées dans la liste suivante.

     lNotifyHandle Doit être égal à zéro. hwndParentSheet Contient le handle de la fenêtre pour recevoir des messages WM_ADSPROP_NOTIFY_CHANGE lorsque quelque chose dans l’une des pages change et est appliqué. Peut être NULL si ce message n’est pas souhaité.

     hwndHidden Contient le handle de la fenêtre pour recevoir des messages WM_DSA_SHEET_CREATE_NOTIFY et WM_DSA_SHEET_CLOSE_NOTIFY . Définissez cette valeur sur le handle de votre fenêtre masquée.

     wParamSheetClose Contient un identificateur défini par l’application qui est retourné dans le wParam dans le message WM_DSA_SHEET_CLOSE_NOTIFY . Si ce membre est égal à zéro, le message WM_DSA_SHEET_CLOSE_NOTIFY n’est pas publié dans la fenêtre masquée.

3. Créez une instance de l’objet CLSID_DsPropertyPages et obtenez l’interface IShellExtInit pour l’objet . Il est également possible de dupliquer le comportement de l’objet CLSID_DsPropertyPages . Pour plus d’informations, consultez Dupliquer le comportement de l’objet CLSID_DsPropertyPages.

4. Initialisez l’objet CLSID_DsPropertyPages en appelant la méthode IShellExtInit::Initialize . Les paramètres pidlFolder et hkeyProgID ne sont pas utilisés dans cette méthode. Le paramètre pdtobj est le pointeur vers l’objet de données créé à l’étape 2. Lorsque la méthode IShellExtInit::Initialize est appelée, l’objet CLSID_DsPropertyPages enregistre une référence à l’objet de données.

5. Obtenez l’interface IShellPropSheetExt pour l’objet CLSID_DsPropertyPages et appelez la méthode IShellPropSheetExt::AddPages . Le paramètre lpfnAddPage est l’adresse d’une fonction de rappel que vous devez implémenter. Le format de cette fonction est illustré ci-dessous. Si la fonction de rappel est déclarée en tant que membre d’une classe C++, la fonction de rappel doit être déclarée comme statique. Le paramètre lParam est une valeur définie par l’application qui peut être utilisée pour identifier l’objet qui implémente la fonction de rappel. Lorsque la méthode IShellPropSheetExt::AddPages est appelée, l’objet CLSID_DsPropertyPages obtient les données de l’objet de données et énumère les pages de propriétés inscrites pour les spécificateurs d’affichage de l’objet. L’objet CLSID_DsPropertyPages énumère ensuite les objets de page de propriétés, en appelant la méthode IShellPropSheetExt::AddPages de chaque objet.

   BOOL CALLBACK AddPagesCallback(HPROPSHEETPAGE, LPARAM)
   

6. Chaque page ajoutée par les objets de page de propriétés entraîne l’appel de votre fonction de rappel avec le handle de la page de propriétés et la valeur définie par l’application. Votre fonction de rappel doit stocker chaque handle de page de propriétés passé. Lorsque la méthode IShellPropSheetExt::AddPages de l’objet CLSID_DsPropertyPages est retournée, toutes les pages ont été ajoutées via votre fonction de rappel.

7. Renseignez une structure PROPSHEETHEADER pour afficher la feuille de propriétés. Le membre phpage reçoit un pointeur vers un tableau de descripteurs de page qui ont été collectés par votre fonction de rappel. Le membre nPages reçoit le nombre de pages dans le tableau de handles de page.

8. Affichez la feuille de propriétés en appelant la fonction PropertySheet .

Si les données d’une page sont modifiées et que l’utilisateur clique sur les boutons OK ou Appliquer , la fenêtre identifiée par le membre hwndParentSheet de la structure PROPSHEETCFG reçoit un message WM_ADSPROP_NOTIFY_CHANGE . Ce message est strictement une notification et ne nécessite aucune action spécifique.

Lorsque la page est fermée, la fenêtre identifiée par le membre hwndHidden de la structure PROPSHEETCFG reçoit un message WM_DSA_SHEET_CLOSE_NOTIFY . Ce message est strictement une notification et ne nécessite aucune action spécifique à effectuer.

Dans certains cas, les feuilles de propriétés existantes doivent afficher une feuille de propriétés secondaire. Par exemple, si vous affichez la feuille de propriétés d’un objet utilisateur et que vous sélectionnez la page Membre de , une liste de groupes dont l’utilisateur est membre s’affiche. Si vous double-cliquez sur l’un de ces groupes dans la liste, la feuille des propriétés de ce groupe s’affiche. La feuille de propriétés primaire n’affiche pas seule la feuille secondaire. Il demande à l’hôte d’afficher la feuille secondaire en envoyant un message WM_DSA_SHEET_CREATE_NOTIFY à la fenêtre identifiée par le membre hwndHidden de la structure PROPSHEETCFG . Le wParam du message WM_DSA_SHEET_CREATE_NOTIFY est un pointeur vers une structure DSA_SEC_PAGE_INFO qui contient des informations sur la feuille de propriétés secondaire et l’objet qu’elle représente. En réponse à ce message, l’hôte de la feuille de propriétés doit afficher la feuille de propriétés secondaire de la même manière que celle indiquée ci-dessus. Après avoir traité le message WM_DSA_SHEET_CREATE_NOTIFY , le récepteur de message doit libérer la structure DSA_SEC_PAGE_INFO en passant la valeur wParam à la fonction LocalFree .

Duplication du comportement de l’objet CLSID_DsPropertyPages

Pour dupliquer le comportement de l’objet CLSID_DsPropertyPages

1. Énumérez les valeurs dans l’attribut adminPropertyPages ou shellPropertyPages pour le spécificateur d’affichage pour la classe d’objet. Chaque valeur est une chaîne qui contient un nombre, suivi d’une virgule, suivi de la représentation sous forme de chaîne de l’identificateur de classe de l’extension de page de propriétés. Pour plus d’informations sur le format des pages de propriétés affichant les valeurs du spécificateur, consultez Inscription de l’objet COM de page de propriétés dans un spécificateur d’affichage.
2. Convertissez chaque chaîne d’identificateur de classe en CLSID à l’aide de la fonction CLSIDFromString .
3. Triez les identificateurs de classe d’extension par le nombre qui précède chaque chaîne d’identificateur de classe dans la valeur d’attribut. Si deux nombres sont identiques, triez les identificateurs de classe dans l’ordre dans lequel les valeurs d’attribut sont obtenues à partir du serveur Active Directory.
4. Énumérez les identificateurs de classe d’extension, en créant une instance de chaque extension.
5. Pour chaque extension, dans l’ordre trié ci-dessus, appelez IShellExtInit::Initialize de l’extension avec les mêmes informations que celles décrites à l’étape 4 de la procédure Hébergement d’une feuille de propriétés Utilisateurs et ordinateurs Active Directory.
6. Pour chaque extension, dans l’ordre trié ci-dessus, appelez iShellPropSheetExt::AddPages de l’extension avec les mêmes informations que celles décrites à l’étape 5 de la procédure Hébergement d’une feuille de propriétés Utilisateurs et ordinateurs Active Directory.

Si possible, utilisez l’objet CLSID_DsPropertyPages pour créer les pages plutôt que de le faire manuellement. Le CLSID_DsPropertyPages a été optimisé et gère correctement les cas d’échec, par exemple lorsqu’aucun spécificateur d’affichage n’est disponible pour les paramètres régionaux actuels. En outre, l’objet CLSID_DsPropertyPages peut changer à l’avenir, ce qui signifie que vos feuilles de propriétés peuvent ne pas correspondre exactement à celles affichées par le composant logiciel enfichable MMC Utilisateurs et ordinateurs Active Directory.

Éléments de programmation spéciaux

Actuellement, les éléments de programmation suivants ne sont pas définis dans un fichier d’en-tête publié. Pour utiliser ces éléments, vous devez les définir vous-même dans le format exact indiqué dans la page de référence particulière.

• CFSTR_DS_PROPSHEETCONFIG
• PROPSHEETCFG
• WM_DSA_SHEET_CLOSE_NOTIFY
• WM_DSA_SHEET_CREATE_NOTIFY
• DSA_SEC_PAGE_INFO

Exemple de code

L’exemple de code C++ suivant montre un moyen sûr de définir ces éléments qui continueront à fonctionner même si ces éléments sont définis dans un fichier d’en-tête publié à l’avenir.

#ifndef CFSTR_DS_PROPSHEETCONFIG
    #define CFSTR_DS_PROPSHEETCONFIG_W L"DsPropSheetCfgClipFormat"
    #define CFSTR_DS_PROPSHEETCONFIG_A "DsPropSheetCfgClipFormat"

    #ifdef UNICODE
        #define CFSTR_DS_PROPSHEETCONFIG CFSTR_DS_PROPSHEETCONFIG_W
    #else
        #define CFSTR_DS_PROPSHEETCONFIG CFSTR_DS_PROPSHEETCONFIG_A
    #endif //UNICODE
#endif //CFSTR_DS_PROPSHEETCONFIG


#ifndef WM_ADSPROP_SHEET_CREATE
    #define WM_ADSPROP_SHEET_CREATE (WM_USER + 1108)
#endif


#ifndef WM_DSA_SHEET_CREATE_NOTIFY
    #define WM_DSA_SHEET_CREATE_NOTIFY (WM_USER + 6)
#endif


#ifndef WM_DSA_SHEET_CLOSE_NOTIFY
    #define WM_DSA_SHEET_CLOSE_NOTIFY (WM_USER + 5) 
#endif


#ifndef DSA_SEC_PAGE_INFO
    typedef struct _DSA_SEC_PAGE_INFO
    {
        HWND    hwndParentSheet;
        DWORD   offsetTitle;
        DSOBJECTNAMES dsObjectNames;
    } DSA_SEC_PAGE_INFO, *PDSA_SEC_PAGE_INFO;
#endif //DSA_SEC_PAGE_INFO

#ifndef PROPSHEETCFG
    typedef struct _PROPSHEETCFG
    {  
        LONG_PTR lNotifyHandle;  
        HWND hwndParentSheet;  
        HWND hwndHidden;  
        WPARAM wParamSheetClose;
    } PROPSHEETCFG, *PPROPSHEETCFG;
#endif //PROPSHEETCFG