hojas de propiedades de Usuarios y equipos de Active Directory

Artículo
06/13/2023

El complemento MMC de Usuarios y equipos de Active Directory está diseñado para mostrar una hoja de propiedades para varios objetos en un servidor de Active Directory. La hoja de propiedades contiene una o varias páginas que se usan para ver y modificar datos de objeto. Los distintos tipos de objeto tienen diferentes conjuntos de páginas que se muestran para ellos. El complemento MMC de Usuarios y equipos de Active Directory también permite a los proveedores de terceros agregar páginas personalizadas a la hoja de propiedades para un tipo específico de objeto. Para obtener más información, vea Páginas de propiedades para su uso con especificadores de pantalla.

Algunas aplicaciones, aparte del complemento MMC de Usuarios y equipos de Active Directory, deben proporcionar al usuario la vista de capacidad y editar atributos de un objeto en un servidor de Active Directory. La aplicación podría implementar sus propias hojas de propiedades, pero es mejor ofrecer una interfaz de usuario coherente para reducir el tiempo de confusión y aprendizaje. Afortunadamente, el complemento MMC de Usuarios y equipos de Active Directory permite que cualquier aplicación OLE COM muestre una hoja de propiedades para un objeto que sea idéntico a la hoja de propiedades que mostraría el complemento MMC de Usuarios y equipos de Active Directory para el mismo objeto.

Para obtener más información y un ejemplo de código que hospeda una hoja de propiedades de Usuarios y equipos de Active Directory, vea el ejemplo PropSheetHost en el Kit de desarrollo de software (SDK) de plataforma.

Audiencia de los desarrolladores

En esta documentación se supone que el lector está familiarizado con el desarrollo de componentes y operaciones COM mediante C++. Actualmente, no es posible crear una extensión de hoja de propiedades de Active Directory mediante Visual Basic.

Hospedar una hoja de propiedades de Usuarios y equipos de Active Directory

Para mostrar una hoja de propiedades para un objeto en un servidor de Active Directory

Cree una ventana que se pueda usar para procesar mensajes. Puede ser una ventana existente o una ventana de propósito especial. Esto se conoce como la ventana oculta.

Cree un objeto COM OLE derivado de IDataObject. Este objeto de datos debe admitir los siguientes formatos de datos:

CFSTR_DSOBJECTNAMES Este formato de datos contiene un DSOBJECTNAMES que identifica el objeto al que se aplica la hoja de propiedades. Al hospedar una hoja de propiedades, los miembros más significativos de la estructura DSOBJECTNAMES se muestran en la lista siguiente.

clsidNamespace Reservados. Establézcalo en un GUID para la aplicación aquí en caso de que se use en el futuro.

aObjects Contiene una matriz de estructuras DSBOJECT . Cada estructura DSBOJECT representa un único objeto de directorio. El miembro cItems contiene el número de elementos de la matriz. Solo se usa el primer objeto de esta matriz. Se omiten otros objetos.

CFSTR_DSDISPLAYSPECOPTIONS Este formato de datos contiene una estructura DSDISPLAYSPECOPTIONS que contiene datos que usarán las páginas de propiedades, como dónde cargar las páginas de propiedades, el servidor y las credenciales que se van a usar, etc. Los miembros más significativos de DSDISPLAYSPECOPTIONS se muestran en la lista siguiente.

offsetAttribPrefix La cadena de prefijo de atributo determina dónde se obtiene la lista de páginas de propiedades. Debe contener una de las cadenas siguientes.

Cadena de prefijo de atributo	Descripción
"admin"	Las páginas de propiedades se cargan desde el atributo adminPropertyPages .
"shell"	Las páginas de propiedades se cargan desde el atributo shellPropertyPages .

CFSTR_DS_PROPSHEETCONFIG Este formato de datos contiene una estructura PROPSHEETCFG que contiene datos de host de hoja de propiedades. Al hospedar una hoja de propiedades, los miembros más significativos de la estructura PROPSHEETCFG contienen los datos que se muestran en la lista siguiente.

