Folhas de propriedades Usuários e Computadores do Active Directory

Artigo
06/13/2023

O snap-in MMC Usuários e Computadores do Active Directory foi projetado para exibir uma folha de propriedades para vários objetos em um servidor do Active Directory. A folha de propriedades contém uma ou mais páginas que são usadas para exibir e modificar dados de objeto. Diferentes tipos de objeto têm diferentes conjuntos de páginas exibidas para eles. O snap-in MMC Usuários e Computadores do Active Directory também permite que fornecedores de terceiros adicionem páginas personalizadas à folha de propriedades de um tipo específico de objeto. Para obter mais informações, consulte Páginas de propriedades para uso com especificadores de exibição.

Alguns aplicativos, além do snap-in MMC Usuários e Computadores do Active Directory, devem fornecer ao usuário a capacidade de exibir e editar atributos para um objeto em um servidor do Active Directory. O aplicativo poderia implementar suas próprias folhas de propriedades, mas é melhor oferecer uma interface de usuário consistente para reduzir a confusão e o tempo de aprendizado. Felizmente, o snap-in MMC Usuários e Computadores do Active Directory permite que qualquer aplicativo OLE COM exiba uma folha de propriedades para um objeto idêntico à folha de propriedades que seria exibida pelo snap-in MMC Usuários e Computadores do Active Directory para o mesmo objeto.

Para obter mais informações e um exemplo de código que hospeda uma folha de propriedades Usuários e Computadores do Active Directory, consulte o exemplo PropSheetHost no Platform Software Development Kit (SDK).

Público-alvo do desenvolvedor

Esta documentação pressupõe que o leitor esteja familiarizado com a operação COM e o desenvolvimento de componentes usando C++. Atualmente, não é possível criar uma extensão de folha de propriedades do Active Directory usando o Visual Basic.

Hospedando uma folha de propriedades Usuários e Computadores do Active Directory

Para exibir uma folha de propriedades de um objeto em um servidor do Active Directory

Crie uma janela que possa ser usada para processar mensagens. Pode ser uma janela existente ou uma janela para fins especiais. Isso é conhecido como a janela oculta.

Crie um objeto OLE COM derivado de IDataObject. Esse objeto de dados deve oferecer suporte aos seguintes formatos de dados:

CFSTR_DSOBJECTNAMES Esse formato de dados contém um DSOBJECTNAMES que identifica o objeto ao qual a folha de propriedades se aplica. Ao hospedar uma folha de propriedades, os membros mais significativos da estrutura DSOBJECTNAMES são mostrados na lista a seguir.

clsidNamespace reservado. Defina isso como um GUID para seu aplicativo aqui, caso ele seja usado no futuro.

aObjects Contém uma matriz de estruturas DSBOJECT . Cada estrutura DSBOJECT representa um único objeto de diretório. O membro cItems contém o número de elementos na matriz. Somente o primeiro objeto nessa matriz é usado. Outros objetos são ignorados.

CFSTR_DSDISPLAYSPECOPTIONS Esse formato de dados contém uma estrutura DSDISPLAYSPECOPTIONS que contém dados que serão usados pelas páginas de propriedades, como de onde carregar as páginas de propriedades, o servidor e as credenciais a serem usadas e assim por diante. Os membros mais significativos das DSDISPLAYSPECOPTIONS são mostrados na lista a seguir.

offsetAttribPrefix A cadeia de caracteres de prefixo de atributo determina onde a lista de páginas de propriedades é obtida. Isso deve conter uma das seguintes cadeias de caracteres.

Cadeia de caracteres de prefixo de atributo	Descrição
"admin"	As páginas de propriedades são carregadas a partir do atributo adminPropertyPages.
"Concha"	As páginas de propriedades são carregadas a partir do atributo shellPropertyPages.

