Edit

Share via

Directory Object Picker

  • Article

The directory object picker dialog box enables a user to select one or more objects from either the global catalog, a domain or computer, or a workgroup. The object types from which a user can select include user, contact, group, and computer objects. For more information about Active Directory Domain Services, see Active Directory Domain Services.

To display an object picker dialog box:

  1. Call the CoCreateInstance or CoCreateInstanceEx function to create an instance of the IDsObjectPicker interface.
  2. Call the IDsObjectPicker::Initialize method to initialize the dialog box.
  3. Call the IDsObjectPicker::InvokeDialog method to display the dialog box.
  4. Call the IDataObject::GetData method of the IDataObject instance returned by the object picker dialog box to retrieve the CFSTR_DSOP_DS_SELECTION_LIST data. The CFSTR_DSOP_DS_SELECTION_LIST clipboard format provides an HGLOBAL that contains a DS_SELECTION_LIST structure. The DS_SELECTION_LIST structure contains data about the items selected in the object picker dialog box.

If the Security Identifier (SID) is required for an object, this should be requested directly from the object picker by adding the objectSID attribute to the list of attributes to retrieve for the selected object. Passing the returned object name to the LsaLookupNames or LookupAccountName function is not recommended because the name lookup will be redundant and may fail in some cases.

If a reference to any selected objects will be saved, the distinguished name should not be saved because the object may move, get renamed, or may change due to locale differences. For security principals, the objectSID should be requested for the object and securely saved. If the name of the security principal is needed later, it can be retrieved with the LookupAccountSid function. For all other objects, the objectGUID should be requested and saved.

Initialization

When the object picker dialog box is initialized, a set of scope types and filters is specified. The specified scope types determine the locations, domains or computers for example, from which a user can select objects. The filters determine the types of objects that a user can select from a given scope type. For more information, see the Scopes and Filters section below.

By default, a user can select a single object in the directory object picker dialog box. To enable multiple selections, set the DSOP_FLAG_MULTISELECT flag in the flOptions member of the DSOP_INIT_INFO structure when the dialog box initialized.

Scopes and Filters

The Look in drop-down list contains the scopes from which a user can select objects. A scope is a domain, computer, workgroup, or global catalog that stores data about, and provides access to, a set of available objects. The entries in the scope list depend on the scope types and the target computer specified when the IDsObjectPicker::Initialize method was last called to initialize the object picker dialog box.

A scope type is a generic category of scopes, such as all domains in the enterprise to which the target computer belongs, or the global catalog for the target computer's enterprise, or the target computer itself. For each specified scope type, the dialog box uses the context of the target computer to determine the scope list entries.

The IDsObjectPicker::Initialize method takes a pointer to a DSOP_INIT_INFO structure that contains an array of DSOP_SCOPE_INIT_INFO structures. Each entry in the DSOP_SCOPE_INIT_INFO array specifies one or more scope types as well as applicable filters and other attributes. The filters determine the types of objects, such as users, groups, contacts, and computers, that the user can select from a given scope type. When the user selects a scope from the list, the dialog box applies the filters for that scope type to display a list of objects from which the user can select.

Each DSOP_SCOPE_INIT_INFO structure contains a DSOP_FILTER_FLAGS structure that specifies the filters for that scope type. The DSOP_FILTER_FLAGS structure distinguishes between up-level and down-level scopes:

  • An up-level scope is a global catalog or a domain that supports the ADSI LDAP provider.
  • A down-level scope includes workgroups and all individual computers. The dialog box uses the ADSI WinNT provider to access a down-level scope.

There are two sets of filter flags defined for use in the DSOP_FILTER_FLAGS structure: one for up-level scopes and one for down-level scopes. The Uplevel member of the DSOP_FILTER_FLAGS structure is a DSOP_UPLEVEL_FILTER_FLAGS structure that specifies the filters for up-level scopes. The flDownlevel member of the DSOP_FILTER_FLAGS structure is a set of flags that specify the filters for down-level scopes.