lNotifyHandle Debe ser cero. hwndParentSheet Contiene el identificador de la ventana que se va a recibir WM_ADSPROP_NOTIFY_CHANGE mensajes cuando cambia algo en una de las páginas y se aplica. Puede ser NULL si no se desea este mensaje.

hwndHidden Contiene el identificador de la ventana para recibir WM_DSA_SHEET_CREATE_NOTIFY y WM_DSA_SHEET_CLOSE_NOTIFY mensajes. Establézcalo en el identificador de la ventana oculta.

wParamSheetClose Contiene un identificador definido por la aplicación que se devuelve en wParam en el mensaje WM_DSA_SHEET_CLOSE_NOTIFY . Si este miembro es cero, el mensaje WM_DSA_SHEET_CLOSE_NOTIFY no se publicará en la ventana oculta.

Cree una instancia del objeto CLSID_DsPropertyPages y obtenga la interfaz IShellExtInit para el objeto. También es posible duplicar el comportamiento del objeto CLSID_DsPropertyPages . Para obtener más información, vea Duplicar el comportamiento del objeto CLSID_DsPropertyPages.
Inicialice el objeto CLSID_DsPropertyPages llamando al método IShellExtInit::Initialize . Los parámetros pidlFolder y hkeyProgID no se usan en este método. El parámetro pdtobj es el puntero al objeto de datos creado en el paso 2. Cuando se llama al método IShellExtInit::Initialize , el objeto CLSID_DsPropertyPages guardará una referencia al objeto de datos.
Obtenga la interfaz IShellPropSheetExt para el objeto CLSID_DsPropertyPages y llame al método IShellPropSheetExt::AddPages . El parámetro lpfnAddPage es la dirección de una función de devolución de llamada que debe implementar. A continuación se muestra el formato de esta función. Si la función de devolución de llamada se declara como miembro de una clase de C++, la función de devolución de llamada debe declararse como estática. El parámetro lParam es un valor definido por la aplicación que se puede usar para identificar el objeto que implementa la función de devolución de llamada. Cuando se llama al método IShellPropSheetExt::AddPages , el objeto CLSID_DsPropertyPages obtendrá los datos del objeto de datos y enumerará las páginas de propiedades registradas para los especificadores de visualización de objetos. A continuación, el objeto CLSID_DsPropertyPages enumerará los objetos de página de propiedades, llamando al método IShellPropSheetExt::AddPages de cada objeto.
```
BOOL CALLBACK AddPagesCallback(HPROPSHEETPAGE, LPARAM)
```
Cada página agregada por los objetos de página de propiedades hará que se llame a la función de devolución de llamada con el identificador de la página de propiedades y el valor definido por la aplicación. La función de devolución de llamada debe almacenar cada identificador de página de propiedades que se pasa. Cuando se devuelve el método IShellPropSheetExt::AddPages del objeto CLSID_DsPropertyPages, todas las páginas se agregarán a través de la función de devolución de llamada.
Rellene una estructura PROPSHEETHEADER para mostrar la hoja de propiedades. El miembro phpage recibe un puntero a una matriz de identificadores de página recopilados por la función de devolución de llamada. El miembro nPages recibe el número de páginas de la matriz de identificadores de página.
Para mostrar la hoja de propiedades, llame a la función PropertySheet .

Si se cambian los datos de cualquier página y se hace clic en los botones Aceptar o Aplicar , la ventana identificada por el miembro hwndParentSheet de la estructura PROPSHEETCFG recibirá un mensaje de WM_ADSPROP_NOTIFY_CHANGE . Este mensaje es estrictamente una notificación y no requiere ninguna acción específica.