CFSTR_DS_PROPSHEETCONFIG Esse formato de dados contém uma estrutura PROPSHEETCFG que contém dados de host de folha de propriedades. Ao hospedar uma folha de propriedades, os membros mais significativos da estrutura PROPSHEETCFG contêm os dados mostrados na lista a seguir.

lNotifyHandle Deve ser zero. hwndParentSheet Contém o identificador da janela para receber mensagens de WM_ADSPROP_NOTIFY_CHANGE quando algo em uma das páginas é alterado e aplicado. Pode ser NULL se esta mensagem não for desejada.

hwndHidden Contém o identificador da janela para receber mensagens WM_DSA_SHEET_CREATE_NOTIFY e WM_DSA_SHEET_CLOSE_NOTIFY. Defina isso como a alça da janela oculta.

wParamSheetClose Contém um identificador definido pelo aplicativo que é retornado no wParam na mensagem WM_DSA_SHEET_CLOSE_NOTIFY. Se esse membro for zero, a mensagem WM_DSA_SHEET_CLOSE_NOTIFY não será postada na janela oculta.

Crie uma instância do objeto CLSID_DsPropertyPages e obtenha a interface IShellExtInit para o objeto. Também é possível duplicar o comportamento do objeto CLSID_DsPropertyPages . Para obter mais informações, consulte Duplicando o comportamento do objeto CLSID_DsPropertyPages.
Inicialize o objeto CLSID_DsPropertyPages chamando o método IShellExtInit::Initialize. Os parâmetros pidlFolder e hkeyProgID não são usados nesse método. O parâmetro pdtobj é o ponteiro para o objeto de dados criado na Etapa 2. Quando o método IShellExtInit::Initialize é chamado, o objeto CLSID_DsPropertyPages salvará uma referência ao objeto de dados.
Obtenha a interface IShellPropSheetExt para o objeto CLSID_DsPropertyPages e chame o método IShellPropSheetExt::AddPages. O parâmetro lpfnAddPage é o endereço de uma função de retorno de chamada que você deve implementar. O formato desta função é mostrado abaixo. Se a função de retorno de chamada for declarada como membro de uma classe C++, a função de retorno de chamada deverá ser declarada como estática. O parâmetro lParam é um valor definido pelo aplicativo que pode ser usado para identificar o objeto que implementa a função de retorno de chamada. Quando o método IShellPropSheetExt::AddPages é chamado, o objeto CLSID_DsPropertyPages obterá os dados do objeto de dados e enumerará as páginas de propriedades registradas para os especificadores de exibição de objeto. O objeto CLSID_DsPropertyPages enumerará os objetos da página de propriedades, chamando o método IShellPropSheetExt::AddPages de cada objeto.
```
BOOL CALLBACK AddPagesCallback(HPROPSHEETPAGE, LPARAM)
```
Cada página adicionada pelos objetos de página de propriedades resultará em sua função de retorno de chamada sendo chamada com o identificador para a página de propriedades e o valor definido pelo aplicativo. Sua função de retorno de chamada deve armazenar cada identificador de página de propriedade que é passado. Quando o método IShellPropSheetExt::AddPages do objeto CLSID_DsPropertyPages retornar, todas as páginas terão sido adicionadas por meio de sua função de retorno de chamada.
Preencha uma estrutura PROPSHEETHEADER para exibir a folha de propriedades. O membro phpage recebe um ponteiro para uma matriz de identificadores de página que foram coletados pela função de retorno de chamada. O membro nPages recebe o número de páginas na matriz de identificador de página.
Exiba a folha de propriedades chamando a função PropertySheet .

Se os dados em qualquer página forem alterados e os botões OK ou Aplicar forem clicados, a janela identificada pelo membro hwndParentSheet da estrutura PROPSHEETCFG receberá uma mensagem WM_ADSPROP_NOTIFY_CHANGE. Esta mensagem é estritamente uma notificação e não requer nenhuma ação específica.

