Platform SDK: Active Directory, ADSI, and Directory Services

DSOP_SCOPE_INIT_INFO

The DSOP_SCOPE_INIT_INFO structure describes one or more scope types that have the same attributes. A scope type is a type of location, for example a domain, computer, or Global Catalog, from which the user can select objects.

When you call the IDsObjectPicker::Initialize method, you must specify an array of DSOP_SCOPE_INIT_INFO structures.

typedef struct _DSOP_SCOPE_INIT_INFO 
{
  ULONG    cbSize;
  ULONG    flType;
  ULONG    flScope;
  DSOP_FILTER_FLAGS  FilterFlags;
  PCWSTR   pwzDcName;
  PCWSTR   pwzADsPath;
  HRESULT  hr;
} DSOP_SCOPE_INIT_INFO, *PDSOP_SCOPE_INIT_INFO;
typedef const DSOP_SCOPE_INIT_INFO *PCDSOP_SCOPE_INIT_INFO;

Members

cbSize
Specifies the size, in bytes, of the structure.
flType
Flags that indicate the scope types described by this structure. You can combine multiple scope types if all specified scopes use the same settings. This member can be a combination of the following flags.
Value Meaning
DSOP_SCOPE_TYPE_DOWNLEVEL_JOINED_DOMAIN A downlevel domain to which the target computer is joined.
DSOP_SCOPE_TYPE_ENTERPRISE_DOMAIN All Windows® 2000 domains in the enterprise to which the target computer belongs. If the DSOP_SCOPE_TYPE_UPLEVEL_JOINED_DOMAIN scope is specified, then the DSOP_SCOPE_TYPE_ENTERPRISE_DOMAIN scope represents all Windows 2000 domains in the enterprise except the joined domain.
DSOP_SCOPE_TYPE_EXTERNAL_DOWNLEVEL_DOMAIN All downlevel domains external to the enterprise but trusted by the domain to which the target computer is joined.
DSOP_SCOPE_TYPE_EXTERNAL_UPLEVEL_DOMAIN All uplevel domains external to the enterprise but trusted by the domain to which the target computer is joined.
DSOP_SCOPE_TYPE_GLOBAL_CATALOG A scope containing objects from all domains in the enterprise. An enterprise can contain only uplevel domains.
DSOP_SCOPE_TYPE_TARGET_COMPUTER Computer specified by the pwzTargetComputer member of the DSOP_INIT_INFO structure.

If the target computer is an uplevel or downlevel domain controller, this flag is ignored unless the DSOP_FLAG_SKIP_TARGET_COMPUTER_DC_CHECK is set in the flOptions member of the DSOP_INIT_INFO structure.

DSOP_SCOPE_TYPE_UPLEVEL_JOINED_DOMAIN An uplevel domain to which the target computer is joined. If this flag is set, you can use the pwzDcName member to specify the name of a domain controller in the joined domain.
DSOP_SCOPE_TYPE_USER_ENTERED_DOWNLEVEL_SCOPE Enables the user to enter a downlevel scope.
DSOP_SCOPE_TYPE_USER_ENTERED_UPLEVEL_SCOPE Enables the user to enter an uplevel scope. If neither of the DSOP_SCOPE_TYPE_USER_ENTERED_* types is specified, the dialog box restricts the user to the scopes in the Look in drop-down list.
DSOP_SCOPE_TYPE_WORKGROUP The workgroup to which the target computer is joined. Applies only if the target computer is not joined to a domain.

Note that the only type of object that can be selected from a workgroup is a computer.


flScope
Flags that indicate the format used to return ADs paths for objects selected from this scope. The flScope member can also indicate the initial scope displayed in the Look in drop-down list. This member can be a combination of the following flags.
Value Meaning
DSOP_SCOPE_FLAG_STARTING_SCOPE The scope described by this structure is initially selected in the Look in drop-down list. Only one scope can specify this flag. If no scope specifies this flag, the initial scope is the first successfully-created scope in the array of scopes passed to the IDsObjectPicker::Initialize method.
DSOP_SCOPE_FLAG_WANT_DOWNLEVEL_BUILTIN_PATH ADs paths for downlevel well-known SID objects are an empty string unless this flag is specified (For example; DSOP_DOWNLEVEL_FILTER_INTERACTIVE). If it is, the paths will have the form:

WinNT://NT AUTHORITY/Interactive -or-

WinNT://Creator owner

DSOP_SCOPE_FLAG_WANT_PROVIDER_GC ADs paths for objects selected from this scope are converted to use the Global Catalog provider.
DSOP_SCOPE_FLAG_WANT_PROVIDER_LDAP ADs paths are converted to use the LDAP provider. For more information, see LDAP ADsPath.
DSOP_SCOPE_FLAG_WANT_PROVIDER_WINNT ADs paths are converted to use the WinNT provider. For more information, see WinNT ADsPath Syntax.
DSOP_SCOPE_FLAG_WANT_SID_PATH ADs paths having an objectSid attribute are converted to the form LDAP://<SID=x>, where x represents the hexadecimal digits of the objectSid attribute value.

LDAP and GC paths can be converted to the WinNT ADsPath Syntax. GC paths can be converted to the LDAP format. WinNT objects having an objectSid attribute can be converted to the LDAP format if you specify the DSOP_SCOPE_FLAG_WANT_SID_PATH or DSOP_SCOPE_FLAG_WANT_PROVIDER_LDAP flags. No other conversions are legal.

FilterFlags
A DSOP_FILTER_FLAGS structure that indicates the types of objects presented to the user for this scope or scopes.
pwzDcName
Pointer to a null-terminated Unicode string containing the name of a domain controller of the domain to which the target computer is joined. This member is used only if the flType member contains the DSOP_SCOPE_TYPE_UPLEVEL_JOINED_DOMAIN flag. If that flag is not set, pwzDcName must be NULL.

This member can be NULL even if the DSOP_SCOPE_TYPE_UPLEVEL_JOINED_DOMAIN flag is specified, in which case, the dialog box looks up the domain controller. This member enables you to name a specific domain controller in a multimaster domain. For example, an administrative application might make changes on a domain controller in a multimaster domain, and then open the object picker dialog box before the changes have been replicated on the other domain controllers.

pwzADsPath
Reserved; must be NULL.
hr
An HRESULT value. If the IDsObjectPicker::Initialize method successfully created the scope or scopes specified by this structure, hr returns S_OK. Otherwise, hr returns an error code such as E_INVALIDARG.

If IDsObjectPicker::Initialize returns S_OK, the hr members of all the specified DSOP_SCOPE_INIT_INFO structures also return S_OK.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Objsel.h.

See Also

DSOP_FILTER_FLAGS, DSOP_INIT_INFO, IDsObjectPicker::Initialize, Object Picker Dialog Box Overview, Object Picker Dialog Box Structures