Cuando se cierra la página, la ventana identificada por el miembro hwndHidden de la estructura PROPSHEETCFG recibirá un mensaje de WM_DSA_SHEET_CLOSE_NOTIFY . Este mensaje es estrictamente una notificación y no requiere que se realice ninguna acción específica.

En algunos casos, las hojas de propiedades existentes deberán mostrar una hoja de propiedades secundaria. Por ejemplo, si muestra la hoja de propiedades de un objeto de usuario y selecciona la página Miembro de , se mostrará una lista de grupos de los que es miembro el usuario. Si hace doble clic en uno de estos grupos en la lista, se mostrará la hoja de propiedades de ese grupo. La hoja de propiedades principal no muestra la hoja secundaria por sí misma. Solicita que el host muestre la hoja secundaria enviando un mensaje de WM_DSA_SHEET_CREATE_NOTIFY a la ventana identificada por el miembro hwndHidden de la estructura PROPSHEETCFG . WParam del mensaje de WM_DSA_SHEET_CREATE_NOTIFY es un puntero a una estructura de DSA_SEC_PAGE_INFO que contiene información sobre la hoja de propiedades secundaria y el objeto que representa. En respuesta a este mensaje, el host de la hoja de propiedades debe mostrar la hoja de propiedades secundaria de la misma manera que se muestra anteriormente. Después de procesar el mensaje WM_DSA_SHEET_CREATE_NOTIFY , el receptor de mensajes debe liberar la estructura de DSA_SEC_PAGE_INFO pasando el valor wParam a la función LocalFree .

Duplicar el comportamiento del objeto CLSID_DsPropertyPages

Para duplicar el comportamiento del objeto CLSID_DsPropertyPages

Enumere los valores del atributo adminPropertyPages o shellPropertyPages para el especificador de visualización para la clase de objeto. Cada valor es una cadena que contiene un número, seguido de una coma, seguida de la representación de cadena del identificador de clase de la extensión de página de propiedades. Para obtener más información sobre el formato de los valores del especificador de visualización de páginas de propiedades, vea Registrar el objeto COM de la página de propiedades en un especificador de visualización.
Convierta cada cadena de identificador de clase en un CLSID mediante la función CLSIDFromString .
Ordene los identificadores de clase de extensión por el número que precede a cada cadena de identificador de clase en el valor del atributo. Si dos números son idénticos, ordene los identificadores de clase en el orden en que se obtienen los valores de atributo del servidor de Active Directory.
Enumerar los identificadores de clase de extensión, creando una instancia de cada extensión.
Para cada extensión, en el orden ordenado anteriormente, llame al IShellExtInit::Initialize de la extensión con la misma información descrita en el paso 4 del procedimiento Hospedar una hoja de propiedades de Usuarios y equipos de Active Directory.
Para cada extensión, en el orden anterior, llame al IShellPropSheetExt::AddPages de la extensión con la misma información descrita en el paso 5 del procedimiento Hospedar una hoja de propiedades de Usuarios y equipos de Active Directory.

Si es posible, use el objeto CLSID_DsPropertyPages para crear las páginas en lugar de hacerlo manualmente. El CLSID_DsPropertyPages se ha optimizado y controlará correctamente los casos de error, como cuando no haya ningún especificador de visualización disponible para la configuración regional actual. Además, el objeto CLSID_DsPropertyPages puede cambiar en el futuro, lo que significa que las hojas de propiedades pueden no coincidir exactamente con las mostradas por el complemento MMC de Usuarios y equipos de Active Directory.

Elementos de programación especiales

Actualmente, los siguientes elementos de programación no se definen en un archivo de encabezado publicado. Para usar estos elementos, debe definirlos usted mismo en el formato exacto que se muestra en la página de referencia determinada.

Código de ejemplo

En el siguiente ejemplo de código de C++ se muestra una manera segura de definir estos elementos que seguirán funcionando incluso si estos elementos se definen en un archivo de encabezado publicado en el futuro.

#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

Compartir a través de