Quando a página for fechada, a janela identificada pelo membro hwndHidden da estrutura PROPSHEETCFG receberá uma mensagem WM_DSA_SHEET_CLOSE_NOTIFY. Esta mensagem é estritamente uma notificação e não requer nenhuma ação específica a ser executada.

Em alguns casos, as folhas de propriedades existentes precisarão exibir uma folha de propriedades secundária. Por exemplo, se você exibir a folha de propriedades de um objeto de usuário e selecionar a página Membro de, uma lista de grupos dos quais o usuário é membro será exibida. Se você clicar duas vezes em um desses grupos na lista, a folha de propriedades desse grupo será exibida. A folha de propriedades primária não exibe a planilha secundária por si só. Ele solicita que o host exiba a folha secundária enviando uma mensagem WM_DSA_SHEET_CREATE_NOTIFY para a janela identificada pelo membro hwndHidden da estrutura PROPSHEETCFG. O wParam da mensagem WM_DSA_SHEET_CREATE_NOTIFY é um ponteiro para uma estrutura DSA_SEC_PAGE_INFO que contém informações sobre a folha de propriedades secundária e o objeto que ela representa. Em resposta a essa mensagem, o host da folha de propriedades deve exibir a folha de propriedades secundária da mesma maneira mostrada acima. Depois de processar a mensagem WM_DSA_SHEET_CREATE_NOTIFY, o receptor da mensagem deve liberar a estrutura DSA_SEC_PAGE_INFO passando o valor wParam para a função LocalFree.

Duplicando o comportamento do objeto CLSID_DsPropertyPages

Para duplicar o comportamento do objeto CLSID_DsPropertyPages

Enumere os valores no atributo adminPropertyPages ou shellPropertyPages para o especificador de exibição da classe de objeto. Cada valor é uma cadeia de caracteres que contém um número, seguido por uma vírgula, seguido pela representação de cadeia de caracteres do identificador de classe da extensão de página de propriedades. Para obter mais informações sobre o formato dos valores do especificador de exibição de páginas de propriedades, consulte Registrando o objeto COM da página de propriedades em um especificador de exibição.
Converta cada cadeia de caracteres de identificador de classe em um CLSID usando a função CLSIDFromString.
Classifique os identificadores de classe de extensão pelo número que precede cada cadeia de caracteres de identificador de classe no valor do atributo. Se dois números forem idênticos, classifique os identificadores de classe na ordem em que os valores de atributo são obtidos do servidor do Active Directory.
Enumere os identificadores de classe de extensão, criando uma instância de cada extensão.
Para cada extensão, na ordem classificada acima, chame IShellExtInit::Initialize da extensão com as mesmas informações descritas na Etapa 4 do procedimento Hospedando uma folha de propriedades de usuários e computadores do Active Directory.
Para cada extensão, na ordem classificada acima, chame IShellPropSheetExt::AddPages da extensão com as mesmas informações descritas na Etapa 5 do procedimento Hospedando uma folha de propriedades de usuários e computadores do Active Directory.

Se possível, use o objeto CLSID_DsPropertyPages para criar as páginas em vez de fazer isso manualmente. O CLSID_DsPropertyPages foi otimizado e manipulará corretamente os casos de falha, como quando nenhum especificador de exibição estiver disponível para a localidade atual. Além disso, o objeto CLSID_DsPropertyPages pode ser alterado no futuro, o que significa que suas folhas de propriedades podem não corresponder exatamente às exibidas pelo snap-in MMC Usuários e Computadores do Active Directory.

Elementos Especiais de Programação

Atualmente, os seguintes elementos de programação não estão definidos em um arquivo de cabeçalho publicado. Para usar esses elementos, você mesmo deve defini-los no formato exato mostrado na página de referência específica.

Código de exemplo

O exemplo de código C++ a seguir mostra uma maneira segura de definir esses elementos que continuarão a funcionar mesmo se esses elementos forem definidos em um arquivo de cabeçalho publicado no 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

Partilhar via