Legal Information

ADSI Version 2.0

Information in this document is subject to change without notice. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 1997-1998 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, MS, Windows, Windows NT, ActiveX, JScript, Visual Basic, Visual J++, Visual C++, Win32, Win32s are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

NetWare is a registered trademark of Novell, Inc. and NDS (Novell Directory Service) is a trademark of Novell, Inc.

Java is a trademark of Sun Microsystems, Inc.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Introduction to Active Directory Service Interfaces

The Microsoft® Active Directory Service Interfaces (ADSI) Software Development Kit (SDK) is a client-side product, based on the Component Object Model (COM), that defines a directory service model and a set of COM interfaces that enables Windows NT and Windows 95 client applications to access several network directory services. Active Directory Service Interfaces is one component of Windows® Open System Architecture (WOSA) Open Directory Service Interfaces (ODSI).

The Active Directory Service Interfaces allow client applications to communicate with LDAP-compliant and NDS-compliant directory services in addition to the Windows NT Directory Service and Netware 3.x-compliant namespaces. ADSI is X.500-compliant for LDAP and NDS.

This document describes the ADSI directory service architecture, the Active Directory Service interfaces, examples of ADSI client applications, requirements for ADSI providers, and an example of an ADSI provider implementation.


What This Guide Contains

This guide explains the ADSI directory service architecture and the Active Directory Service Interface definitions. The first section presents information needed by ADSI client application writers. The second section presents information needed by ADSI provider writers.

Throughout the client application section, examples of writing to Active Directory Service Interfaces or to Active Directory Service Interface objects are provided for several language platforms, notably Visual Basic, Java, and C/C++. Resources for additional material are listed in ADSI References.


What You Should Know Before Reading This Guide

This guide assumes you are familiar with the Component Object Model (COM) and Automation, and that you know how to program in Visual Basic®, Java, or C/C++. For more information on these and other, related technologies, see ADSI References.

Some of the terms used in this guide are unique to the ADSI or directory services environments. Other terms will be familiar but may have slightly different meanings in these environments. For a list of ADSI terms and their definitions, see Glossary

This guide includes numerous code examples that demonstrate key features of ADSI and that may prove useful in your own code. For quick access to the code examples, see Code Examples.


ADSI References

For more information about Active Directory Service Interfaces and the technologies on which they are based, you may find the following sources helpful.

The Active Directory Service Design Specification Version 2.0

The Component Object Model Specification

Understanding ActiveX and OLE, by David Chappell, Microsoft Press, 1996.

OLE 2 Programmer's Reference, Volume Two, Microsoft Press, 1994.

Inside OLE, 2nd edition, by Kraig Brockschmidt, Microsoft Press, 1995.

Inside COM, by Dale Rogerson, Microsoft Press, 1997.

Microsoft's OLE DB Programmer's Reference Version 1.0, 1996.

ADSI Function List

ADSI Interface Definitions

ADSI Object Definitions

ADSI System Providers


Code Examples

The following links take you directly to ADSI code examples:

ADsPaths

Examples of ADsPaths.

Binding to an Object

Binding to a directory object (Automation and (C or C++ Examples).

Accessing an Individual Property in the Property Cache

Get and put methods (Automation example).

Get methods (COM vtable example).

Authentication

Use of the OpenDSobject.

Creating a Security Descriptor Object

How to create a security descriptor object (VB example).

Enumerating the ACLs on an ADSI Object

How to enumerate the discretionary ACL (VB example).

ADSI SQL Grammar

Formal grammar for the SQL queries.

ADSI OLE DB Example

Query a directory service.

Using ADO for Querying

User accounts on an ldap server.

Using IDirectorySearch for Querying

Query a directory service.

Automation Examples

Automation - Retrieving a Property From an ADSI Object

Automation - Browsing a Schema Class Definition

Automation - Adding Users to a Group

Automation - Removing Users From a Group

Automation - Listing Children in a Container

Automation - Enumerating Users in a Group

Automation - Creating a User Object

Automation - Deleting a User Object

Automation - Using a Filter

Java - Binding to an ADSI Object

Query Examples Using ADO

COM Vtable Examples

COM Vtable Examples - Querying a Namespace

COM Vtable Examples - Setting Properties

COM Vtable Examples - Adding Users to a Group

COM Vtable Examples - Removing Users from a Group

COM Vtable Examples- Enumerating Users in a Group

COM Vtable Examples - Creating a User Object

COM Vtable Examples - Deleting a User Object


ADSI Overview

Active Directory Service Interfaces (ADSI) provide the means for client applications of directory services to use one set of interfaces to communicate with any namespace that provides an ADSI implementation. ADSI clients gain a simpler access to a namespace's services by being able to use the well-defined Active Directory Service Interfaces in place of the network-specific API calls.

Active Directory Service Interfaces conform to the Component Object Model and support standard COM features.

ADSI supplies both Automation-compliant interfaces for use by name-bound controllers like Java, Visual Basic, and VBScript and also non-Automation interfaces for language environments like C and C++ that can optimize for performance.

The pure COM interfaces IDirectoryObject and IDirectorySearch support directory queries and object management.

In addition, ADSI supplies its own OLE DB provider, so that any client already using OLE DB, including those using ActiveX Data Objects, can query directory services directly.

Web applications using Active Server Pages also can program access to directory services through ADSI.

ADSI clients can programmatically discover all the ADSI providers at a site and use the same interfaces to communicate with each namespace. As additional providers are installed, the ADSI clients can communicate, without recompiling, with the new namespaces as well.

ADSI supplies system providers for the LDAP, NDS, NetWare 3.x, and WinNT namespaces.


ADSI for Clients

Active Directory Service Interfaces are COM interfaces that isolate client applications from underlying network specific API calls to a directory service. Client applications that use these interfaces or the COM Automation objects that expose IADs and the other Active Directory Service interfaces benefit from the layered insulation of the underlying directory services.

You can write ADSI client applications in many languages, For the majority of administrative tasks, ADSI defines interfaces and objects accessible from Automation-compliant languages like Microsoft® Visual Basic®, Microsoft® Visual Basic® Scripting Edition (VBScript), and Java to the more performance and efficiency-conscious languages such as C and C++.

Smooth integration with Active Server Pages and VBScript make it easy to write Internet applications that access directory services. For integration with OLE DB applications, ADSI supplies an OLE DB provider by supporting a subset of the OLE DB query interfaces. For Internet applications, using scripting in .asp files (Active Server Pages) can create and manipulate ADSI objects on the server and display the results in a Web page. In Microsoft® Management Console, directory-service administration snap-ins can use ADSI to find directory services of interest. In short, Active Directory Service Interfaces can provide access to a broad and diverse set of directory services — including those not yet built.

For tasks that require high performance and low overhead, the ADSI architecture defines low-level, non-Automation interfaces accessible from languages like C and C++ that are little more than COM wrappers for on-the-wire protocols to a directory service.

Coding to the published interfaces allows your application to reach directory services for all installed ADSI providers and integrate the resulting information. Without recompiling or amending your code, your application can continue to access additional directory services on your network as new ADSI providers are installed.

The following figure shows how ADSI fits into an application environment. Whether the application is written in Java, Visual Basic, C/C++, VBScript, Microsoft® JScript™, or as a web application using Active Server Pages, Active Directory Service Interfaces provide a clean and easy-to-use access to the underlying directory services without having to use the native network APIs.

As shown in the preceding figure, non-Automation clients have access to all ADSI interfaces, including both pure COM interfaces with the naming convention IDirectoryXXX and Automation COM interfaces with the naming convention IADsXXX. Because clients predominantly request information from directory services, ADSI's flexible query model through OLE DB and IDirectorySearch is especially powerful.


ADSI Development Environment

The ADSI SDK contains the following files of interest to ADSI clients:

  • ADSI DLLs
  • ADSI OLE DB Provider DLLs
  • ADSI Provider DLLs for WinNT, LDAP, NDS, Netware 3.x
  • ADSI libraries
  • ADSI type library for Automation controllers
  • ADSI .odl files
  • ADSI include files
  • ADSI .dbg files
  • ADSI .hlp file


Client Overview

If you understand the object model and ADSI architecture, you'll be able to easily take advantage of the range of features ADSI offers. The following sections discuss the specific features that are supplied by ADSI as they are important for writing client applications. Whether you are coding in Java, Visual Basic®, VBScript, C, C++, or some other scripting or development language, the following sections discuss the concepts you should understand to gain the most from this set of interfaces. Each section supplies a brief introductory discussion and lists the items of interest. See Using ADSI Objects and Interfaces for detailed examples of each section.

  • ADSI Object Model
  • ADSI Architecture
  • ADSI Schema Model
  • ADsPaths
  • Interface Summary
  • Helper Functions
  • Binding to an Object
  • Accessing a Directory Service
  • Querying a Directory Service
  • ADSI Security Model
  • About Collections and Groups
  • About Provider-Specific Information
  • ADSI Errors


ADSI Object Model

ADSI objects represent any item within a directory service: computers, users, files, servers, printers, print queues, and more – elements that network administrators work with daily. ADSI defines different kinds of objects to represent different kinds of elements. Each object, as shown in the following figure, supports one or more COM interfaces that give you access to information about the object itself (called metadata) and information about what the object represents.

Because COM interfaces are logically connected sets of properties and methods, you can think of each interface as a handle to the object that allows you access only one set of logical functions at a time. In ADSI, the fundamental interfaces are:

IADs — Object Identification
Fundamental interface required on all ADSI objects. Supplies access to properties that describe the object itself (its metadata) including its definition in the ADSI Schema and access to properties and methods that manage the object's data in the property cache.
IADsContainer — Object Lifetime Management and Detection
Fundamental interface required on all ADSI container objects. Manages object creation, deletion, copying and moving, binding and enumeration.
IADsPropertyList — Object Property Management
Fundamental interface that optimizes managing an object's data in the property cache.
IDirectoryObject — Direct Object Access
Low-level object access for non-Automation clients. This interface bypasses the object property cache and provides a direct access to object properties. For more information, see IADs vs. IDirectoryObject Global Strategy.
IUnknown — COM Object Management
Required on all COM objects.
IDispatch — Type Library Information and Method Invocation.
Required on all Automation objects.

More complex ADSI objects may expose additional interfaces. For example, IADsCollection supports methods that manage collections of directory elements of the same data type. IADsGroup methods manage the special case collections of objects that support the IADsMembers interface. For providers that support it, the IDirectorySearch interface supports methods to query directory services. In addition, ADSI supplies interfaces that represent well-known logical and physical items. ADSI objects that represent users support IADsUser, those that represent computers support IADsComputer, and so on. The list of ADSI objects defined for the SDK is in ADSI Object Definitions. Expanded explanations of ADSI objects can be found in IADs vs. IDirectoryObject Global Strategy. Not all providers implement all interfaces or all methods and properties on all interfaces. For more information, see provider-specific documentation in the ADSI reference pages in the Microsoft® Platform SDK.


ADSI Architecture

Many directory services are hierarchical in nature and thus lend themselves to a hierarchical object model. A natural way of displaying these relationships is to use the familiar browser tree view, where double-clicking any node expands the node to show what it contains. Both the object representation and the browser representation are used in the following section to illustrate ADSI features.

In the following object model figure, a top-level system object contains one Namespace object for every installed ADSI provider.

Each of the Namespace objects is itself a container that contains the top-level root nodes of every server, domain, or whatever other kinds of directory-system objects are defined as roots in each directory service.

The following figure shows browser representation of this same set of objects using the Visual Basic-based Dsbrowse.exe utility that comes with this SDK. The top-level ADSI object has been expanded to show the Namespace objects.

When you expand each Namespace object in the browser, the ADSI provider implementation of that Namespace object supplies the information you are requesting. This gives you access to both the power and the limitations of each directory service. For example, expanding the WinNT Namespace object yields the list of Domain objects or root nodes currently connected to the network. Expanding NDS and NWCOMPAT each also give the top-level root nodes on the network. (However, expanding the LDAP Namespace object does not do the same thing because LDAP supplies no network API to determine which servers are currently connected to the network.)

ADSI supplies a set of predefined objects and interfaces so that client applications can interact with directory services using a uniform set of methods. However, ADSI may not provide access to the complete functionality of a particular directory service. To help use the full power of each directory service, ADSI supplies a schema model that directory service providers and third-party software vendors can use to extend functionality beyond the interfaces ADSI offers.

The root-node container objects found within each provider Namespace object include an ADSI schema container object. This object contains the definition of all the functionality for that provider. For more information, see ADSI Schema Model.


ADSI Schema Model

A schema is like a dictionary in that it holds the definition of every type of object known to a directory service. ADSI client applications can browse through a schema to discover the features of any given ADSI implementation. In addition, ADSI supplies schema management interfaces that can be used to communicate with a directory service's underlying schema.

Some schemas are extensible and ADSI providers or third-party suppliers may choose to publish new interfaces or additional properties for existing interfaces there. ADSI clients use this information to determine what features are supported for each directory service.

There are three kinds of schema objects: classes, properties, and syntaxes, each respectively supporting the schema management interfaces IADsClass, IADsProperty, and IADsSyntax.

Note Class is an overloaded term in the software world. There are C++ classes, Java classes, COM classes, and ADSI classes. In this document, the word class, unless otherwise qualified, refers to a category or type of schema object.

ADSI abstracts the schema of every directory service and places it in every top-level root node in the Namespace object. To find out what classes a directory service supports on a given root-node, you enumerate the schema object and get a list of class objects, property objects and syntax objects. Details of this configuration are discussed in Using the ADSI Schema.


ADsPaths

Because the number of objects accessible from a directory service may be very large, you need some way to specify particular objects without naming collisions. ADsPaths enable you do just that both for a single provider and across multiple providers.

An ADsPath is a case-sensitive string guaranteed to identify uniquely an ADSI object on any given directory service. Because ADSI objects exist within the context of the namespace of the underlying directory service, part of the syntax of an ADsPath name is provider-specific.

The initial elements of the ADsPath string are the programmatic identifier (progID) of the ADSI provider, followed by "://" followed by whatever syntax is dictated by the provider namespace.

The following are examples of ADsPaths:

LDAP://ldapsvr/O=Internet/DC=COM/DC=MSFT/DC=DEV/CN=TopHat
LDAP://MyDomain.microsoft.com/CN=TopHat,DC=DEV,DC=MSFT,DC=COM,O=Internet
LDAP://c=us/o=msft/cn=MyName

WinNT://MyDomain/ComputerName,Computer
WinNT://MyDomain/UserAccount

NDS://MarsTree/O=MARS/OU=MARTIANS/CN=MyFavorite

NWCOMPAT://NWServer/MyNw3xPrinter

Using the LDAP namespace, you can specify the ADsPath either in an X500 DN (distinguished name) form starting with the CN tag or its hierarchical inverse starting with the O tag. Whichever form you use in the initial ADsPath determines its order.

Characters that have special meaning when referring to an ADsPath are listed in the following table.

Special Characters

Name | Character | Comment
Double quote | " | Used to quote any part of the ADsPath that may contain a special character so that the string is interpreted literally. For example, "CN=Name/Prefix"
Backward slash | \ | Escape character, used to precede special characters to signify they should be used as literals, including the '\' character and ',' (commas). For example, CN=Name\/Prefix
Forward slash | / | Component separator.
Right and Left angle bracket | <> | Delimits an ADsPath within another naming convention.

In order to delimit an ADsPath in a search specification or as part of an URL, use angle brackets. For example, "<WinNT://MyDomain/UserAccount>".

Some ADSI providers may have additional restrictions on the syntax because of their namespace requirements.

In addition to supporting ADsPaths, ADSI also supports COM globally unique identifiers (GUIDs), which provide a well-known way to establish a unique tag by which an object can be distinguished from all other objects ever created. For more information about the GUID structure, see the Microsoft® Platform SDK.


Interface Summary

A list of all Active Directory Service Interfaces can be found in ADSI Definitions, but in general, interfaces fall into several groups of functionality.

IADs, IADsContainer, and IADsPropertyList (along with its associated IADsPropertyEntry and IADsPropertyValue) are the fundamental interfaces that supply the foundation for interactions among ADSI objects. You can use their built-in house-keeping functions to keep track of names and hierarchical relationships, and their cache functions for improved performance.

The schema-management interfaces IADsClass, IADsProperty, and IADsSyntax identify the types of objects used to represent a specific directory service. You can use these interfaces to determine what types of objects are known to a specific directory service and to define and add new schema classes at runtime.

You can use IADsMembers, IADsCollection and IADsGroup to define, enumerate, and manage collections of similar objects. Group memberships use are special collections of IADsMembers interfaces.

You can use the interfaces IADsAccessControlEntry, IADsAccessControlList, and IADsSecurityDescriptor to support access control lists.

Use IADsOpenDSObject or the helper function ADsOpenObject to supply credentials to an operating system when first binding to a directory service object.

IDirectorySearch, available only to non-Automation clients, supports the ability to query a directory service and provides several practical means to guide the search for performance reasons. Because ADSI is an OLE DB provider, Automation clients can use the OLE DB-style queries discussed in Using the ADSI OLE DB Provider for Searches.

IDirectoryObject, available only to non-Automation clients, expands the set of supported syntaxes to a wider range, including provider-specific syntaxes. This interface also bypasses the overhead of ADSI housekeeping functions and provides direct, on-the-wire interactions with the directory service.

ADSI supplies implementations of interfaces, such as IADsUser , IADsDomain, and IADsOU, that represent a hierarchical grouping of the underlying data and services. By using these ADSI implementations, an application can maximize its functionality across all namespaces with installed ADSI providers on a network.

ADSI also supplies helper functions for C and C++ client applications.


Helper Functions

ADSI supplies several helper functions available to C and C++ developers. For a list of these functions, see ADSI Function List.

ADsGetObject, given a fully qualified distinguished name, finds the directory element specified, creates an ADSI object to represent it, and retrieves an interface pointer on that object. ADsOpenObject, in addition to performing the same function, also supplies a user name and password for credentials.

Listing the contents of a container or collection object requires a special type of object known as an enumerator. The IEnumXXXX interface on the enumerator object supplies the methods needed to list the collection of elements or objects within a container or collection. The helper functions ADsBuildEnumerator, ADsEnumerateNext, and ADsFreeEnumerator encapsulate the code needed to perform these operations. In addition, ADsBuildVarArrayInt and ADsBuildVarArrayStr are supplied to ease the task of building an array of integers or strings of type VARIANT. For more information, see enumeration examples in Automation Examples or COM Vtable Examples.


Binding to an Object

Binding to a directory object through ADSI is simple. In languages that support Automation, such as Java or Visual Basic®, use the GetObject function with a fully specified ADsPath.

Binding to user objects from different directory services
Dim MyObject1 As IADsUser
Dim MyObject2 As IADsUser
Set MyObject1 = GetObject("WinNT://MyDomain/MyAccount,User")
Set MyObject2 = GetObject("LDAP://MyLdapSvr/O=Internet/DC=Redmond/CN=MarySmith")

In C or C++, the binding looks very similar:

IADsUser *pMyObject1, *pMyObject2;
ADsGetObject(TEXT("WinNT://MyDomain/MyAccount,User"),
              IID_IADsUser,
              (void) ** &pMyObject1);
ADsGetObject(TEXT(
              "LDAP://MyLdapSvr/O=Internet/DC=Redmond/CN=MarySmith"),
              IID_IADsUser,
              (void) ** &pMyObject2);

In each case, the client application calls either ADsGetObject or Visual Basic® GetObject to obtain a pointer or a reference respectively, to an interface on an ADSI object that represents an end-user.

ADSI uses the ProgID in the first part of the string to load the appropriate ADSI provider DLL to process the bind request.

When credentials need to be established when passing a bind request to a directory service, you can use ADsOpenObject. In Automation environments, the Namespace object supports the IADsOpenDSObject interface to supply the same functionality.

The following Visual Basic code fragment supplies credentials when binding to an object:

Dim MyObject as Object
Dim MyNamespace as IADsOpenDSObject

Set MyNamespace = GetObject("LDAP:")
Set MyObject = MyNamespace.OpenDSObject("LDAP://MyLdapSvr/O=Internet",
       "Mary Smith","LandOfOz",0x1);

C and C++ programmers can use ADsOpenObject as shown below:

hr = ADsOpenObject(

LDAP://MyLdapSvr/O=Internet,

"Mary Smith",

"LandOfOz",

0x1,

IID_IADs,

(void **)&pIADs

);

For more information, see ADSI Component Interaction.


Accessing a Directory Service

Client applications frequently display directory service information through browsers and query functions. Several examples are included in this section to show ADSI client applications.

The following figure provides an example. Using the Visual Basic® browser Dsbrowse.exe, which is provided in the ADSI SDK, you can start at the top-level "ADs:" container and expand it. By double-clicking several container objects under the "WinNT:" namespace, you can see how the hierarchical object model works. The Namespace object contains two domain objects. The domain object"MYDOMAIN2" contains a user object, a computer object, and a group object names "Users."

The browser determines if an object is a container object by trying to enumerate it. If the attempt fails, the object contains no other objects.

If you already have the distinguished name for a directory object, you can use an application like the command-prompt adscmd.exe or adsvw.exe (in the Microsoft® Windows NT® Resource Kit) to bind specifically to a directory object.

Some directory services support both top-to-bottom and bottom-to-top components in their hierarchical namespace. For example, the following two ADsPath names specify the same directory service object.

"LDAP://Lserver1/O=Internet/DC=COM/CN=Me"
"LDAP://Lserver1/CN=Me,DC=COM,O=Internet"

The ADSI provider determines the style used and whether or not to reflect that use throughout the completion of any bind requests.


Querying a Directory Service

Because many queries to a directory service behave like database queries and return tables of information, ADSI supports interfaces that allow you to define queries.

For both Automation clients using ActiveX Data Objects (ADO) and all non-Automation clients, ADSI supplies an OLE DB provider, supporting a subset of OLE DB query interfaces. Client code that already uses OLE DB interfaces for queries can use the same interfaces to query directory services.

For non-Automation clients, ADSI providers can support the IDirectorySearch interface on any ADSI object. This interface is a simpler implementation of the same OLE DB functionality. For information on whether or not this interface is supported by a system provider, see ADSI System Providers.

For more information, see Using Directory Service Queries.


ADSI Security Model

ADSI security interfaces support both authentication and access control.


About Authentication

You can supply credentials to a directory service using the IADsOpenDSObject::OpenDSObject method or the ADsOpenObject function. Both these routines include user-name and password parameters. A flags parameter can indicate binding option preferences when you want to use secure authentication or encryption options, but the directory service may override these flags. Because the flags are provider specific, the directory service may not support them at all. For example, the Microsoft® NDS-compliant ADSI provider always uses strong authentication. For more information, see ADSI System Providers.


About Access Control

The following interfaces support access control through Access Control Lists (ACLs): SecurityDescriptor objects and their corresponding AccessControlEntry objects and AccessControlList objects. These objects and their corresponding IADsSecurityDescriptor, IADsAccessControlList, and IADsAccessControlEntry interfaces supply the methods and properties necessary to represent a directory service's ACL lists. For more information, see Using Credentials and Security.


About Collections and Groups

ADSI uses collection objects to represent any arbitrary set of items in a directory service that can be represented using the same data type. Collection objects are defined as a set of VARIANT values, representing any of the valid Automation data types. Collection objects can represent both persistent information such as access control lists and volatile information such as print jobs in a print queue.

The standard COM convention for listing the contents of a collection (or container) object is to create a enumerator object that supports IEnumVARIANT, which has methods to step through the list of collection objects. The interfaces in ADSI that supply the get__NewEnum method (note the two underscores) are IADsContainer, IADsMembers and IADsCollection. ADSI also supplies the helper functions ADsBuildEnumerator and ADsEnumerateNext to be used in C and C++ programs to simplify enumeration. Automation clients use enumeration implicitly when they call Next in a For loop.

Groups are simply collections of objects supporting the IADsMembers interface.

For examples, see the following:

· Automation - Enumerating Users in a Group

· COM Vtable Examples- Enumerating Users in a Group

· Enumerating the ACLs on an ADSI Object — An Automation Example


About Provider-Specific Information

Each ADSI provider supplies implementations of the Active Directory Service Interfaces in the most effective representation of the underlying directory service. The features and protocols of the native directory service do influence the ADSI implementations. For notes on each system implementation, see ADSI System Providers.


ADSI Errors

ADSI error codes are returned in the standard COM HRESULT status variable using facility code 5 with the severity bit set TRUE. This results in errors of the form 0x80005xxx. The following 32-bit error codes are listed here and defined in adserr.h.

Error/Value | Message
0x80005000L | E_ADS_BAD_PATHNAME: An invalid ADSI pathname was passed.
0x80005001L | E_ADS_INVALID_DOMAIN_OBJECT: An unknown ADSI domain object was requested.
0x80005002L | E_ADS_INVALID_USER_OBJECT: An unknown ADSI user object was requested.
0x80005003L | E_ADS_INVALID_COMPUTER_OBJECT: An unknown ADSI computer object was requested.
0x80005004L | E_ADS_UNKNOWN_OBJECT: An unknown ADSI object was requested.
0x80005005L | E_ADS_PROPERTY_NOT_SET: The specified ADSI property was not set.
0x80005006L | E_ADS_PROPERTY_NOT_SUPPORTED: The specified ADSI property is not supported.
0x80005007L | E_ADS_PROPERTY_INVALID: The specified ADSI property is invalid.
0x80005008L | E_ADS_BAD_PARAMETER: One or more input parameters are invalid.
0x80005009L | E_ADS_OBJECT_UNBOUND: The specified ADSI object is not bound to a remote resource.
0x8000500AL | E_ADS_PROPERTY_NOT_MODIFIED: The specified property for an ADSI object has not been modified.
0x8000500BL | E_ADS_PROPERTY_MODIFIED: The specified property for an ADSI has been modified.
0x8000500CL | E_ADS_CANT_CONVERT_DATATYPE: The ADSI datatype cannot be converted to or from a native DS datatype.
0x8000500DL | E_ADS_PROPERTY_NOT_FOUND: The ADSI property cannot be found in the property cache.
0x8000500EL | E_ADS_OBJECT_EXISTS: The ADSI object exists.
0x8000500FL | E_ADS_SCHEMA_VIOLATION: The attempted action violates the DS schema rules.
0x80005010L | E_ADS_COLUMN_NOT_SET: During a query, the specified column in the Active Directory was not set.
0x80005011L | S_ADS_ERRORSOCCURRED: During a query, one or more errors occurred.
0x80005012L | S_ADS_NOMORE_ROWS: During a query, there are no more rows to be obtained by the search result.
0x80005013L | S_ADS_NOMORE_COLUMNS: During a query, there are no more columns to be obtained by the search result.
0x80005014L | E_ADS_INVALID_FILTER: During a query, the specified search filter is invalid.

Error codes beginning with 0x8007xxxx are standard Win32® error codes. Within the Visual Basic® environment, the function error(#) gives you a friendly help message. Outside the Visual Basic environment, do the following. Take the last 3 digits of the error number and convert them from hex to decimal, using the Microsoft® Calculator if you choose. Type

net helpmsg #

where # is the decimal number. A description of the error message is then displayed.

If an error code is 0x8005XXXX, the error is listed above and defined in adserr.h.

Two common errors are 0x80004005, E_FAIL and 0x000041E4 MK_E_SYNTAX. The former is the generic COM fail message; the latter indicates the object was not found and probably indicates an error in the ADsPath name.

More information can be found in adserr.h and in Platform SDK, COM and ActiveX Object Services, COM, Error Handling. Error codes returned from the ADSI OLE DB provider implementation can be found in oledberr.h.

ADSI provides extended error handling so that providers may supply their own error messages and add context information to system errors.

The ADSI functions ADsGetLastError and ADsSetLastError are C-language wrappers provided for applications that receive an ERROR_EXTENDED_ERROR return in response to any ADSI helper function in the ADSI Function List.

Functions | Value
ADsGetLastError | Returns the last-error code value for the calling thread.
ADsSetLastError | Sets the last-error code value for the calling thread.

These two functions follow the same rules as the Win32 functions GetLastError and SetLastError described in the Microsoft Platform SDK.


Using ADSI Objects and Interfaces

For ADSI client applications seeking to understand how all the elements of the ADSI object model fit together, this section provides plenty of examples.


IADs vs. IDirectoryObject Global Strategy

ADSI clients manage and manipulate directory service objects by using one of two COM interfaces: IADs or IDirectoryObject. IADs is a dispinterface intended for use by late-bound clients such as those written in Microsoft® Visual Basic®, Java, and various scripting languages. IDirectoryObject is a vtable interface that provides direct access to objects by early-bound clients such as those written in C and C++.

Each ADSI object must implement both IADs and IDirectoryObject.ADSI clients written in languages such as C or C++, which are able to directly access vtables, can use either interface but not both from one application. ADSI clients written in Visual Basic or Java are limited to using IADs.

The IADs interface enables late-bound clients to take advantage of the inherent housekeeping features of the ADSI object model. Among these features is the property cache, which enables clients to read and write properties without going over the wire for each call. In addition, client applications gain the use of powerful UI and ActiveX™ control libraries and a simpler style of programming. In return, late-bound clients must use the VARIANT data type, which precludes using ADSI's richer native data types. For more information, see Using IADs.

The IDirectoryObject interface enables early-bound clients to take full advantage of native directory-service data types at the cost of foregoing a slight performance advantage from using the property cache. In return, the IDirectoryObject interface provides direct, on-the-wire access to object properties through a single request, rather than through individual get and put calls.. For more information, see Using IDirectoryObject.


Using IADs

In the ADSI environment, each element of a directory service is represented by an ADSI object, which is a Component Object Model (COM) object that supports the standard COM IUnknown interface as well as IDispatch and IADs. IADs supplies the basic house-keeping functions for ADSI objects.

The preceding figure shows a generic ADSI object supporting the fundamental interfaces IADs, IADsPropertyList, IUnknown, IDirectoryObject, and IDispatch. An ADSI object such as this manages data from the data store of the underlying directory service through the interfaces it supports. This data is known as the properties of the object, and the routines that retrieve and set these properties are known as property methods. Read-only properties have one property method that sets the value of the property. Read-write properties have two methods: one that sets the value and one that gets the value. Properties are implemented on each ADSI object using a property cache. IADs::get_ADsPath and IADs::put_ADsPath are examples of property methods. Property methods are not apparent to Visual Basic and other Automation clients that allow direct references to the property. For example, Visual Basic refers to IADS::ADsPath directly using the Object.ADsPath syntax. For more information, see Interface Property Methods.

In addition, an ADSI object interacts with other ADSI objects and directly to a namespace through methods. Methods execute immediately Examples of methods include IADs::SetInfo, IADs::GetInfo, and IADsPrintJobOperations::Pause.

Properties, property methods, and methods are all accessed through standard COM interfaces.

An ADSI object is uniquely identified by its ADsPath. An example of an ADsPath for the LDAP namespace is "LDAP://MyServer/OU=Seattle". For programmers familiar with COM monikers, this is conceptually similar to the COM moniker display name.

Any ADSI object that contains other ADSI objects (an ADSI container object) also supports the IADsContainer interface, which provides methods and properties that manage the creation, deletion, and enumeration of ADSI objects that are contained by the object. The following figure shows an ADSI container object.

Almost all ADSI objects are contained by other objects. The only ADSI object with no parent container is the top-level ADSI Namespaces object ("ADS:").

The IADs::SetInfo method on a container object persistently stores the cached properties of the ADSI container object to storage in addition to any objects that have been created with the IADsContainer::Create method. IADsContainer::Deletedoes not affect the property cache but deletes the underlying namespace directory element represented by this object immediately.


Using IDirectoryObject

Late-bound ADSI clients written in languages such as C and C++ can take advantage of ADSI's rich native data types by calling the IDirectoryObject interface instead of the IADs interface. The IDirectoryObject interface provides methods to support a subset of an object's housekeeping properties and to access its attributes. The following figure shows the relationships among the data structures:

In the preceding figure, the structure ADS_OBJECT_INFO defines properties that identify the object by distinguished name, relative distinguished name, by container (ParentDN), by object type (ClassDN), and by schema definition (SchemaDN). The attribute descriptor ADS_ATTR_INFO consists of a name, data type, an array of data values shown in ADSVALUE, and a flag that directs the underlying DS to perform certain operations on the attributes detailed in ADS_ATTR_* constants. The data types for these attributes include the ADSI extended syntax types, detailed in ADSTYPE.

Note Although IDirectoryObject provides most of the functionality of IADs, as well as new functionality of its own, it does not currently support ADSI container interfaces. Therefore, all ADSI objects must also implement IADs, which does provide such support.


Using the ADSI Schema

ADSI providers create a representation of the underlying schema by implementing the schema-management interfaces IADsClass, IADsProperty, and IADsSyntax. For example, on LDAP, IADsClass represents the attribute "objectClass" which contains values that identify every type of object known to an ldap server. NDS uses "object class". WinNT defines each object type directly, such as "Domain", "Computer", or "User". In all these cases, the IADsClass interface supplies methods to identify and manage the list of properties or attributes a class uses. Similarly, IADsProperty supplies methods to define a property as it is known to the underlying directory service. If you browse a directory service directly, you probably will not find anything corresponding to syntax objects. ADSI abstracts the syntax information as necessary and lets you use IADsSyntax to identify the syntax needed to represent an object's data.


ADSI Object Properties

The ADSI object model defines properties or attributes of an ADSI object for use in the housekeeping functions associated with directory services, all defined on the IADs interface. These properties include the fully qualified path name ADsPath, the unique identifier GUID, the Parent container object, the Schema object, and the Class or type of the object. These properties, along with the properties defined for this type of object that have also been defined in the underlying directory service, are cached in a property cache for each object.

The Class definition, found in the schema, specifies certain attributes that can be filled in from the underlying directory-service schema or namespace as available. The MandatoryProperties attribute supplies a list of property names that must be supplied before the object can be saved in persistent storage. The OptionalProperties list the properties that may be set for an object of this type.


Property Cache

The ADSI object model provides a client-side property cache for each ADSI object. An object's property cache enables client applications to set multiple properties in a single call. This capability is critical for clients written in languages, such as Microsoft Visual Basic, that have no native batching mechanism for setting properties. Without the ADSI property cache, such clients would have to hit the wire for each and every put call, with a predictable drop in performance.

Think of the cache as a table in memory that contains the names and values of all an object's properties. When an object is created, its property cache is empty. Calling IADs::GetInfo loads the object's properties from the underlying directory service. If a property is multi-valued, use the GetInfoEx method instead. If the cache is empty, calling get or get_propertymethod from a client written in C or C++, or calling .propertymethod from an Automation client, , forces an implicit GetInfo. Once the cache is filled, all get and put calls work on the contents of the cache only. You change the property values in the tables as necessary for your application using IADs methods or IADsPropertyList methods, then write the changes back out to the directory service when they are in a consistent state using SetInfo. After the SetInfo is called, the cache values remain until they are explicitly refreshed with a GetInfo. The following figure shows the different methods used to operate on the cache.

As shown in the preceding figure, while the property values are in the cache, you can access them in two ways:

Accessing an Individual Property in the Property Cache

Accessing All Properties in the Property Cache


Accessing an Individual Property in the Property Cache

Individual properties in the property cache can be referenced in several ways. From Automation languages, you use the property name directly. This is the ADSI property name, for example, Name or Class, both properties defined on IADs. You can also use the property names as it is defined in the schema object. Then you can use the IADs::Get or any of its related interfaces, GetEx, Put, and PutEx. In each of these cases, you pass the name of the property as it is defined in the schema as the first parameter.

From non-Automation languages, you can also use the IADs::Get method and its related methods as described above. In addition, you can use the get_propertyname and put_propertyname methods supported on all ADSI interfaces.

To find the property names supported by an object, first get the IADs interface pointer for that object. Use IADs::Schema to find the schema object, and IADs::Class to look up the class definition. Using the IADsClass interface on the class definition, use property methods MandatoryProperties and OptionalProperties to see the list of properties defined for each object of this type.

Note In the following discussion, "get methods" include IADs::Get, IADs::GetEx, and any get_ property method defined on an ADSI interface. Similarly, "put methods" include IADs::Put, IADs::PutEx, and any put_ property method defined on an ADSI interface.

When an object is created, its property cache is empty. You can force all the properties to load by calling GetInfo. When you call one of the get methods and the cache is empty, an implicit GetInfo occurs. Once the cache is filled, all subsequent get and put requests are filled from the current contents of the cache, eliminating network calls. Only another explicit GetInfo refreshes the cache.

One consequence of this design occurs for the following scenario:

If the cache already has values, and you then set a previously undefined property in the underlying directory service, and you get that property, the cache will not have the value and the error return is E_ADS_PROPERTY_NOT_FOUND. You must explicitly call GetInfo to see the new value.

If you use a put method to change a value in the cache for a property and subsequently use a get method for that property, you retrieve the value you just put there. If you explicitly call GetInfo after you have changed values in the cache but before you call SetInfo, the values in the cache are refreshed from the underlying directory service and any changes you made are over-written.

SetInfo is always an explicit call, never called implicitly.

For more information, see IADs.

Examples of get and put methods for properties for Automation clients include the following:

MyObject.xxxx
Get by using object.property syntax on the right side of an assignment operation (=) or in an expression. Put by using object.property syntax on the left side of an assignment operator (=).
Value=(User.FullName)
Get by passing the name of the property. Use GetEx for multivalued properties.
MyObject.Put("Property_X", value)
Put by passing the name of the property. Use PutEx for multivalued properties.

The following Automation example shows both styles of setting the IADsUser::FullName property in the cache.

' Visual Basic example
Dim User as IADsUser
Dim MyObject as IADs
Dim Name as Variant

Set FullName as "John Q. Public"
Set User = GetObject("WinNT://MSFT/Users/John")

//Set using IADsUser::put_Fullname property method
User.FullName = Name

//Set using IADs::PutMethod
User.Put("FullName",Name)

Examples of get methods for properties for non-Automation clients include the following:

IADsXXXX::get_xxxx
An interface's compile-time property method beginning with get_ on a named property.
IADs::Get("Property_X")
A runtime get by property name.
// For non-Automation clients
IADsUser     *pUser;
IADs         *PObject;
ADsGetObject(
     TEXT("WinNT://MSFT/Users/John"),
     IID_IADsUser,
     (void**) &pUser);
// Set using IADsUser::put_FullName property method
pUser->put_FullName(TEXT("John Q. Public"));
// Set using IADs::Put method
pUser->QueryInterface(IID_IADs,(void **) &pObject);
pObject->Put("FullName",TEXT("John Q. Public"))


Accessing All Properties in the Property Cache

In addition to the IADs methods that get and set individual properties in the cache, ADSI provides the IADsPropertyList, IADsPropertyEntry, and IADsPropertyValue interfaces that allow client software to access the property cache directly. These interfaces allow you to work with the properties without having to use the individual property names.

ADSI clients call:

Interface | To:
IADsPropertyList | Manage the entire list of properties defined on an object.
IADsPropertyEntry | Manage individual property attributes and values.
IADsPropertyValue | Read and write values for each property entry in the property cache.

The following figure shows the property cache as a table.

In the preceding figure, each entry in the cache contains the property name, the number of values that exist for the property, the data type needed to represent its information, and the actual value list. The ADSI property-cache interfaces represent each property entry. IADsPropertyEntry allows access to a single property in the cache and includes a pointer to the list of IADsPropertyValue pointers needed to represent each value. IADsPropertyList allows you to manage the property entries, including enumerating all the properties in the cache.


Standard Syntax Objects

An ADSI schema container object contains the syntax objects necessary to represent all the property-object data in all the schema classes. Syntax objects by definition are Automation-compliant. Extended syntax support for non-Automation clients is defined in ADSTYPE.

Syntax Name | IDL Type Representation | Automation VARTYPE | Remarks
Boolean | VARIANT_BOOL | VT_BOOL | TRUE = -1, FALSE = 0;
Counter | long | VT_I4 | Differs from Integer in that any value added is added to the total, and any value deleted is deleted from the total.
ADsPath | BSTR | VT_BSTR | String that uniquely identifies an object.
EmailAddress | BSTR | VT_BSTR |
FaxNumber | BSTR | VT_BSTR | Should comply with E.123, with an optional bit string formatted according to T.30.
Integer | long | VT_I4 |
Interval | long | VT_I4 | Value represents an interval of time, in seconds. -1 = Unlimited.
List | VARIANT | VT_VARIANT | Value is an ordered sequence of strings. The VARIANT contains a SAFEARRAY of BSTRs.
Interface Ptr | IDispatch | VT_DISPATCH | Identifies a function available on this COM object.
NetAddress | BSTR | VT_BSTR | A network address, represented as a string.
OctetString | VARIANT | VT_VARIANT | Values are uninterpreted byte strings. The VARIANT contains a SAFEARRAY of unsigned chars.
Path | BSTR | VT_BSTR | Value is a file system path.
PhoneNumber | BSTR | VT_BSTR |
PostalAddress | BSTR | VT_BSTR | Value is a postal address, typically 6 lines of 30 characters each. Carriage return characters are allowed. The following format is recommended: Line 1: Name Line 2: Street Address or PO Box Number Line 3: State or Province Name Line 4: Postal Code Line 5: Country
SmallInterval | long | VT_I4 | Value represents an interval of time in milliseconds.
String | BSTR | VT_BSTR |
Time | DATE | VT_DATE |
DN | BSTR | VT_BSTR | Distinguished Name
UTCTIME | BSTR | VT_BSTR | Time string in Universal Coordinated Time format.
ORName | BSTR | VT_BSTR | X.400 Originator/Recipient name.
IA5String | BSTR | VT_BSTR | String in the IA5 character set.
OID | BSTR | VT_BSTR | Object Identifier in dotted decimal form (1.2.3.4.5 etc.)
NumericString | BSTR | VT_BSTR |
AccessPointDN | BSTR | VT_BSTR | Distinguished Name (used internally by DS)
Large Integer | VARIANT | VT_VARIANT | An object


Using Credentials and Security

ADSI provides interfaces to enforce both user authentication and access control on directory service objects.


Authentication

In ADSI, credentials consisting of a user name and password allow system software to authenticate the identity of a user during the initial system login. Use IADsOpenDSObject::OpenDSObject or the helper function ADsOpenObject to establish a user's credentials for a directory service. If you don't use OpenDSObject, ADSI uses default credentials. Once the system authenticates the user, the user is free to make requests for system resources, access to file shares, and file permissions, as supported by the underlying directory service's security requirements.

The following examples show the use of the OpenDSobject method on different directory services:

Dim MyNamespace As IADsOpenDSObject

Set MyNamespace = GetObject("LDAP:")
Set X = MyNamespace.OpenDSObject(DN, UserName, Password, Flags)


Access Control

Privileges to access directory service resources are usually granted through the use of access control entries (ACEs). An ACE defines an access or audit permission on an object for a specific user or group. An access control list (ACL) is the ordered collection of ACEs defined for an object. A security descriptor supports properties and methods that create and manage ACLs. For more information on security models, see the "Windows Base Services" section of the Microsoft Platform SDK or Microsoft Windows NT Resource Kit.

ADSI clients call:

Interface | To:
IADsAccessControlEntry | Read and write ACE properties.
IADsAccessControlList | Manage and enumerate all ACEs on a directory service object.
IADsSecurityDescriptor | Read and write security properties of a directory service object.

The following figure shows the traditional finance department example: the owner of a confidential document has the complete set of permissions for accessing it. The temporary help has no access to the document object. The other members of the finance department have read-only access.

The preceding figure shows that a property or attribute called "ntSecurityDescriptor" has been created for a generic directory service object. As this is a generic object that does not support the IADs interface, the ADsPath property has also been created for this object and its value is "LDAP://o=ms/ou=printers/cn=FancyExpensiveColorPrinter". The value of the property for "ntSecurityDescriptor" is a pointer to an interface on a security descriptor object that, among other properties, has a property named "DiscretionaryACL". This property contains a pointer to an interface on an AccessControlList object that supplies a method to create an enumerator object that in turn allows you to list the individual AccessControlEntry objects defined on the original document object.

Most security checking algorithms have rules about the ordering of different types of ACEs. Since ADSI packs the ACEs in the order specified by the client to be sent to the directory service and preserves the order when loading them from the directory service, the ordering is preserved.


Creating a Security Descriptor Object

The following Visual Basic example shows how to create a security descriptor object for an ADSI object.

' Assume you have the credentials to create objects
Dim MyObject As IADs
Dim MySecDes As IADsSecurityDescriptor
Dim Var As Variant
Dim SecDes As New SecurityDescriptor
Dim Dacl As New AccessControlList
Dim Ace As New AccessControlEntry

'Create an Access Control Entry (ACE) for Group objects at Microsoft
'     on an LDAP namespace.
Ace.AccessMask = 0
Ace.AceType = 1
Ace.AceFlags = 1
Ace.Trustee = "cn=Groups,o=Microsoft"

' Add the newly created ACE object as the only ACE
'     in a new Access Control List (ACL)
Dacl.AceCount = 1
Dacl.AclRevision = 4
Dacl.AddAce Ace

' Use this ACL as the discretionary ACL (DACL) for
'     this Security Descriptor object and use
'     this DACL instead of the default.
SecDes.Revision = 1
SecDes.OwnerDefaulted = True
SecDes.GroupDefaulted = True
SecDes.DaclDefaulted = False
SecDes.SaclDefaulted = True
SecDes.DiscretionaryAcl = Dacl
' Attach  this security descriptor
'     to the ADSI object
MyObject.Put "ntSecurityDescriptor", SecDes
' Commit the changes to the underlying DS
MyObject.SetInfo
' Read the properties back in to the property cache
MyObject.GetInfo
' Retrieve the SecurityDescriptor object
Set MySecDes = MyObject.Get("ntSecurityDescriptor")


Enumerating the ACLs on an ADSI Object

The following Visual Basic example shows how to enumerate the discretionary ACL on a security descriptor object.

Dim X as IADs
Dim Namespace As IADsOpenDSObject
Dim SecurityDescriptor As IADsSecurityDescriptor
Dim Dacl As IADsAccessControlList

' First get access to the LDAP directory service
Set Namespace = GetObject("LDAP:")
' Establish your credentials with no password
Set X = Namespace.OpenDSObject("LDAP://MyLdapSvr/O=Internet/DC=MS",
     "cn=administrator,DC=MS,O=Internet", "", 1)
' Retrieve the contents of the ntSecurityDescriptor field which is
'     an interface pointer on the security descriptor object
'     for the X object
Set SecurityDescriptor = X.Get("ntSecurityDescriptor")
' Print out the owner of the object
' Print out the group
Debug.Print SecurityDescriptor.Owner
Debug.Print SecurityDescriptor.Group
'
Set Dacl = SecurityDescriptor.DiscretionaryAcl
' Enumerate the ACEs in the Dacl, first printing out the count
Debug.Print Dacl.AceCount

For Each Obj In Dacl
     Debug.Print Obj.Trustee
     Debug.Print Obj.AccessMask
     Debug.Print Obj.AceFlags
     Debug.Print Obj.AceType
Next


Using Directory Service Queries

Querying a directory service using ADSI is similar to querying a database. Because the potential amount of information to be searched could be millions of data elements (or more), a good query strategy allows you to limit your search in various ways. ADSI uses the following concepts in defining a search:

Base DN
The root node of a search. The base DN (distinguished name) must be a fully qualified name in the form: "WinNT://MyDomain/MyServer/User" or "WinNT://MyDomain/MyServer/MyPrintQueue". (DNs are not case sensitive. The use of capital letters in the preceding examples is for clarity only.)
Filter
A string that specifies the criteria to be met by the objects to be returned in a query. This string is in LDAP search filter format, as described in RFC 1960. More information about this can be found in the document ftp://ds.internic.net/rfc/rfc1960.txt. For more information on using a search filter, see Using a Search Filter.
Attribute or Property List
Identifying those attributes of interest allows the search to ignore all other attributes of the object.
Scope
In a directory hierarchy, you need to choose the beginning entry of the search and decide if you want to search recursively through all branches of that node. Scope is one of the values "Base", "OneLevel", or "SubTree", which are defined in ADS_SCOPE_* constants.
Preference
Search preference includes other ways to limit a query. A search preference set allows you to indicate limits such as the size of the query result, time limits, whether or not to dereference aliases during the search, whether to use secure authentication and other limits.

To use ADSI to query a directory service, you can use IDirectorySearch or the ADSI OLE DB provider. For more information, see Using the ADSI OLE DB Provider for Searches or Using IDirectorySearch for Querying.


Using a Search Filter

The search filter specifies the relationship between the attributes and values of those attributes in the prefix expression notation.

The following are examples of valid search filters:

Search Filter | Meaning
(objectClass=*) | All objects that have objectClass attribute present.
(cn=FooBar) | All objects having cn property equal to "FooBar".
(&(objectClass=User)(revision>=10)) | All user objects that have the property revision greater than or equal to 10.
(&(objectClass=Computer)(|(name=a*)(name=b*))) | All Computer objects which have name attribute starting with "a" or "b".

The formal definition of the search filter is as follows (from RFC 1960):

<filter> ::= '(' <filtercomp> ')'

<filtercomp> ::= <and> | <or> | <not> | <item>

<and> ::= '&' <filterlist>

<or> ::= '|' <filterlist>

<not> ::= '!' <filter>

<filterlist> ::= <filter> | <filter> <filterlist>

<item> ::= <simple> | <present> | <substring>

<simple> ::= <attr> <filtertype> <value>

<filtertype> ::= <equal> | <approx> | <ge> | <le>

<equal> ::= '='

<approx> ::= '~='

<ge> ::= '>='

<le> ::= '<='

<present> ::= <attr> '=*'

<substring> ::= <attr> '=' <initial> <any> <final>

<initial> ::= NULL | <value>

<any> ::= '*' <starval>

<starval> ::= NULL | <value> '*' <starval>

<final> ::= NULL | <value>

The token <attr> is a string representing an AttributeType. The token <value> is a string representing an AttributeValue whose format is defined by the underlying directory service.

If a <value> must contain one of the characters * or ( or ), the character should be preceded by \ escape character.


Using the ADSI OLE DB Provider for Searches

Under the OLE DB implementation, a directory service is exposed as a Data Source Object. Data source objects are factories for session objects and support IDBInitialize to connect to the directory, IDBCreateSession to create the session object, IDBProperties to supply authentication information to the underlying namespace and supply the query command and IPersist to save the information necessary to create the data source object to the underlying directory service.

The OLE DB Sessions Object represents a transaction on the data source object and, in the ADSI implementation, can create rowset objects and command objects. It supports IOpenRowSet to allow direct access to DS tables without having to use command objects. ISessionProperties to manage the information stored in property sets, and IDBCreateCommand to create a command object.

The OLE DB Command Object manages the information required by a search. The object supports the following interfaces:

  • ICommand methods execute the command once it is set up.
  • IAccessor methods describe how the data should be stored in a consumer's buffer.
  • IColumnsInfo methods provide information about the columns.
  • ICommandProperties methods to specify some of the characteristics of the search, for example, Scope andDerefAliases.
  • ICommandText methods to set the command text, which contains the basic search information including the root of the search, search filter, and list of attributes to be returned.
  • IConvertType to examine what kind of data conversions among different data types are allowed by the provider.

The OLE DB Rowset Object allows the DS to expose its information in tabular form. The ADSI implementation of this object supports the following interfaces:

  • IRowset methods traverse the tables row by row.
  • IAccessor methods describe how the data should be stored in a consumer's buffer.
  • IColumnsInfo methods provide information about the columns.
  • IConvertType methods determine if the type of information for this row can be converted to, for example, an Automation-supported type.
  • IRowsetLocate, IRowsetScroll, and IRowsetIndex methods support complex rowset navigational methods that include cursoring, bookmarks, and client-side filtering.

For more information about OLE DB, see the Database and Messaging Services section of the Microsoft Platform SDK.

To see if a specific provider implements these interfaces, see ADSI System Providers.

The ADSI SDK includes adsqry source code in the sampapp\cxx\adsqry directory. For an edited version of this example, see ADSI OLE DB Example.


ADSI SQL Grammar

The following are examples of ADSI queries using SQL:

Select ADsPath, Cn FROM 'LDAP://O=Internet/DC=COM/DC=MICROSOFT/DC=NTDEV' where objectClass='group' :  Select all group objects

Select AdsPath, cn, revision FROM
'LDAP://nw01t1/O=Internet/DC=COM/DC=MICROSOFT/DC=NTDEV/dc=nwparent' where objectClass='*' AND revision >= 10 : All user objects which have the property revision greater than or equal to 10

Select AdsPath, cn, revision FROM 'LDAP://nw01t1/O=Internet/DC=COM/DC=MICROSOFT/DC=NTDEV/dc=nwparent' where objectClass='*' AND (cn = 'a*' OR cn = 'b*'):  All Computer objects which have name attribute starting with "a" or "b"

The formal grammar for the SQL queries is defined in the following way. (All keywords are case insensitive.)

statement ::= select-statement

select-statement ::= SELECT [ALL] select-list FROM table-identifier [WHERE search-condition]

select-list ::= * | select-sublist [, select-sublist]...

select-sublist ::= column-identifier

column-identifier ::= user-defined-name

table-identifier ::= string-literal

search-condition ::= boolean-term [OR search-condition]

boolean-term ::= boolean-factor [AND boolean-term]

boolean-factor ::= [NOT] boolean-primary

boolean-primary ::= comparison-predicate | (search-condition)

comparison-predicate ::= column-identifier comparison-operator literal

comparison-operator ::= < | > | <= | >= | = | <>

user-defined-name ::= letter [letter | digit]...

literal ::= string-literal | numeric-literal | boolean-literal

string-literal ::= '{character}...' (Any sequence of characters delimited by quotes)

numeric-literal ::= digits [fraction] [exponent]

digits ::= digit [digit]...

fraction ::= . digits

exponent ::= E digits

boolean-literal ::= TRUE | FALSE | YES | NO | ON | OFF


ADSI OLE DB Example

This following ADSI example shows a simple command-prompt program that uses the OLE DB interfaces to query a directory service. The beginning comment section describes which functions were removed to simplify the example. The complete example code is included in the ADSI SDK in the samples/activeds/sampapp/cxx/adsqry directory.

//--------------------------------------------------------------
//  Microsoft Active Directory 2.0 Sample Code
//  Copyright (C) Microsoft Corporation, 1997
//  File:       main.cxx
//  Contents:   Main for adsqry
//--------------------------------------------------------------
// ... global declarations, free memory calls, and error handling
//        print routines, mapping input arguments to
//        search arguments etc. omitted for brevity

#include "main.hxx"

int __cdecl
main( int argc, char ** argv)
{
 //  Load up a DBPropSet for DB data
 //    and a CmdPropSet for Command data
    hr = ProcessArgs(argc, argv);
    hr = CoInitialize(NULL);
    //
    // Instantiate a data source object for LDAP provider
    //
    hr = CoCreateInstance(
         CLSID_ADsDSOObject,
             0,
             CLSCTX_INPROC_SERVER,
             IID_IDBInitialize,
             (void **)&pIDBInit
             );
 // Initialize the Data Source
     hr = pIDBInit->Initialize();
    if (cDBPropSet) {
        pIDBInit->QueryInterface(
            IID_IDBProperties,
            (void**) &pIDBProperties);
        hr = pIDBProperties->SetProperties(
                 cDBPropSet,
                 rgDBPropSet);

    }
 // Get the interface to create a session
    pIDBInit->QueryInterface(
        IID_IDBCreateSession,
        (void**) &pIDBCS);

 // Create a session returning a pointer to its CreateCommand interface
    hr = pIDBCS->CreateSession(
             NULL,
             IID_IDBCreateCommand,
             (LPUNKNOWN*) &pIDBCreateCommand
             );
 // Create a command from the session object
    hr = pIDBCreateCommand->CreateCommand(
             NULL,
             IID_ICommandText,
             (LPUNKNOWN*) &pICommandText
             );
 // Set the CommandText for the Query
    hr = pICommandText->SetCommandText(
             rguidDialect,
             pszCommandText
             );
// Set the properties on the Command Object
    if (cCmdPropSet) {
        hr = pICommandText->QueryInterface(
                 IID_ICommandProperties,
                 (void**) &pICommandProperties);
        hr = pICommandProperties->SetProperties(
                 cCmdPropSet,
                 rgCmdPropSet);
    }

    hr = pICommandText->QueryInterface(
             IID_ICommand,
             (void**) &pICommand);

 // Do the Query and get back a rowset
    hr = pICommand->Execute(
             NULL,
             IID_IRowset,
             NULL,
             NULL,
             (LPUNKNOWN *)&pIRowset
             );
    hr = pIRowset->QueryInterface(
             IID_IColumnsInfo,
             (void**) &pIColsInfo
             );
    hr = pIColsInfo->GetColumnInfo(
             &cCol,
             &prgColInfo,
             &szColNames
             );
 // The no. of attributes is one less than the no. of columns because of
 //  the Bookmark column
    nAttrs = cCol - 1;
    pMyStatus = (DBBINDSTATUS *) LocalAlloc(
                                     LPTR,
                                     sizeof(DBBINDSTATUS) * nAttrs
                                     );
    hr = CreateAccessorHelper(
             pIRowset,
             nAttrs,
             prgColInfo,
             &myAccessor,
             pMyStatus
             );
    pMyData = (Data *) LocalAlloc(
                           LPTR,
                           sizeof(Data) * nAttrs
                           );
    //  Get the rows; 256 at a time
    phRows = NULL;
    hr = pIRowset->GetNextRows(
             NULL,
             0,
             256,
             &cRowsObtained,
             &phRows
             );
    j = cRowsObtained;
    while (cRowsObtained) {
        for (i = 0; i < cRowsObtained; i++) {
 // Get the data from each row
            hr = pIRowset->GetData(
                     phRows[i],
                     myAccessor,
                     (void*)pMyData
                     );
           PrintData(pMyData, nAttrs, prgColInfo);
        }
        pIRowset->ReleaseRows(
                      cRowsObtained,
                      phRows,
                      NULL,
                      NULL,
                      NULL
                      );
 // Get the next 256 rows
        hr = pIRowset->GetNextRows(
                 NULL,
                 0,
                 256,
                 &cRowsObtained,
                 &phRows
                 );
        j+=cRowsObtained;
    }
    printf("Rows printed = %d\n", j);
    exit(0);

}


Using ADO for Querying

The following example shows how Automation clients can use ActiveX Data Objects (ADO) to query directory services using ADSI and its OLE DB implementation. The ADO object model consists of the following objects:

Connection
An open connection to an OLE DB data source such as ADSI.
Command
Defines a specific command to execute against the data source.
Parameters
An optional collection for any parameters to provide to the command object.
Recordset
A set of records from a table, command object, or SQL syntax. A recordset can be created without any underlying Connection object.
Field
A single column of data in a recordset.
Property
A collection of values supplied by the provider for ADO.
Error
Contains details about data access errors, refreshed for each time an error occurs in a single operation.

For more information, see the Microsoft Platform SDK under ActiveX Data Objects.

The following example disables the user accounts on an ldap server.

Dim X as IADs
Dim con As New Connection, rs As New Recordset
Dim MyUser As IADsUser

con.Provider = "ADsDSOObject"
con.Open "Active Directory Provider", "CN=Foobar,CN=Users,DC=MICROSOFT,DC=COM,O=INTERNET", "Password"
Set rs = con.Execute("<LDAP://ldapserver.microsoft.com/O=Internet/DC=COM/DC=MICROSOFT/OU=MyOrg>;(objectClass=User);ADsPath;onelevel")

While Not rs.EOF
    MyUser = GetObject(rs.Fields(0).Value)
    MyUser.AccountDisabled = True
    rs.MoveNext
Wend


Using IDirectorySearch for Querying

In addition to the search capabilities supported by the ADSI OLE DB provider, ADSI supplies the IDirectorySearch interface to query directly directory services for non-Automation clients. IDirectorySearch requires almost the same search information as the methods of the OLE DB interfaces, but reduces the programming overhead. Use IDirectorySearch when you just want to specify a query and get the results back without any of the richer navigation features supplied when using OLE DB queries.

When implemented by a provider, IDirectorySearch is supported on every ADSI object. For information on which providers support this interface, see ADSI System Providers.

Use IDirectorySearch::SetSearchPreference to set the preferred settings for your query. Once your preferences are created, use ExecuteSearch to initiate the query. Query results are exposed in the form of a table. Each row is one entry of the result. Each column within the row represents an attribute or property. The following figure shows a simplified representation of how the query process works.

Use GetNextRow to advance the search handle shown in the preceding figure row by row, and GetNextColumnName with GetColumn to retrieve results from the columns. With each row you step through the columns of interest looking for the attributes that match. This process continues until there are no more rowsets in the query results.

The following ADSI example shows a simple command-prompt program that uses the IDirectorySearch interface to query a directory service. This sample has been edited, primarily by removing error checking, to simplify the flow. The complete example code is included in the ADSI SDK in the samples/activeds/sampapp/cxx/dssrch directory.

Usage: dssrch /b <baseObject> /f <search_filter> [/f <attrlist>] [/p <preference>=value>]  [/u <UserName> <Password>] [/t <flagName>=<value>

   where:
   baseObject     = ADsPath of the base of the search
   search_filter  = search filter string in LDAP format
   attrlist       = list of the attributes to display
   preference could be one of:
   Asynchronous, AttrTypesOnly, DerefAliases, SizeLimit, TimeLimit,
   TimeOut, PageSize, SearchScope
   flagName could be one of:
   SecureAuth or UseEncrypt
   value is yes/no for a Boolean and the respective integer for integers
   scope is one of "Base", "OneLevel", or "Subtree"

For Example: dssrch /b NDS://ntmarst/ms /f "(object Class=Group)"  /a  "ADsPath, name, description" /p searchScope=onelevel

//------------------------------------------------------------------
//
//  Microsoft Windows
//  Copyright (C) Microsoft Corporation, 1992 - 1997.
//
//-------------------------------------------------------------------
#define INC_OLE2
#include <windows.h>
#include <stdlib.h>
#include <limits.h>
#include <io.h>
#include <stdio.h>
#define BAIL_ON_NULL(p) if (!(p)) {goto error;}
#define BAIL_ON_FAILURE(hr) if (FAILED(hr)) {goto error;}

#include "activeds.h"
#include "main.hxx"
// Globals representing parameters on IDirectorySearch
LPWSTR pszSearchBase, pszSearchFilter, pszAttrNames[10], pszAttrList;
DWORD dwNumberAttributes = -1;
// Preference Values
BOOL fASynchronous=FALSE, fDerefAliases=FALSE, fAttrsOnly=FALSE;
DWORD fSizeLimit, fTimeLimit, dwTimeOut, dwPageSize, dwSearchScope;

ADS_SEARCHPREF_INFO pSearchPref[10];
DWORD dwCurrPref = 0;

LPWSTR pszUserName=NULL, pszPassword=NULL;
DWORD dwAuthFlags=0;
DWORD cErr=0;

char *prefNameLookup[] =
    {
    "ADS_SEARCHPREF_ASYNCHRONOUS",
    "ADS_SEARCHPREF_DEREF_ALIASES",
    "ADS_SEARCHPREF_SIZE_LIMIT",
    "ADS_SEARCHPREF_TIME_LIMIT",
    "ADS_SEARCHPREF_ATTRIBTYPES_ONLY",
    "ADS_SEARCHPREF_SEARCH_SCOPE",
    "ADS_SEARCHPREF_TIMEOUT",
    "ADS_SEARCHPREF_PAGESIZE",
    "ADS_SEARCHPREF_PAGED_TIME_LIMIT",
    "ADS_SEARCHPREF_CHASE_REFERRALS"
    };

//+-----------------------------------------------------------------
//  Function:   main
//------------------------------------------------------------------
INT _CRTAPI1
main(int argc, char * argv[])
{

    hr = CoInitialize(NULL);
    hr = ADsOpenObject(
        pszSearchBase,
        pszUserName,
        pszPassword,
        dwAuthFlags,
        IID_IDirectorySearch,
        (void **)&pDSSearch
        );

    if (dwCurrPref) {
        hr = pDSSearch->SetSearchPreference(
                 pSearchPref,
                 dwCurrPref
                 );
        BAIL_ON_FAILURE(hr);
        }

    hr = pDSSearch->ExecuteSearch(
             pszSearchFilter,
             pszAttrNames,
             dwNumberAttributes,
             &hSearchHandle
              );      BAIL_ON_FAILURE(hr);

    hr = pDSSearch->GetNextRow(
             hSearchHandle
             );     BAIL_ON_FAILURE(hr);

    while (hr != S_ADS_NOMORE_ROWS) {
        nRows++;

        if (dwNumberAttributes == -1) {
            hr = pDSSearch->GetNextColumnName(
                     hSearchHandle,
                     &pszColumnName
                     );             BAIL_ON_FAILURE(hr);

            while (hr != S_ADS_NOMORE_COLUMNS) {
                hr = pDSSearch->GetColumn(
                         hSearchHandle,
                         pszColumnName,
                         &Column
                         );

                if (FAILED(hr)  && hr != E_ADS_COLUMN_NOT_SET)
                    goto error;

                if (SUCCEEDED(hr)) {
                    PrintColumn(&Column, pszColumnName);
                    pDSSearch->FreeColumn(&Column);
                }

             if (pszColumnName)
             free(pszColumnName);
                hr = pDSSearch->GetNextColumnName(
                         hSearchHandle,
                         &pszColumnName
                         );      BAIL_ON_FAILURE(hr);
            }
            printf("\n");
        }
        else {
            for (unsigned int i=0; i<dwNumberAttributes; i++) {
                hr = pDSSearch->GetColumn(
                         hSearchHandle,
                         pszAttrNames[i],
                         &Column
                         );

                if (hr == E_ADS_COLUMN_NOT_SET)
                    continue;

                BAIL_ON_FAILURE(hr);

                PrintColumn(&Column, pszAttrNames[i]);

                pDSSearch->FreeColumn(&Column);
            }
        printf("\n");
        }

        hr = pDSSearch->GetNextRow(
                 hSearchHandle
                 );
        BAIL_ON_FAILURE(hr);
    }

    wprintf (L"Total Rows: %d\n", nRows);

    if (cErr) {
        wprintf (L"%d warning(s) ignored", cErr);
    }

    if (hSearchHandle)
        pDSSearch->CloseSearchHandle(hSearchHandle);

    FREE_INTERFACE(pDSSearch);

    FREE_UNICODE_STRING(pszSearchBase) ;
    FREE_UNICODE_STRING(pszSearchFilter) ;
    FREE_UNICODE_STRING(pszAttrList) ;

    CoUninitialize();

    return(0) ;

error:
//  Error handling
}


Debugging Hints

Here are some hints for the most common errors experienced by first-time ADSI application writers:

Case-sensitivity
The ProgIDs for ADSI are case sensitive! This is a feature of the underlying namespace because some directory services use case sensitive path names. For example, when you call ADsGetObject with an ADsPath name for the ADSI LDAP provider, use "LDAP:" and not "ldap:".
VT_BOOLEAN for Automation clients
A reminder that VT_BOOLEAN is defined as -1, not 1.
Dim for Automation clients
The Dim() statement sets the upper bound of an array. For example, if you Dim(8), you get an array of size 9 where the first element index is 0 and the last element index is 8. If you initialize just 8 elements of the array and pass the result to an ADSI method expecting an initialized VARIANT, Visual Basic errors out.
Binding to an object over the net
If you are having trouble getting ADsGetObject to get past the server connection and return without error, try accessing the same ADsPath string through a command prompt window, using the "net use <ADsPath>".For example, if
GetObject("WinNT://MyDomain/MyComputer")

results in an error, enter the following at the command prompt:

>net use * \\MyDomain\netlogon

If you can successfully execute the command prompt syntax, you know your ADsPath is accurate and that your network connections are valid and can continue to look elsewhere for the problem.

Not finding properties for an object
In some implementations of ADSI, there is a direct correspondence between the properties listed in a schema definition for an object and the underlying properties in a directory service. In other implementations of ADSI, the property names included in the mandatory and optional attribute lists of the schema class object may be simulated from various places in the underlying system to supply an easy way to work with these properties. In both cases, when client software calls .get or get_propertyname and a corresponding property does not exist in the underlying directory service, E_ADS_PROPERTY_NOT_FOUND is returned. Whether the underlying directory service property had never been set or there is no underlying value, the client code should handle the result gracefully. For more information about how the property cache works, see Property Cache.


Automation Examples

This section contains short code examples in Visual Basic® for ADSI client applications.

Automation - Retrieving a Property From an ADSI Object

Automation - Browsing a Schema Class Definition

Automation - Adding Users to a Group

Automation - Removing Users From a Group

Automation - Listing Children in a Container

Automation - Enumerating Users in a Group

Automation - Creating a User Object

Automation - Deleting a User Object

Automation - Using a Filter


Automation - Retrieving a Property From an ADSI object

The following example retrieves a property directly from an ADSI object using the standard IADsUser interface and the Fullname property it supports.

Dim MyUser as IADsUser
Dim MyName as String

Set MyUser = GetObject("NDS://O=MyOrg/OU=SomeOU/CN=JamesSmith")
MyName = MyUser.Fullname

The following example retrieves a property by name from an object using IADs::Get. If the property is multivalued, IADs::GetEx must be used. Note that because IADsUser inherits from IADs, the methods supported by IADs are automatically accessible.

Dim MyUser as IADsUser
Dim MyName as String

set MyUser = GetObject("NDS://O=MyOrg/OU=SomeOU/CN=JamesSmith")
MyName = MyUser.Get("Fullname")

The following example uses IADsPropertyList using the Next method to retrieve all the properties on a given object from an LDAP server.

Dim MyVar As Variant
Dim MyADsPropList As IADsPropertyList
Dim MyADsObj As IADsOpenDSObject
Dim DN As String
Dim UserName As String
Dim Password As String
Dim propcount As Integer

'Bind to specific object
DN = "LDAP://MyServer/dc=Mydomain,dc=microsoft,dc=com,o=internet"
UserName = "cn=Administrator,cn=Users,dc=Mydomain,dc=microsoft,dc=com,o=internet"
Password = "password"
Set MyADsObj = GetObject("LDAP:")
Set MyADsPropList = MyADsObj.OpenDSObject(DN, UserName, Password, 0)

' Get the properties into the cache !
MyADsPropList.GetInfo

'Get the Number of Properties in the list and walk the list
propcount = MyADsPropList.PropertyCount

Debug.Print "There are ", propcount, " properties."

For i = 1 To propcount
    Set MyVar = MyADsPropList.Next
    Debug.Print "The property Name from Variant is "; MyVar.Name
Next

On Error Resume Next
' This call will fail !
Set MyVar = MyADsPropList.Next
If Err.Number Then
    Debug.Print Err.Number; " Occurred "
    Err.Clear
End If

' Now Reset the property Index and and then call next
' This will return the first value
MyADsPropList.Reset
Set MyVar = MyADsPropList.Next
Debug.Print "The first element in the list has the name ", MyVar.Name


Automation - Browsing a Schema Class Definition

This example uses the Windows NT provider schema.

Dim Computer As IADsComputer
    Dim Class As IADsClass
    Dim Property As IADsProperty
    Dim V As Variant
    Dim I As Integer

    Set c = GetObject("WinNT://MyDomain/MyMachine,Computer")
    Set Class = GetObject(c.Schema)

    Debug.Print "Class: " & Class.Name
    Debug.Print "GUID: " & Class.GUID
    Debug.Print "Implemented by: " & Class.CLSID

    If Class.Container Then
        Debug.Print "Container Object"
        Debug.Print "Class Contains:"
        For Each V In Class.Containment
            Debug.Print "   "; V
        Next V
    Else
        Debug.Print "Leaf Object"
    End If

    Debug.Print "Properties in this Class: "
    For Each V In Class.MandatoryProperties
        Debug.Print "   "; V
    Next V
    For Each V In Class.OptionalProperties
        Debug.Print "   "; V
    Next V


Automation - Adding Users to a Group

Dim Group as IADsGroup

' Bind to a known group object.
Set Group = GetObject("WinNT://MyDomain/Groups/Administrators")

' Add Jane and John to the Administrators group.
Group.Add("WinNT://MyDomain/Users/John")
Group.Add("WinNT://MyDomain/Users/Jane")


Automation - Removing Users From a Group

Dim Group as IADsGroup

' Bind to a known group object.
Set Group = GetObject("WinNT://MyDomain/Groups/Administrators")

' Remove Jane and John from the Administrators group.
Group.Remove("WinNT://MyDomain/Users/John")
Group.Remove("WinNT://MyDomain/Users/Jane")


Automation - Enumerating Users in a Group

Dim Group as IADsGroup
Dim Member as IADs

' Bind to a known group object.
Set Group = GetObject("WinNT://MyDomain/Administrators")

' Enumerate the members in the group.
For Each Member in Group.Members
    Debug.Print Member.Name
Next Member


Automation - Creating a User Object

Dim Container as IADsContainer
Dim NewUser as IADsUser

' Bind to the known container.
Set Container = GetObject("WinNT://MyDomain")

' Create the new wrapper.
Set NewUser = Container.Create("user", "Jane")
' Write it back to the DS
NewUser.SetInfo

' Set Jane's password.
NewUser.SetPassword("PW.1234")


Automation - Listing Children in a Container

Dim MyObject as IADs
Dim Child as IADs
Dim Container as IADsContainer

On Error Resume Next
Set MyObject = GetObject("WinNT://MyDomain/Group/Admin")
Set Container = MyObject

If Err = 0 Then
    For Each Child in Container
        Debug.Print Child.Name
    Next Child
EndIf


Automation - Deleting a User Object

Dim Container as IADsContainer
Dim User as IADsUser
Dim UserPath as String

' Bind to the known object.  In this case, we happen to know
' the explicit path, but typically the object will be discovered
' using query or enumeration.
Set User = GetObject("WinNT://MyDomain/Users/Jane")

' Get the container of the user object.
Set Container = GetObject(User.Parent)

' Delete the user.
Call Container.Delete("user",User.name)

' Release the user object.  Note that we deleted
' the underlying DS object, so we should not hang on to the user
' component.
Set User = Nothing


Automation - Using a Filter

The Example is TBD.


Automation Examples Using Java

This section contains short code samples that show simple ADSI operations like binding and object creation and deletion. The expanded code samples that include complete java code are included in the SDK samples directory.

A Java implementation of ADSI is a separate product found under JavaADSI and is part of the Application Foundation Classes (AFC).


Java - Binding to an ADSI Object

// bind.java - Edited simple demonstration of binding
//     a DS object using AFC ADSI.
//     Any comment beginning "// ..." means java codes lines have
//         been deleted for simpler logic flow. For complete code,
//         see ADSI samples.
//
// Copyright © 1997 Microsoft Corporation
// All Rights Reserved
//
// ... import statements

class bind
{
   private ADsConn m_conn = null;
   private IADs    m_adsobj = null;
   private IADsOpenDSObject    m_namespace = null;

   String iniFileName = ".\\jadsi.ms";
   // ... Initializations

   public static void main(String args[])
   {
      bind bindObject = null;

      // ... Check the arguments on input
      if (bindObject != null) {
          bindObject.bindToObject();
    }

   }

   public bind()
   { // ... Prompt for ADsPath, UserName, Passwd }

   public bind(String args[])
   { // ... Get ADsPath, UserName, PassWd from the args array }

   public void bindToObject()
   {
   try  {  // Process the .ini file to set up AFC ADSI
      m_conn = new ADsConn(iniFileName);
   }  // ... plus error handling

   try {  // instantiate the LDAP namespace object
       m_namespace = (IADsOpenDSObject)m_conn.getObject("LDAP:");

       // Fetch a DS object using the specified parameters.
       m_adsobj = (IADs)m_namespace.OpenDSObject(ADsPath, UserName,
                   PassWd, 0);
       // ... print out IADs object properties
   } // ... plus error handling

   // ... Exit code
   }
}


Query Examples Using ADO

The following code shows how to connect to a directory service, access an ADSI provider, and query an object.

Dim QuerySTring As String
Dim MyConnection As New Connection
Dim MyRecordset As Recordset
Dim i As Integer
Dim Msg As String
Dim vRecsAffected As Variant
Dim liTemp As ListItem

On Error GoTo errhand

' Ask for and get credentials if necessary.

If (fLogin.mylogin) Then

    FormQuery.MousePointer = vbHourglass
    ' Set the query string
    QuerySTring = sDn + ";" + sQuery + ";" + sReturnAttributes
    ' Add adspath to the return string.
    QuerySTring = QuerySTring + ",adspath"
    ' Add the scope
    If iScope = SCOPEBASE Then
        QuerySTring = QuerySTring + ";Base"
    ElseIf iScope = SCOPE1LVL Then
        QuerySTring = QuerySTring + ";OneLevel"
    ElseIf iScope = SCOPESUBTREE Then
        QuerySTring = QuerySTring + ";SubTree"
    Else
        MsgBox "internal err"
    End If

    ' Set the connection object props
    MyConnection.Provider = "ADsDSOObject"
    MyConnection.Open "ADs Provider", szUserName, szPassword
    Set MyRecordset = MyConnection.Execute(QuerySTring, vRecsAffected, adCmdUnspecified)
    ' Prepare listview
    FormQuery.ListView1.ColumnHeaders.Clear
    FormQuery.ListView1.ListItems.Clear
    ' Put in listview column headers for the number of attributes.

    For i = 0 To MyRecordset.Fields.Count - 1
        FormQuery.ListView1.ColumnHeaders.Add , , CStr(MyRecordset.Fields(i).name), _
         (FormQuery.ListView1.Width / MyRecordset.Fields.Count)
    Next i

    ' Loop through each row returned and display.
    While Not MyRecordset.EOF
        For i = 0 To MyRecordset.Fields.Count - 1
            On Error GoTo NOHANDLE
            DoEvents                'Handle events
            If i = 0 Then
                ' Add main column item to list view.
                If Not IsNull(MyRecordset.Fields(i)) Then sString = CStr(MyRecordset.Fields(i)) Else sString = "Null"
                Set liTemp = FormQuery.ListView1.ListItems.Add(, , sString)
            Else
                If Not (IsEmpty(MyRecordset.Fields(i))) Then
                    If Not (IsNull(MyRecordset.Fields(i))) Then sString = CStr(MyRecordset.Fields(i)) Else sString = "Null"
                    liTemp.SubItems(i) = sString
                End If

                On Error GoTo errhand
           End If
        Next i
        iQueryAdsPathArrayIndex = i
        sString = ""

        MyRecordset.MoveNext
    Wend

    FormQuery.MousePointer = Default
    If FormQuery.ListView1.ListItems.Count = 0 Then MsgBox "No records returned"

End If


COM Vtable Examples

This section contains short code examples in C or C++ for ADSI client applications and one longer example for query.


COM Vtable Examples - Querying a Namespace

See Using IDirectorySearch for Querying.


COM Vtable Examples - Setting Properties

IADsUser  *pUser;
BSTR      bstrDescription;
BSTR      bstrTitle;
VARIANT   vHints;

//
// Bind to the user object.
//
ADsGetObject(TEXT("WinNT://MyDomain/Users/John"),
             IID_IADsUser,
             (void**)&pUser);

//
// Allocate the strings for the changes.
//
bstrDescription = SysAllocString(TEXT("Johnny"));
bstrTitle = SysAllocString(TEXT("General Manager"));
bstrPassword = SysAllocString(TEXT("PW.123"));

//
// Change the Description and title of the user.  The changes
// are made in the local cache only.
//
pUser->put_Description(bstrDescription);
pUser->put_Title(bstrTitle);

//
// Call SetInfo to commit the changes to the network.
//
pUser->SetInfo();

//
// Now change the user's password - this non-property method
// executes immediately.
//
pUser->SetPassword(bstrPassword);
//
// Refresh the ADSI object with a call to GetInfo.
//     No hints are specified.
//
VariantInit(&vHints);
V_VT(&vHints) = VT_EMPTY;
pUser->GetInfo(vHints);
//
// Clean up and reuse the strings.
//
SysFreeString(bstrDescription);
SysFreeString(bstrTitle);
SysFreeString(bstrPassword);
//
// Retrieve values from the object.
//
pUser->get_Description(&bstrDescription);
pUser->get_Location(&bstrTitle);
printf("%s, %s", bstrDescription, bstrTitle);
//
// Release all interfaces.
//
pUser->Release();


COM Vtable Examples - Adding Users to a Group

IADsGroup *pGroup;

//
// Bind to a known group object.
//
ADsGetObject(TEXT("WinNT://MyDomain/Groups/Administrators"),
             IID_IADsGroup,
             (void**)&pGroup);

//
// Add Jane and John to the Administrators group.
//
pGroup->Add(TEXT("WinNT://MyDomain/Users/John"));
pGroup->Add(TEXT("WinNT://MyDomain/Users/Jane"));

//
// Cleanup.
//
pGroup->Release();


COM Vtable Examples - Removing Users from a Group

//
IADsGroup *pGroup;
//
//
// Bind to a known group object.
//
ADsGetObject(TEXT("WinNT://MyDomain/Groups/Administrators"),
             IID_IADsGroup,
             (void**)&pGroup);
//
// Remove Jane and John from the Administrators group.
//
pGroup->Remove(TEXT("WinNT://MyDomain/Users/John"));
pGroup->Remove(TEXT("WinNT://MyDomain/Users/Jane"));
//
// Cleanup.
//
pGroup->Release();


COM Vtable Examples- Enumerating Users in a Group

IADsGroup *pGroup;
IADsMembers *pMembers;
IEnumVARIANT *pEnum;
IADs *pMember;
BSTR bstrMemberName;
//
// Bind to a known group object.
//
ADsGetObject(TEXT("WinNT://MSFT/Groups/Administrators"),
             IID_IADsGroup,
             (void**)&pGroup);
//
// Get the Members collection.
//
pGroup->Members(&pMembers);

//
// Get an enumerator.  ADsBuildEnumerator is a helper
// function supplied by ADSI.  See Appendix B for more
// details.
//
ADsBuildEnumerator((IADsContainer *)pMembers,
                    &pEnum);

//
// Enumerate through all the children of the container.
// ADsEnumerateNext is a helper function supplied by ADSI.
// See Appendix B for more details.
//
do {
    hr = ADsEnumerateNext(pEnum,
                         1,
                         (void**)&pMember,
                         NULL);
    if (SUCCEEDED(hr))
        {
        pMember->get_Name(&bstrMemberName);
        printf("%s\n", bstrMemberName);
        SysFreeString(bstrMemberName);
        pMember->Release();
        } // if
    } while (SUCCEEDED(hr)); // do
//
// Cleanup.
//
pEnum->Release();
pMembers->Release();
pGroup->Release();


COM Vtable Examples - Creating a User Object

IADsContainer *pContainer;
IADs     *pNewObject;
IADsUser *pUser;

//
// Bind to the known container.
//
ADsGetObject(TEXT("WinNT://Mydomain"),
             IID_IADsContainer,
             (void**)&pContainer);
//
// Create the new wrapper.
//
pContainer->Create(TEXT("user"),
                   TEXT("Jane"),
                   &pNewObject);
//
// Get the IADsUser interface from the wrapper.
//
pNewObject->QueryInterface(IID_IADsUser, &pUser);
//
// Write it back to the DS.
//
pUser->SetInfo();
//
// Set Jane's password.
//
pUser ->SetPassword(TEXT("PW.1234"));
//
// Cleanup.
//
pContainer->Release();
pNewObject->Release();
pUser->Release();


COM Vtable Examples - Deleting a User Object

IADsContainer *pContainer;
BSTR     bstrContainerPath;
IADsUser *pUser;
BSTR     bstrUserName;
//
// Bind to the known object.  In this case, we happen to know
// the explicit path, but typically the object will be discovered
// using query or enumeration.
//
ADsGetObject(TEXT("WinNT://MSFT/Users/Jane"),
             IID_IADsUser,
             (void**)&pUser);
//
// Get the container object path.
//
pUser->get_Parent(&bstrContainerPath);
//
// Get the container object.
//
ADsGetObject(bstrContainerPath,
             IID_IADsContainer,
             (void**)&pContainer);
//
// Get the user object's name.  (This step is unneccesary in
// this example since we already know the name, but is included to
// indicate that we either need to know the name, or have a ptr
// to the object).
//
pUser->get_Name(&bstrUserName);
//
// Release the user object.  Note that we are about to delete
// the underlying DS object, so we should not hang on to the user
// component.
//
pUser->Release();
//
// Delete the user.
//
pContainer->Delete(TEXT("user"),bstrUserName);
//
// Cleanup.
//
SysFreeString(bstrContainerPath);
SysFreeString(bstrUserPath);
pContainer->Release();


ADSI for Providers

Active Directory Service Interfaces are COM interfaces that wrap directory service objects to make them accessible to clients of directory services. By supplying an implementation of ADSI, you expand your clientele to the set of ADSI client applications.

As with any COM implementation, you can write an ADSI provider in many languages. The ADSI COM interfaces are defined as dual interfaces that allow both run-time and compile-time name resolution and can be called by Automation-compliant languages like Microsoft Visual Basic, Visual Basic Scripting, and Java, and also the more performance and efficiency-conscious languages such as C and C++. ADSI clients also include web applications using Active Server Pages and administration snap-ins through the Microsoft Management Console.

Because ADSI supplies its own OLE DB provider, implementing the search functionality defined by IDirectorySearch also enables ADSI clients to query your directory service for information of interest.

All directory service objects can be represented through a generic ADSI object supporting IDirectoryObject. ADSI supplies the building blocks necessary to represent the features and services of any directory service.

In addition, the ADSI meta-interfaces represent common objects used by directory administrators. You map the properties of the meta-interfaces to the properties supported by your directory service. ADSI clients programming to the Active Directory Service Interfaces gain access to your directory service as soon as the provider is installed and the system re-started.

If your directory service supports a schema representation, supporting the schema management interfaces makes your namespace directly accessible to directory service browsers. By publishing your features through the schema, clients can query your directory service on-line and take advantage of the services you offer. Because of the on-line schema availability and the COM interface advantage, you can continue to make new functionality available to your client software while supporting down-level versions.


Provider Minimum Requirements

To write an ADSI provider, implement the Active Directory Service interfaces as described in the following sections.

  • Core Implementation briefly lists those software elements that an ADSI provider must support.
  • Optional Implementation briefly lists those software elements that an ADSI provider is strongly encouraged to support.
  • Custom properties are those properties and interfaces exposed by each provider to provide programmability of the native features of the directory service.
  • Dual Interfaces describe the ADSI convention to supply interfaces that are accessible both to Automation and non-Automation compliant controllers.


Core Implementation

An ADSI provider supports the following features.

  • ADsPath strings in both COM and URL format. By definition, an Active Directory object can always be retrieved using an ADsPath. For the ADsPath syntax definition, see ADsPaths. Providers support whatever syntax their directory service requires using the ParseDisplayName implementation described in the next bulleted item.
  • A top-level Namespace object that supports IParseDisplayName::ParseDisplayName and IADsOpenDSObject. This object contains the root nodes for this namespace. Part of the ParseDisplayName implementation must include a parser that checks for syntax errors for its own namespace. This object must also support IADs and IADsOpenDSObject.
  • The IADs interface. This includes a simple property cache implementation through IADs::GetInfo and IADs::SetInfo. Operations that get or set object properties occur in cached mode. Cache values are written to the underlying directory store during SetInfo. An ADSI method, however, is not cached, but executes immediately.
  • The IADsPropertyList , IADsPropertyEntry and IADsPropertyValue interfaces for directly accessing and enumerating the properties in the property cache. For directory services that do not expose a schema, this interface allows you to manipulate the properties of an object.
  • The IDirectoryObject interface for non-Automation clients. This uses on-the-wire protocol for maximum performance and bypasses the property cache.
  • The IADsContainer interface. Every Active Directory object has a parent container that controls its lifetime. Note that on ADs container objects, GetInfo affects only the container properties and not its contents. SetInfo on ADs container objects affects only newly created objects and the container properties, and does not affect objects that already exist within the container.
  • The IDispatch interface. This is the Automation interface for languages like Java and Visual Basic that do not use compile-time binding. Related to this is the type library information that a provider must supply. For more information, see Implementation Issues for ADSI Providers.
  • A schema class container object and the appropriate syntax, property, and schema class objects that support IADsSyntax, IADsProperty, and IADsClass respectively. At a minimum, each root node must contain its own schema class container object.
  • The IADsMembers interface, if any supported attributes are collections of ADSI objects, such as security groups.
  • The IADsCollection interface, if any supported attributes are collections of the same directory element type with Add and Remove capability.
  • The IEnumXXXX enumeration support for all specific enumerator objects.
  • Routines to map syntax and convert native data to the VARIANT data type. ·Follow ADSI conventions for provider-supplied ADSI objects. Include help files and type libraries documenting the interface properties and methods. See
  • Meta-Schema Interfaces, a minimal implementation required. Because you map your directory service names for the appropriate attributes to the ADSI property names when implementing the meta-interfaces, client applications can display directory service objects in a uniform manner across all directory services.
  • As with any COM implementation, you must return E_NOTIMPL for unimplemented interfaces and E_ADS_PROPERTY_NOT_SUPPORTED for unimplemented properties. For more information about dual interfaces and how they affect property implementation, see Dual Interfaces.


Optional Implementation

The following features are optional, but highly recommended.

  • The IDirectorySearch interface for non-Automation clients. Because the ADSI OLE DB provider uses IDirectorySearch to present queries and collect results from the underlying directory service, providers that implement this interface gain access to OLE DB style databases for no extra effort.
  • The IADsSecurityDescriptor, IADsAccessControlList, and IADsAccessControlEntry interfaces. Providers for directory services that support ACL-based object security are strongly encouraged to implement this additional functionality.


Custom Properties

Providers can expose additional objects, interfaces, and properties not defined by the ADSI meta-schema.

Further details on implementation guidelines for providers can be found throughout ADSI Reference under Notes to Implementers. Examples of most of the items listed above can be found in ADSI Example Provider Component.


Dual Interfaces

Use COM interfaces to access the properties and methods on any provider ADSI objects. A read-only property maps to an interface entry of the form get_<PropertyName>. A read/write property maps to two interface entries of the form get_<PropertyName> and put_<PropertyName>.

All methods on a COM interface must:

  • Return an HRESULT value to indicate success or failure. The HRESULT type is discussed in the COM specification.
  • Return E_NOTIMPL for interfaces that have not been implemented.
  • Return E_ADS_PROPERTY_NOT_SUPPORTED for interface properties that are not supported.

To retain compatibility with Automation controllers, all parameters and return types should be within the subset defined by the Automation VARIANT data type. For more information, see VARIANT and VARIANTARGS in the Microsoft Platform SDK.

A provider Active Directory object can expose interfaces that use data types other than those in the VARIANT subset. However, Automation controllers such as Visual Basic and Java will not be able to call those interfaces. Since all ADSI provider interfaces are derived from IDispatch, they can be used as IDispatch interface pointers.


Provider Overview

Besides the Provider Minimum Requirements, other information you may find useful as a provider writer includes:

  • ADSI Component Interaction describes the context in which the provider component runs.
  • Schema Interfaces discuss the schema management interfaces from the provider's point of view.
  • Enumerating Container Objects describes the requirements to support enumerations.
  • Provider Registry Information lists the registry entries an ADSI provider uses.
  • Support for Queries
  • Implementation Issues for ADSI Providers includes notes to providers about various software issues.


ADSI Component Interaction

The Active Directory router component populates an ADSI provider table from the installed ADSI providers listed in the registry when it receives its first request from the client application. Registry information can be found in Installing the Example Provider Component.

Operations that make a request from a directory for a pointer to an interface on an Active Directory object come through a function (GetObject in Visual Basic or Java or ADsOpenObject or ADsGetObject in C or C++), or an interface method (IADsContainer::GetObject). In the following figure, the ADSI client application passes such a bind request to the ADSI router component (1). The router component identifies the ProgID for the provider from the first part of the ADsPath and uses CLSIDFromProgID to find the matching CLSID in the registry(2) and loads the proper provider component (3).

ADSI Component Interactions in the Example Provider.

In the preceding figure, the provider component creates an Active Directory object representing the named directory element. The ADSI support component does a QueryInterface on the requested interface identifier. Once a pointer to that interface is retrieved (4), as with all COM client/server implementations, it is then passed back to the client (5), and from then on the client application works directly with the provider component (6).


Schema Interfaces

The schema interface IADsClass is available to represent a directory service class. It is used to represent a provider's directory service class. The IADsProperty interface represents a single or multi-valued property from the directory service. The IADsSyntax interface represents a single VARIANT type.

Providers supplying their own ADSI implementations supply schema management objects supporting these interfaces that reflect their underlying namespace.

Interfaces defined by ADSI can support specific properties and syntaxes, such as IADsUser and IADsOU. For the complete list, see ADSI Interface Definitions. Providers can choose to extend an ADSI definition by using the methods that create and access properties IADs::Get, IADs::GetEx, IADs::Put, and IADs::PutEx. Providers can also choose to support additional properties through additional interfaces.

The schema container is used to attach a set of schema definitions to part of a provider's namespace tree. Typically, each instance of a namespace has its own schema. For example, in the following figure, the ADSI example provider defines a schema container in each of the root nodes "Seattle" and "Toronto".

ADSI Schema Objects in the Example Provider

An ADSI provider component with a complex namespace might allow multiple schemas to exist in a namespace instance, each at a different part of the tree. An object's IADs::Schema property, however, always names its own the schema definition.


Schema Extensions

Because of the architecture of the ADSI schema, new schema classes can be added to the schema class container and new properties to an existing schema class object at run time. The latter ability requires no new code, and for namespaces that allow extensible directory services, this is an important feature. The provider component must allow for this extensibility and know where to access and store the class instance and the values of its properties. In a typical extensible directory service, this information is stored in the directory service database in the same manner as any other schema class and property definitions.

Note In COM interface terminology, only properties can be added to an existing schema class, not methods. Adding a new method would require adding a new implementation of that method and thus require additional code.

For an example of a specific provider schema, see Schema Management.


Enumerating Container Objects

By convention, all items in an enumeration in ADSI must be of the same Automation data type. For example, an enumeration should not return some items as VARIANTs of type VT_I4 and others as VARIANTs of type VT_BSTR.

To enumerate a list of items that an object maintains, a client requests the creation of an enumeration object for the specific type of information being listed. In ADSI, the client may list the objects in namespace objects, generic container objects, collection objects, member objects, or schema objects. ADSI provides a filter that can be set and modified to limit the matches in any enumeration though IADsContainer::Filter. Examples of implementations of enumerator objects can be found in the example provider component code for the following ADs container objects.

Object type | code
Generic Container | cenumobj.cpp
Namespace Container | cenumns.cpp
Schema Container | cenumsch.cpp

For client-side information, see About Collections and Groups .


Provider Registry Information

Under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ADs\Providers subkey, an ADSI provider must have the following subkeys and values:

ProgIDNamespace = Friendly Name

Under the HKEY_CLASSES_ROOT\CLSID subkey, provider namespace objects must have the following subkeys and values:

ProgIDNamespaceCLSID = FriendlyDisplayName

ProgIDNamespaceCLSID\InProcServer32 = ProviderDLLFilename

ProgIDNamespaceCLSID\InProcServer32\ThreadingModel=Both

ProgIDNamespaceCLSID\ProgID= ProviderNamespaceObjectName

ProgIDNamespaceCLSID\TypeLib=ProviderTypeLibCLSID

ProgIDNamespaceCLSID\Version = ProviderVersionNumber

Under the HKEY_CLASSES_ROOT\CLSID subkey, provider top-level objects must have the following subkeys and values:

ProgIDCLSID = FriendlyDisplayName

ProgIDCLSID\InProcServer32 = ProviderDLLFilename

ProgIDCLSID\InProcServer32\ThreadingModel=Both

ProgIDCLSID\ProgID= ProviderProgIDObjectName

ProgIDCLSID\TypeLib=ProviderTypeLibCLSID

ProgIDCLSID\Version = ProviderVersionNumber

After installing ADSI SDK, the registry contains the following values under HKEY_LOCAL_MACHINE:

SOFTWARE
        Microsoft
            ADs
                Providers
                    LDAP      <No Name>:REG_SZ:LDAPNamespace
                    NDS       <No Name>:REG_SZ:NDSNamespace
                    NWCOMPAT  <No Name>:REG_SZ:NWCOMPATNamespace
                    WinNT     <No Name>:REG_SZ:WinNTNamespace

For a specific example, see Installing the Example Provider Component.


Support for Queries

By implementing the IDirectorySearch interface, ADSI providers gain access to a subset of OLE DB read-only functionality with no extra effort.

The ADSI implementation of the methods of IDirectorySearch itself uses the OLE DB interfaces described in ADSI Version 1.0 included the following list of COM objects:

  • Data Source Object (the directory service), supporting IDBInitialize, IDBCreateSession, IDBProperties, and IPersist.
  • DBSessions Object, supporting IOpenRowSet, ISessionProperties, and ICreateCommand.
  • Command Object, supporting ICommand, IAccessor, IColumnsInfo, ICommandProperties, ICommandText, and IConvertType.
  • Rowset Object, supporting IAccessor, IColumnsInfo, IConvertType, IRowset, and IRowsetInfo.

For more information about OLE DB, see OLE DB Programmer's Reference in the Microsoft Platform SDK.


Implementation Issues for ADSI Providers

In addition to issues listed here, details for implementations can be found in the ADSI Reference under Notes to Implementers and When to Implement.

The recommended way to implement the ADSI interfaces is to first implement the pure COM interface IDirectoryObject. By providing this "minimal-overhead" layer, you supply client applications with control most needed for performance reasons and supply your own implementation with the most flexibility.

Next implement the fundamental ADSI interfaces, IADs, IADsContainer, IADsCollection, and the IADsPropertyValue, IADsPropertyEntry, IADsPropertyList property cache interfaces. IADsGroup and IADsMembers are also interfaces in frequent demand by system administration software.

Implement the schema management interfaces if your directory service has an underlying schema: IADsClass, IADsProperty, IADsSyntax. If there is no underlying schema, you can use these interfaces to abstract the classes and properties used by the directory service as if there were. Schemas are a great means of publishing the features of your directory service to ADSI clients.

Next implement the meta-interfaces so that your directory service features are accessible to ADSI clients that use a single user interface.

Collections

ADSI provider components can follow one of three models for caching collections during enumeration. The choice of a caching model determines the behavior of ADSI when an object in a collection is deleted from the underlying directory service "outside" of ADSI.

The caching models are:

  1. Collections are cached in advance. The collection of object instances is retrieved from the underlying directory service in its entirety when IADsCollection::get__NewEnum is called to create a new enumerator object. If the source object for an Active Directory object instance in the retrieved collection is deleted from the underlying directory service the client does not become aware of the deletion until a IADs::GetInfo or IADs::SetInfo attempts to access the collection.
  2. Collections are incrementally cached. The collection is retrieved from the underlying directory service one object at a time when IEnumVARIANT::Next is called. IEnumVARIANT::Reset will return to the beginning of the collection in the cache and IEnumVARIANT::Next will return cached objects until the end of the cache is reached, at which point new objects will be added from the underlying store. Once an Active Directory object instance is in the cache the client will not become aware of its deletion from the underlying directory service until an IADs::GetInfo or IADs::SetInfo attempts to access the object.
  3. Collections are not cached. The collection is retrieved from the underlying directory service one object at a time when IEnumVARIANT::Next is called. IEnumVARIANT::Reset will return to the beginning of the collection in the underlying store. IEnumVARIANT::Next and IEnumVARIANT::Reset operations cannot retrieve deleted objects, since the objects are fetched on demand from the underlying directory service. Only the "current" object is cached; if the current object is deleted, the client will not become aware of its deletion from the underlying directory service until a IADs::GetInfo or IADs::SetInfo attempts to access the object.

Regardless of the caching model, it is important to note that ADSI enumeration returns Active Directory service interfaces to the caller. To avoid the overhead of obtaining a new interface pointer, ADSI applications should cache the returned interface pointers for object(s) they intend to manipulate. For example, a Visual Basic program that enumerates a container and populates a listbox with names can cache the interface pointers associated with the names for later use. This approach will provide greater performance than populating the listbox during enumeration and obtaining a new interface pointer when the user makes a selection.

About Dispatch IDs

IDispatch is an Automation interface defined by COM for controllers that do not use COM interfaces directly. Accessing an object through IDispatch is called name-bound or late-bound access, since it occurs at run time ("late") and uses string names of properties and methods to resolve references ("name"). At run time, clients pass the string name of the property or method they wish to call into the IDispatch::GetIDsOfNames() method. If the property or method exists on the object, the dispatch identifier (dispID) of the corresponding function is retrieved. The dispID is then used to execute the function through IDispatch::Invoke(). Using IDispatch, properties and methods on the interfaces exposed by a single object appear as a flat list. Because name-bound access requires two function calls, it is less efficient than using a COM interface directly. Clients are encouraged to use the ADSI COM interfaces on the objects when performance is a consideration. Advanced Automation controllers such as Visual Basic 4.0 and Java can call other COM interfaces as well as IDispatch, if the interfaces comply with the Automation constraints for data types and parameter passing.

ADSI providers generate dispIDs dynamically for each Active Directory object. The dispIDs retrieved through IDispatch::GetIDsOfNames for a given object are the generated values, but not the values that are in the IDL for the object. IDispatch users must call GetIDsOfNames to obtain valid dispIDs at run time.

Type Information and Type Libraries

The ADSI SDK supplies a type library, ActiveDs.tlb, that documents all the standard interfaces supported by ADSI. A provider must supply a similar type library for all interfaces found in ActiveDs.TLB, plus any additional type information for the interfaces that are implemented within the provider component. Additional information about type libraries can be found in Generating a Type Library With MIDL under Tools Guide in the Microsoft Platform SDK.

An example of IDL code:

[ object, uuid(IID_IADsXYZ), oleautomation, dual ]
interface IADsXYZ: IDispatch
{
// Read-only properties.
[propget]
HRESULT AReadOnlyProp ([out, retval]BSTR *pbstrAReadOnlyProp);

// Read/write properties.
[propget]
HRESULT AReadWriteProp ([out, retval]long *plAReadWriteProp);
[propput]
HRESULT AReadWriteProp ([in]long lAReadWriteProp);

// Methods.
HRESULT AMethod ([in]DATE dateInParameter,
[out, retval]BSTR *pbstrReturnValue);
};

Thread Safety

Windows NT and Windows 95 support multiple threads in a single process. ADSI providers may therefore be used in multithreaded applications and must allow for this.

The Component Object Model describes the following three different threading models. COM programs indicate which model is in use when initializing the COM library using the CoInitialize and CoInitializeEx functions.

  • Single threading. The single threaded model assumes a single thread of execution in a process, further assuming that COM data structures in a process need no access serialization.
  • Apartment threading. A COM object is associated with the thread that created it. Calls to an object on another thread must be executed by the thread that created that object. To accomplish this, the source thread invokes a client proxy which marshals the method call and delivers it to a server stub function in the destination thread through the Win32 message queue associated with the destination thread.
  • Free threading. COM objects are assumed to be thread safe. Multiple threads are allowed access to any object in the process with no serialization imposed.

ADSI does not assume any particular threading model. Writers of provider components should assume the free threading model and guarantee the consistency of their internal data structures by protecting them from thread-unsafe (that is, uncoordinated) updates through the use of synchronization objects such as critical sections or semaphores.

Object Locking

ADSI does not impose or define an object-locking scheme. Providers for namespaces that support access serialization using locking can expose the underlying locking scheme through provider-specific extensions to ADSI.

Property Names Within a Schema

ADSI represents properties as property objects within the ADSI schema container. This requires that property names be unique within each schema container. It is up to the provider to ensure there are no name collisions.

Primary Interface

When a provider does not know what interface should be returned as the primary interface, IID_IADs should be returned. This provides name-bound access to all properties of an object through IDispatch and the IADs::Get, IADs::GetEx, IADs::Put, and IADs::PutEx methods.


ADSI Example Provider Component

Active Directory Service Interfaces provider writers will find this section of particular interest because it describes the ADSI example provider component in depth. ADSI provider writers can install the example provider and use the code framework as a basis to create their own implementation. The topics discussed are:

Installing the Example Provider Component describes how to install the ADSI "Sample:" provider and its mock directory. This section includes a list of the registry settings.

Directory Definition describes the directory entries defined by the example provider component.

Schema Management describes how each element in the example provider component directory service can be represented by a specific type of Active Directory object.

Binding to an Active Directory Object describes how, given an ADsPath string, the example provider component identifies that element, creates the appropriate type of Active Directory object for it, and retrieves the requested type of interface pointer on that object to pass back to the ADs client software.

Enumerator Objects list the specific types of enumerations supplied by the example provider component and in which source code the implementations can be found.

Code Overview provides a task-level description of each part of the example provider component.

Code Details lists the software modules and their contents.


Installing the Example Provider Component

After installing the ADSI SDK, and starting from the installation directory, move to samples\activeds\sampprov\setup. Run install.bat as described in the README.TXT instructions.

For registry settings, under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ADs\Providers subkey, the ADSI example provider component has the following subkeys and values:

ProgIDNamespace = SampleNamespace

Under the HKEY_CLASSES_ROOT\CLSID subkey, provider namespace objects must have the following subkeys and values:

SampleNamespaceCLSID= Sample Namespace Object

SampleNamespaceCLSID\InProcServer32 = adssmp.dll

SampleNamespaceCLSID\InProcServer32\ThreadingModel=Both

SampleNamespaceCLSID\ProgID= Sample

SampleNamespaceCLSID\TypeLib=ProviderTypeLibCLSID

SampleNamespaceCLSID\Version = 0.0

Under the HKEY_CLASSES_ROOT\CLSID subkey, provider top-level objects must have the following subkeys and values:

SampleCLSID = Sample Provider Object

SampleCLSID\InProcServer32 = adssmp.dll

SampleCLSID\InProcServer32\ThreadingModel=Both

SampleCLSID\ProgID= Sample

SampleCLSID\TypeLib=ProviderTypeLibCLSID

SampleCLSID\Version = 0.0

For the specific example of the example provider component dll, the following registry entries are needed:

HKEY_LOCAL_MACHINE
    SOFTWARE
        +CLSID
        Sample
            Clsid          <No Name>:REG_SZ{323991f0-…}
        SampleNAMESPACE
            Clsid          <No Name>:REG_SZ{51d11c90--…}

Other entries in the registry under concerning the example provider component exist because the example provider component happened to implement its directory hierarchy in the registry. This in no way implies other providers would want to or should do the same.


Directory Definition

The example provider component has a relatively simple directory design to clarify the relationship of the components with each other and to show the minimum requirements necessary to be an ADSI provider.

The "directory" for the example provider component consists of two root nodes: "Seattle" and "Toronto". Seattle contains two more sublevels, "Bellevue" and "Redmond". Each of those entries contains several user accounts. The "Toronto" entry has no further sublevels, but directly contains several user accounts. The following figure shows these two root nodes connected with a network.

ADSI Example Provider Component Directory

In hierarchical terms, the Namespace node contains "Seattle" and "Toronto". "Seattle" contains "Bellevue" and "Redmond". "Bellevue" and "Redmond" each contain a set of user accounts. "Toronto" directly contains the user accounts with no intermediate organizational nodes.

The example provider component represents this structure with only two Active Directory object types: a container object and a leaf object. "Seattle", "Toronto", "Bellevue", and "Redmond" are container objects and each user account is a leaf object.

The example provider component creates a schema class called "Organizational Unit" for a container object type and a schema class called "User" for a user account.

The properties for each schema class, their methods, and the rules that govern the containment relationships for these objects are all defined in Schema Management.


Schema Management

The ADSI example provider component defines the schema classes "Organizational Unit" and "User" and manages these schema classes in the following way.

The "Organizational Unit" schema class is represented by an ADs container object and can contain other "Organizational Units" and "Users". The container object automatically supports the interfaces IUnknown, IDispatch, IADs, and IADsContainer. The "User" schema class is represented by a generic Active Directory object and does not contain any other types of objects. In the example provider component, the User object is implemented as a generic Active Directory object that supports the interfaces IUnknown, IDispatch, and IADs . Note that the User object in this case does not support the IADsUser interface.

The example provider component must also implement the ADs namespace object, which supports the interfaces IUnknown, IADs, IADsContainer, IADsOpenDSObject, and IDispatch.

The details of the schema representing the two example provider component schema classes are shown in the following figure.

ADSI Example Provider Component Schema

Note that in the preceding figure the "Organizational Unit" schema class defines three properties: "Description," "Headcounts," and "ID." The "User" schema class defines four properties: "ID," "Name," "PhoneNumber," and "Title." The "ID" property is shared by both schema classes. Each property is defined by either the "String" or the "Integer" syntax object.

Note Syntax objects are not present in the first release of the example provider component. However, in most Microsoft ADSI schema implementations, the syntax objects are included in the schema container object, just as the schema class and property objects are. For this reason, they are shown here.

This provider component makes the schema information accessible to the ADSI client application in the form of ADs class objects, ADs property objects, and ADs syntax objects all within a schema class container object, so that schema information can be retrieved at run-time.

The ADsPaths for the schema class container objects defined for the example provider component are "Sample://Seattle/schema" and "Sample://Toronto/schema.". In this example, the contents of the schemas are identical.


Binding to an Active Directory Object

The most common way binding to an Active Directory object, by using the GetObject function, happens between an ADSI client and an ADSI provider and is also the easiest way to show how the provider component receives requests and services them. Both the ADSI API function ADsGetObject or the Visual Basic GetObject follow the same steps.

For this example, assume the ADSI client is an ADSI viewer application that has received the ADsPath "Sample://Seattle/Redmond/AnneA" from its user interface (1). The following figure details the sequence of events by numbering the flow arrows.

ADSI Components: Detailed View

In the preceding figure, the client initiates the request for an interface pointer on the Active Directory object represented by the ADsPath "Sample://Seattle/Redmond/AnneA" from the ADSI services (2). The services software, during its initialization, populated a table of installed provider programmatic identifiers (ProgIDs) from the registry ("LDAP:","Sample:", "WinNT:","NDS:", etc.) and paired them with the matching CLSIDs, which identify the appropriate software module.

The ADSI server makes sure the ProgID, in this case "Sample:", exists in the ADsPath. It then creates a bind context to optimize further references to this object, and calls the standard COM function MkParseDisplayName to create a COM moniker that can be used to find and bind to the object representing user "AnneA".

(In the following discussion, the file names of the example provider component source code are included in parentheses where appropriate.)

As in other COM server implementations, MkParseDisplayName examines the ProgID, and looks up the proper CLSID in the registry (3) to find the corresponding provider-supplied class factory code (cprovcf.cpp) in the appropriate provider implementation (4). This code creates an initial object that implements the IParseDisplayName::ParseDisplayName method (cprov.cpp). The provider's implementation of ParseDisplayName resolves the path name in the provider's own namespace. This eventually calls ADsObject and invokes the parser supplied with the provider component (parse.cpp) to check that the ADsPath is syntactically correct for this namespace.

GetObject then determines if the object being requested is a top-level object, a schema object, or some other type of object. If either of the first two, that type of schema class object is created and the appropriate interface pointer retrieved. Otherwise the Sample directory path is created from the ADsPath (for example, "\Seattle\Redmond\AnneA", but in a different directory service it might have had to be "\OU=Seattle\OU=Redmond\CN=AnneA") and control passes to SampleDSOpenObject which opens the object in the example data storage and also retrieves its object type (in this case, "User") (5).

With the information gathered so far, a new object is created (6) to represent the item described by the ADsPath, and a pointer to the IUnknown interface on that object is retrieved. In this case, a generic Active Directory object is created that supports the IUnknown and IADs methods (cgenobj.cpp, core.cpp). The CSampleDSGenObject::AllocateGenObject routine reads the type library information to create the proper dispatch entries for these new objects in order to support IDispatch.

Wrapping this interface pointer into a moniker completes the ResolvePathName (cprov.cpp) function and parsing the display name is done.

All the COM objects created during this process are cached for performance reasons and managed through the binding context. This improves performance for other operations on the same object that immediately follows the moniker binding.

This well-formed Active Directory object is now queried for the interface identifier requested for the initial ADsGetObject call and a pointer to that interface is retrieved (7) and passed back through the ADSI server to the client (8). From then on, the client works directly with the provider component through the interface methods until the initial request is satisfied (9).

Further requests for information about this object from the client usually take the form of requests for property gets and puts, all of which are optimized through the provider's implementation of a property cache (cprops.cpp). Intelligently packing and unpacking data (often including copying and freeing structures and strings) between the native data types on the example provider component's operating system and the Automation VARIANT type supported by ADSI takes place before the properties are loaded into the cache (smpoper.cpp).

The example provider component is designed so that the actual calls to the operating system are logically isolated from the rest of the provider component, creating software that's easily portable to more than one operating system (RegDSAPI.cpp).


Enumerator Objects

The example provider component code supplies the implementation of creating enumerator objects for the ADs namespace object (cenumns.cpp), generic ADSI container objects (cenumobj.cpp), ADSI schema container objects (cenumsch.cpp).


Code Overview

The following figure is a conceptual representation of the blocks of code necessary to implement the ADSI example provider component. Each section is described below. Knowledgeable COM programmers may find this is all they need for an overview of the example provider component. For more details, each code file is detailed in Code Details.

ADSI Example Provider Component Source Code Description

  1. Loading the DLL (libmain.cpp, guid.cpp). The entry point for the DLL. Class factory static object definitions for the two provider objects: Guid.cpp contains the CLSID definitions for the implementations of the various Example provider component objects.
  2. Provider object class factory and creation code (cprovcf.cpp, cprov.cpp, stdfact.cpp). The provider object is the object that supports IParseDisplayName during the moniker binding operations as discussed in Finding and Binding in the Example Provider Component.
  3. Binding to an object (getobj.cpp). This code calls the parser to check that the given ADsPath is syntactically correct, and then performs any necessary mapping from the ADsPath to the native directory service path for the item being created as an Active Directory object. It looks up the schema definition for this type of object and fills in the mandatory properties. After creating the Active Directory object, an interface pointer to IUnknown is retrieved for the caller.
  4. Parser for the provider's namespace (parse.cpp). This is the code invoked by the step above. The parser simply checks that the ADsPath string passed in is syntactically correct for its own namespace.
  5. Class factory, creation, and enumeration for the namespace object (cnamcf.cpp, cnamesp.cpp, cenumns.cpp). The namespace object is a container object that can be enumerated to find all the root node objects for this namespace.
  6. Class factory and creation code for a generic Active Directory object, and class factory, creation and enumeration code for a generic ADs container object (cgenobj.cpp, cenumobj.cpp, common.cpp, core.cpp). This code is executed whenever an Active Directory object is created.
  7. Filtering and enumerating VARIANTs (cenumvar.cpp, object.cpp). When a collection of VARIANT elements of a single type are managed in within ADSI, this code is used.
  8. Globals (globals.cpp). Namespace keywords, syntax mapping structures from native data formats to the ADs Automation VARIANT type are all defined here.
  9. Marshaling/unmarshaling data (pack.cpp, property.cpp, smpoper.cpp). Conversion from native data formats to the supported set of Automation VARIANT types occurs when properties of an object are loaded into the property cache. Other special handling for data must be performed when structures with pointers are copied, deleted, or moved in memory.
  10. Property cache (cprops.cpp). Caching properties is a feature of the ADSI environment. The IADs::GetInfo, IADs::GetInfoEx, and IADs::SetInfo methods act on the property cache.
  11. Memory management (memory.cpp). Using one set of memory functions to allocate and free memory allows the example provider component to track memory use and ensure there are no memory leaks.
  12. Schema objects and management (cschobj.cpp, cprpobj.cpp, cclsobj.cpp, cenumsch.cpp). This includes routines to create, manage, and enumerate the schema objects. This includes schema class objects, property objects, and syntax objects, in addition to being able to enumerate the schema class container object.
  13. Operating-system specific calls (RegDSAPI.cpp). This includes all calls that reference the native operating system. Among other functions, they include functions opening, closing, reading, and modifying objects as well as those accessing the schema and property data. The example provider component happened to simulate a directory hierarchy by using the registry. Only function names should be of much interest to a provider writer.
  14. IDispatch implementation (cdispmgr.cpp). This code accesses the type library information to allow interface methods to be invoked in an Automation-compatible way.


Code Details

This section lists the source code for the ADSI example provider component implementation. All source code references in this document are subject to change and are available in the example code directory included in the ADSI SDK.

Note The IADs methods GetEx and PutEx are not implemented in the ADSI example provider component. This means that the code that implements Active Directory objects that inherit from IADs do not have GetEx and PutEx methods. This includes the schema class object that supports IADsClass, the property object that supports IADsProperty, the generic Active Directory object that supports IADs, and any container object that supports IADsContainer. In addition, syntax objects are not present in the example provider component. However, the ADSI architecture requires the syntax objects to be included in the schema container object, just as the schema class and property objects are.

The following source code files included in the provider example directory on the Active Directory Service Interfaces SDK.

cclsobj.cpp | Schema class object routines.
cdispmgr.cpp | Dispatch Manager implementation.
cenumns.cpp | Namespace enumeration routines.
cenumsch.cpp | Schema enumeration routines.
cenumobj.cpp | Generic object enumeration routines.
cenumvar.cpp | Base implementation for xxxEnumVariant derived classes.
cgenobj.cpp | Generic object routines.
cnamcf.cpp | Namespace class factory routines.
cnamesp.cpp | Namespace object routines.
common.cpp | Code common to all provider objects.
core.cpp | Implementations for 'core' properties shared by all Active Directory objects.
cprops.cpp | Property cache functionality.
cprov.cpp | Top-level provider object routines.
cprovcf.cpp | Top-level provider object class factory routines.
cprpobj.cpp | Property object routines.
cschobj.cpp | Schema object routines.
getobj.cpp | GetObject functionality.
globals.cpp | ADSI example provider component globals.
guid.cpp | Example provider component CLSIDs and LIBIDs.
libmain.cpp | Libmain for adssmp.dll.
memory.cpp | Example provider component memory management routines.
pack.cpp | Example provider component pack/unpack data in VARIANTs.
parse.cpp | Path name parsing for example provider component namespace.
property.cpp | Get and Put properties by name.
object.cpp | Example provider component object type list code for filtering.
regdsapi.cpp | Example provider component registry directory service APIs.
smpoper.cpp | Data conversion routines.
stdfact.cpp | Standard IClassFactory implementation.
sampleds.reg | Example directory data store registry information. See Installing the Example Provider Component . .


CCLSOBJ.CPP

In the example provider component, schema class object routines are in cclsobj.cpp.

CSampleDSClass::CSampleDSClass
Standard constructor.
CSampleDSClass::~CSampleDSClass
Standard destructor.
CSampleDSClass::CreateClass
Create an ADs schema class object, looking up the attribute definitions by calling SampleDSGetClassDefinition.
CSampleDSClass::CreateClass
Given the attribute definitions, create a schema class object, setting any known attributes, such as the ones listed in IADsClass::MandatoryAttributes.
CSampleDSClass::AllocateClassObject
Create a schema class object and load its type information.
CSampleDSClass::QueryInterface
Return the requested interface pointer if available.
CSampleDSClass:: standard IADs methods.
CSampleDSClass:: standard IADsClass methods.
CreatePropertyList
Create the appropriate list of properties associated with this schema class by calling CreatePropertyEntry.
CreatePropertyEntry
Create one property object in this schema class.
FreePropertyEntry
Free the entry made in CreatePropertyEntry.
MakeVariantFromPropList
Make an array of VARIANTS from the property list created by CreatePropertyList. Can be used in the implementation of IADsClass::MandatoryProperties and elsewhere.


CDISPMGR.CPP

In the example provider component, an example showing the dispatch manager implementation of the IDispatch interface is in cdispmgr.cpp. See IDispatch in the Microsoft Platform SDK.


CENUMNS.CPP

In the example provider component, the enumeration of a namespace object uses the routines from cenumns.cpp.

CSampleDSNamespaceEnum::Create
Create an object to allow enumeration of an ADS namespace object.
CSampleDSNamespaceEnum::CSampleDSNamespaceEnum
Standard constructor.
CSampleDSNamespaceEnum::~CSampleDSNamespaceEnum
Standard destructor.
CSampleDSNamespaceEnum::Next
Retrieve the specified number of elements from the namespace object indicated.
CSampleDSNamespaceEnum::EnumObjects
Manage retrieving the interface pointers to the objects.
CSampleDSNamespaceEnum::FetchObjects
Fetch the set of IDispatch pointers.
CSampleDSNamespaceEnum::FetchNextObject
Fetch the next object. If found, create a generic Active Directory object and retrieve its IDispatch pointer.


CENUMOBJ.CPP

In the example provider component, the enumeration of a container object uses the routines from cenumobj.cpp.

CSampleDSGenObjectEnum::Create
Create an object to allow enumeration of generic Active Directory objects.
CSampleDSGenObjectEnum::CSampleDSGenObjectEnum
Initialization.
CSampleDSGenObjectEnum::EnumGenericObjects
Manage retrieving the objects.
CSampleDSGenObjectEnum::FetchObjects
Fetch the set of IDispatch pointers that match the filter.
CSampleDSGenObjectEnum::FetchNextObject
Retrieve an object and match against the filter. If it matches, wrap in generic object and return IDispatch pointer.
CSampleDSGenObjectEnum::EnumGenericObjects
Manage retrieving the objects.
CSampleDSGenObjectEnum::Next
Retrieve the specified number of elements from the enumeration object indicated.
CSampleDSGenObjectEnum::IsValidDSFilter
See if object class matches one in the filter list.
CSampleDSGenObjectEnum::BuildDSFilterArray
Manage the filter array.
CSampleDSGenObjectEnum::CreateAndAppendFilterEntry
Add a new object class to the filter and make the filter contiguous.
FreeFilterList
Free the filter.


CENUMSCH.CPP

In the example provider component, the enumeration of a schema object uses the routines from cenumsch.cpp.

CSampleDSSchemaEnum::Create
Create an object to allow enumeration of an ADS schema class object.
CSampleDSSchemaEnum::CSampleDSSchemaEnum
Standard constructor.
CSampleDSSchemaEnum::~CSampleDSSchemaEnum
Standard destructor.
CSampleDSSchemaEnum::Next
Retrieve the specified number of elements from the schema object indicated.
CSampleDSSchemaEnum::EnumObjects
Manage retrieving the interfaces pointers to the objects of the object type indicated.
CSampleDSSchemaEnum::EnumObjects
Manage retrieving the interface pointers to the objects of the default object type.
CSampleDSSchemaEnum::EnumClasses
Manage retrieving the interface pointers to only the schema class objects that are contained in this object.
CSampleDSSchemaEnum::GetClassObject
Retrieve the next schema class definition; if found, create a schema class object, and return the interface pointer to it.
CSampleDSSchemaEnum::EnumProperties
Manage retrieving the interface pointers to the property objects only that are contained in this object.
CSampleDSSchemaEnum::GetPropertyObject
Retrieve the next property definition; if found, create a schema class object, and return the interface pointer to it.
CSampleDSSchemaEnum::EnumSyntaxes
Manage retrieving the interface pointers to the syntax objects only that are contained in this object.
CSampleDSSchemaEnum::GetSyntaxObject
Retrieve the next syntax definition; if found, create a schema class object, and return the interface pointer to it.


CENUMVAR.CPP

In the example provider component, the base implementation for xxxEnumVariant derived classes can be found in cenumvar.cpp.

CSampleDSEnumVariant::CSampleDSEnumVariant
Standard constructor.
CSampleDSEnumVariant::~CSampleDSEnumVariant
Standard destructor.
CSampleDSEnumVariant::QueryInterface
Standard IUnknown::QueryInterface implementation.
CSampleDSEnumVariant::AddRef
Standard IUnknown::AddRef implementation.
CSampleDSEnumVariant::Release
Standard IUnknown::Release implementation.
CSampleDSEnumVariant::Skip
Standard IEnumXXXX::Skip implementation.
CSampleDSEnumVariant::Reset
Standard IEnumXXXX::Reset implementation.
CSampleDSEnumVariant::Clone
Standard IEnumXXXX::Clone implementation.


CGENOBJ.CPP

In the example provider component, generic Active Directory object routines are in cgenobj.cpp.

CSampleDSGenObject::CSampleDSGenObject
Standard constructor.
CSampleDSGenObject::~CSampleDSGenObject
Standard destructor.
CSampleDSGenObject::CreateGenericObject
Create an ADS generic object, initializing it as appropriate.
CSampleDSGenObject::SampleDSCreateObject
Create this object in its parent container.
CSampleDSGenObject::SampleDSSetObject
Save the properties of this object (flush the cache).
CSampleDSGenObject::AllocateGenObject
Create a generic object and load its type information.
CSampleDSGenObject::QueryInterface
Return the requested interface pointer if available.
CSampleDSGenObject:: Standard IADs methods, including implementations for:
Get (including mapping from native data type to VARIANT type)

Put (including mapping from VARIANT type to native data type)

GetInfo (refreshing the property cache)

SetInfo (saving the property cache)

CSampleDSGenObject:: Standard IADsContainer methods, including implementations for:
GetObject

get__NewEnum

get_Filter

Create

Delete

ConvertSafeArrayToVariantArray
Utility routine.


CORE.CPP

In the example provider component, the code for initializing a generic object's core properties is in core.cpp.

CCoreADsObject::InitializeCoreObject
Initialize the basic IADs properties for this object, a convenience for object creation.
CCoreADsObject::CCoreADsObject
Standard creator.
CCoreADsObject::~CCoreADsObject
Standard destructor.


CNAMCF.CPP

In the example provider component, an example of the ADs namespace object class factory code is in cnamcf.cpp.

CSampleDSNamespaceCF::CreateInstance
Creates an instance of the class factory for the ADs namespace object.


CNAMESP.CPP

In the example provider component, code managing. the lifetime of the example provider component namespace object is in cnamesp.cpp.

CSampleDSNamespace::CSampleDSNamespace
Standard constructor.
CSampleDSNamespace::~CSampleDSNamespace
Standard destructor.
CSampleDSNamespace:: Standard IADs methods.
CSampleDSNamespace:: Standard IADsContainer methods.
CSampleDSNamespace::AllocateNamespaceObject
Create a namespace object and load its type information.
CSampleDSNamespace::CreateNamespace
Allocate, initialize, and validate a namespace object.
CSampleDSNamespace::QueryInterface
Check for the given IID on this object.


COMMON.CPP

In the example provider component, an example of code common to all generic objects is found in common.cpp. Objects inherit these methods and properties through C++ inheritance rules. These routines include building ADsPath strings, type information routines, and other house-keeping routines.


CPRPOBJ.CPP

In the example provider component, property object routines are in cprpobj.cpp.

CSampleDSProperty::CSampleDSProperty
Standard constructor.
CSampleDSProperty::~CSampleDSProperty
Standard destructor.
CSampleDSProperty::CreateProperty
Create an ADS Property object, looking up the attribute definitions by calling SampleDSGetPropertyDefinition.
CSampleDSProperty::CreateProperty
Given the attribute definition, create a property object, setting the correspondence between supported ADS syntaxes and the provider syntaxes.
CSampleDSProperty::AllocatePropertyObject
Create a property object and load its type information.
CSampleDSProperty:: QueryInterface
Return the requested interface pointer if available.
CSampleDSProperty:: Standard IADs methods.
CSampleDSProperty:: Standard IADsProperty methods.
MapSyntaxIdtoADsSyntax
Set the correspondence between the syntax id and the ADS syntax.
MapSyntaxIdtoSampleDSSyntax
Set the correspondence between the syntax id and the provider syntax.


CPROPS.CPP

In the example provider component, an example of a property cache implementation can be found in cprops.cpp.

CPropertyCache::addproperty
Extend the property cache by adding a new one.
CPropertyCache::updateproperty
Look up the property, free its contents, and use new values instead; then mark the cache changed for this property.
CPropertyCache::findproperty
Look up this property by name; save its index.
CPropertyCache::getproperty
Find the property in the cache if available, otherwise call GetInfo. Set the index and copy these new values in.
CPropertyCache::putproperty
Find the property. Free what was there, and put new values in their place.
CPropertyCache::CPropertyCache
Standard constructor.
CPropertyCache::~CPropertyCache
Standard destructor.
CPropertyCache::createpropertycache
Create the cache.
CPropertyCache::unboundgetproperty
Find the property in the cache and set it to these values.
CPropertyCache::SampleDSMarshallProperties
Marshal property information and values.
CPropertyCache::marshallproperty
Marshal a property.
CPropertyCache::SampleDSUnMarshallProperties
Unmarshal property information and values.
CPropertyCache::unmarshallproperty
Unmarshal a property.


CPROV.CPP

In the example provider component, one way to implement the ADs provider object is found in cprov.cpp.

CSampleDSProvider::CSampleDSProvider
Standard creator.
CSampleDSProvider::~CSampleDSProvider
Standard destructor.
CSampleDSProvider::Create
Create the object.
CSampleDSProvider::QueryInterface
Check for supported interfaces.
CSampleDSProvider::ParseDisplayName
Resolve the path name.
CSampleDSProvider::ResolvePathName
Get the object and create a pointer moniker for it.


CPROVCF.CPP

In the example provider component, one example of the ADs provider object class factory code is in cprovcf.cpp. The provider component never directly creates an instance of this object at any time other than when the object is created automatically during the binding operations in ADsGetObject or the internal function in the Visual Basic method GetObject.

CSampleDSProviderCF::CreateInstance
Creates an instance of the class factory for the ADs provider object.


CSCHOBJ.CPP

In the example provider component, code managing the lifetime of the schema objects is in cschobj.cpp.

CSampleDSSchema::CreateSchema
Standard constructor.
CSampleDSSchema::~CSampleDSSchema
Standard destructor.
CSampleDSSchema:: Standard IADs methods.
CSampleDSSchema:: Standard IADsContainer methods.
CSampleDSSchema::QueryInterface
Check for the given IID on this object.
CSampleDSSchema::AllocateSchema
Create a schema object and load its type information.


GETOBJ.CPP

In the example provider component, the code that finds and binds to objects is in getobj.cpp.

RelativeGetObject
Gets an object relative to a given ADsPath.
GetObject
Calls ADsObject (parse.cpp) to check the path syntax, validates that the path name has the right provider token and validate the object type. If there are no errors, Create an instance of the correct type of object, and retrieve a pointer to the object's the IUnknown interface.
BuildADsPathFromDSPath
Built an ADsPath string from the native directory path.
BuildDSTreeNameFromADsPath
Use the ADsPath to create a possible tree directory path for the native directory path.
BuildDSPathFromADsPath
Uses ADsPath and DSPathName.
BuildADsParentPath
Build the ADsPath to the parent for this object.
GetNamespaceObject
Validate and CoCreateInstance a example namespace object.
ValidateNamespaceObject
Make sure the namespace object matches the current provider name.
ValidateProvider
Validate provider name (case sensitive)
GetSchemaObject
Validate and open the appropriate schema object type. Then create the right one, and retrieve the IUnknown interface pointer on it.
ValidateSchemaObject
Check that it is a valid schema object type.
ValidateObjectType
Make sure the object type exists in the schema.
BuildSampleDSRootRDNFromADsPath
Build the ADsPath to the root node for the example provider component.
BuildDSPathFromADsPath
Uses ADsPath, DSRootRDN, and DSPathName.


GLOBALS.CPP

In the example provider component, the globals used can be found in globals.cpp.

g_szProviderName
"Sample"
KeywordList
"user", "group", "organizational unit"
Syntax mappings from Sample DS to ADS Variant
Maps between the "String" syntax and the VARIANT VT_BSTR, and "Integer" and VT_I4. This represents the native data format mapping to the Automation-supported formats and vice versa.


GUID.CPP

In the example provider component, example code for. the guids needed for the example provider component objects is in guid.cpp. Guids are defined for the following items:

CLSID_SampleDSNamespace

CLSID_SampleDSProvider

LIBID_SampleDSOle

CLSID_SampleDSGenObject

CLSID_SampleDSSchema

CLSID_SampleDSClass

CLSID_SampleDSProperty


LIBMAIN.CPP

In the example provider component, an example of the standard DLL entry point for adssmp.dll is in libmain.cpp.

DllGetClassObject
Standard DLL entry point for locating class factories.
DllCanUnloadNow
Standard DLL entry point to determine if DLL can be unloaded.
LibMain
Standard DLL initialization entry point.
IsCompatibleOleVersion
Check compatibility with OLE run time.
DllMain
Entry point for most NT versions.


MEMORY.CPP

In the example provider component, an example showing memory allocation and freeing is in memory.cpp. \

AllocProvMem
Allocates specified memory.
FreeProvMem
Frees memory indicated.
ReallocProvMem
Allocates contiguous memory.
AllocProvStr
Allocates an LPWSTR string.
FreeProvStr
Frees string if not already freed.
ReallocProvStr
Allocates contiguous memory.
ProvAllocString
Checks string and first parameter. If OK, then does allocation.


OBJECT.CPP

In the example provider component, an example of object lists, including using a filter, is in object.cpp.

ObjectTypeList::ObjectTypeList
Creator: Build a list using the filter.
ObjectTypeList::~ObjectTypeList
Standard destructor.
ObjectTypeList::GetCurrentObject
Retrieve the current object from the list.
ObjectTypeList::Next
Bump the index.
ObjectTypeList::Reset
Reset the index to the beginning.
IsValidFilter
Check the integrity of the filter
BuildDefaultObjectArray
Build an array of objects using the filter.
BuildObjectArray
Build an object array.


PROPERTY.CPP

In the example provider component, examples of storing different data types in VARIANT data types so that they can be saved as properties of an object is in property.cpp.

get/put_BSTR_Property
For string properties.
get/put_LONG_Property
For long integer properties.
get/put_DATE_Property
For date format properties.
get/put_VARIANT_BOOL_Property
For boolean properties.
get/put_VARIANT_Property
For variant properties.


PARSE.CPP

In the example provider component, an example of the directory service path name parser is in parse.cpp. The path name parser is a key component in ADs provider components. It checks the syntactic validity of an ADs path name passed in to this provider. If the syntax is valid, an OBJECTINFO structure is constructed, which contains a componentized version of the ADs pathname for this object.

Note that all that is being done is a syntax check. Rather than special-case every nuance new to path names, all path checking must conform to the grammar rules laid out by the parser.

Called from GetObjectW in getobj.cpp.

ADsObject
Parses the ADs pathname passed to it. This function follows the following grammar rules:

<ADsObject> -> <ProviderName> <SampleDSObject>

SampleDSObject
Parses the following grammar rules:

<SampleDSObject> -> "\\" <identifier> "\" <SampleDSObject>

ProviderName
Adds in the syntactically correct provider name if not there.
DsPathName
Parses the following grammar rules:

<Pathname> -> <Component> "\\" <Pathname> OR

<Pathname> -> <Component>

Component
Parses the following grammar rules:

<Identifier> OR

<Identifier> "=" <Identifier>

CLexer::CLexer
Standard constructor.
CLexer::~CLexer
Standard destructor.
CLexer::GetNextToken
Tokenizer.
CLexer::NextChar
Retrieves next single character.
CLexer::PushBackToken
Backs up to beginning of last token.
CLexer::PushbackChar
Backs up one character.
CLexer::IsKeyword
Checks keyword list (defined in globals.h).
CLexer::AddComponent
Adds this component to the component array.
AddProviderName
Adds a syntactically correct provider name into the string to be parsed.
AddRootRDN
Adds the syntactically correct root relative distinguished name (RDN) ]name into the string to be parsed


PACK.CPP

In the example provider component, an example of packing and unpacking data types into VARIANTs is found in pack.cpp. These functions are used when properties are being loaded to and flushed from the property cache and are self-explanatory.

PackStringinVariant/UnpackStringinVariant

PackLONGinVariant/UnpackLONGfromVariant

PackDATEinVariant/UnpackDATEinVariant

PackVARIANT_BOOLinVariant/UnpackVARIANT_BOOLfromVariant

PackVARIANTinVariant/UnpackVARIANTfromVariant


REGDSAPI.CPP

In the example provider component, the routines that represent an API that directly accesses the native operating system are in regdsapi.cpp. The example provider component implements its directory service in the registry. To write a provider that accesses your own directory service, create your own implementations of this API.

SampleDSOpenObject
Open this object by name. If the schema class type parameter is NULL, fill in the type found. Retrieve a handle on the object.
SampleDSCloseObject
Use the handle retrieved by SampleDSOpenObject.
SampleDSRDNEnum
Retrieve the handle on an enumerator object to manage the enumeration of relative distinguished names (RDNs) from a container object.
SampleDSNextRDN
Using the handle retrieved by SampleDSRDNEnum, get the next RDN from this container object.
SampleDSFreeEnum
Free the enumerator object allocated in SampleDSRDNEnum.
SampleDSModifyObject
Modify properties of an object in the directory service given the handle of the object and a list of attributes and their values.
SampleDSReadObject
Read the properties of the object from the directory service. Map the syntax from the native storage to the appropriate ADS syntax values. Handle properties with multiple values accordingly.
SampleDSGetPropertyDefinition
In the schema, look up all property definitions and their attributes for this type of schema class object.
SampleDSGetPropertyDefinition
In the schema, look up this property and its attributes by name.
SampleDSFreePropertyDefinition
Free memory allocated by GetPropertyDefinition.
SampleDSGetTypeText
Get the schema class type of an object in text format.
SampleDSGetType
Get the schema class type of an object.
SampleDSGetPropertyInfo
Given a handle on the schema class object and a property name, retrieve the property information, like syntax, etc.
FreeList
Free the memory used by a LPWSTR_LIST.
SampleDSGetClassDefinition
Retrieve the set of all schema class definitions and their associated information from the schema.
SampleDSGetClassDefinition
Retrieve information about a particular schema class in the schema.
SampleDSGetClassInfo
Given the name of a schema class, look up its associated information, like mandatory properties.
SampleDSAddObject
Add an object in the directory service.
SampleDSRemoveObject
Remove an object from the directory service.
SampleDSCreateBuffer
Create a memory buffer for attribute information and operation data.
SampleDSFreeBuffer
Free the buffer created in SampleDSCreateBuffer.


SMPOPER.CPP

In the example provider component, an example showing data type operation routines is in smpoper.cpp.

MarshallSampleDSSynIdToSampleDS
Marshaling example from native to ADS format, using next routine.
CopySampleDSSynIdToSampleDS
Calls routines indented below, one for each syntax.
CopySampleDSSynId1ToSampleDS1
Copies syntax 1 items (strings).
CopySampleDSSynId2ToSampleDS2
Copies syntax 2 items (integers).
UnMarshallSampleDSTOSampleDSSynId
Allocates and copies one or more objects of the same syntax type and value using the next routine.
CopySampleDSToSampleDSSynID
Calls routines indented below, one for each syntax.
CopySampleDS1ToSampleDSSynID1
Copies syntax 1 items (strings).
CopySampleDS2ToSampleDSSynID2
Copies syntax 2 items (integers).
SampleDSTypeCopyConstruct
Makes more than one appropriate copy of the given object, calling the next routine.
SampleDSTypeCopy
Makes a copy of the appropriate type of object, using the indented routines below, one for each syntax.
SampleDSTypeCopySampleDSSynId1
Copies a SampleDS_Type_1 object, which is the "string" syntax.
SampleDSTypeCopySampleDSSynId2
Copies a SampleDS_Type_2 object, which is the "Integer" syntax.
SampleDSTypeToVarTypeCopyConstruct
Converting from native to ADS format, using next routine.
SampleDSTypeToVarTypeCopy
Calls routines below, one for each syntax supported.
SampleDSTypeToVarTypeCopySampleDSSynId1
Copies an example provider component DNString to a VT_BSTR format.
SampleDSTypeToVarTypeCopySampleDSSynId2
Copies an example provider component Integer to a VT_I4 format.
VarTypeToSampleDSTypeCopyConstruct
Copies one or more objects calling the next routine.
VarTypeToSampleDSTypeCopy
Copies source objects to destination objects according to Example provider component syntax types. Calls the routines below, one for each syntax.
VarTypeToSampleDSTypeCopySampleDSSynId1
Copies a VT_BSTR to an example provider component DNString format.
VarTypeToSampleDSTypeCopySampleDSSynId2
Copies a VT_I4 to an example provider component integer format.
SampleDSTypeFreeSampleDSObjects
Free memory for one or more objects calling the next routine.
SampleDSTypeClear
Free memory for an example object, calling indented routines below, one per syntax type.
SampleDSTypeFreeSampleDSSynId1
Free memory used for syntax 1 items (DNstrings).
SampleDSTypeFreeSampleDSSynId2
Free memory used for syntax 2 items (Integers).


STDFACT.CPP

In the example provider component, an example showing the standard IClassFactory implementation is in stdfact.cpp. See IClassFactory in the Platform SDK.


ADSI CONSTANT Definitions

Active Directory Service Interfaces methods use the constant definitions defined in the following section.


ADS_ATTR_* constants

Constants prefixed with ADS_ATTR_* specify the control codes used in the ADS_ATTR_INFO structure.

#define  ADS_ATTR_CLEAR     ( 1 )
#define  ADS_ATTR_UPDATE    ( 2 )
#define  ADS_ATTR_APPEND    ( 3 )
#define  ADS_ATTR_DELETE    ( 4 )


ADS_CHASE_REFERRALS_* constants

Constants prefixed with ADS_CHASE_REFERRALS_* indicate whether or not queries should resolve references in a directory service to files that exist in separate root directories.

#define  ADS_CHASE_REFERRALS_NEVER            ( 0 )
#define  ADS_CHASE_REFERRALS_SUBORDINATE   ( 0x20 )
#define  ADS_CHASE_REFERRALS_EXTERNAL      ( 0x40 )
#define  ADS_CHASE_REFERRALS_ALWAYS
     (ADS_CHASE_REFERRALS_SUBORDINATE | ADS_CHASE_REFERRALS_EXTERNAL )


ADS_SETTYPE_* constants

TBD.

#define  ADS_SETTYPE_FULL       ( 1 )
#define  ADS_SETTYPE_PROVIDER   ( 2 )
#define  ADS_SETTYPE_SERVER     ( 3 )
#define  ADS_SETTYPE_DN         ( 4 )


ADS_PROPERTY_* constants

Constants prefixed with ADS_PROPERTY_* specify operations on a property or attribute in the property cache.

#define  ADS_PROPERTY_CLEAR     ( 1 )
#define  ADS_PROPERTY_UPDATE    ( 2 )
#define  ADS_PROPERTY_APPEND    ( 3 )
#define  ADS_PROPERTY_DELETE        ( 4 )


ADS_DISPLAY_* constants

TBD.

#define  ADS_DISPLAY_FULL        ( 1 )
#define  ADS_DISPLAY_VALUE_ONLY  ( 2 )


ADS_FORMAT_* constants

TBD.

#define  ADS_FORMAT_WINDOWS             ( 1 )
#define  ADS_FORMAT_WINDOWS_NO_SERVER   ( 2 )
#define  ADS_FORMAT_WINDOWS_DN          ( 3 )
#define  ADS_FORMAT_WINDOWS_PARENT      ( 4 )
#define  ADS_FORMAT_X500                ( 5 )
#define  ADS_FORMAT_X500_NO_SERVER      ( 6 )
#define  ADS_FORMAT_X500_DN             ( 7 )
#define  ADS_FORMAT_X500_PARENT         ( 8 )
#define  ADS_FORMAT_SERVER              ( 9 )
#define  ADS_FORMAT_PROVIDER            ( 10 )
#define  ADS_FORMAT_LEAF                ( 11 )


ADS_SCOPE_* constants

Constants prefixed with ADS_SCOPE_* specify the scope of a query and are used by IDirectorySearch.

#define ADS_SCOPE_BASE       0
#define ADS_SCOPE_ONELEVEL   1
#define ADS_SCOPE_SUBTREE    2

Constants

ADS_SCOPE_BASE
Specifies the base level node for the scope of the query.
ADS_SCOPE_ONELEVEL
Specified the query is limited to one level of the object hierarchy.
ADS_SCOPE_SUBTREE
Specifies the query is limited to the specified subtree of the object hierarchy.


ADSI constants for the OLE DB Provider

These constants are used by the OLE DB provider for ADSI and belong to the property set DBPROPSET_ADSISEARCH.

#define ADSIPROP_ASYNCHRONOUS       0
#define ADSIPROP_DEREF_ALIASES      1
#define ADSIPROP_SIZE_LIMIT         2
#define ADSIPROP_TIME_LIMIT         3
#define ADSIPROP_ATTRIBTYPES_ONLY   4
#define ADSIPROP_SEARCH_SCOPE       5
#define ADSIPROP_TIMEOUT            6
#define ADSIPROP_PAGESIZE           7
#define ADSIPROP_PAGED_TIME_LIMIT   8
#define ADSIPROP_CHASE_REFERRALS    9

#define DBPROPFLAGS_ADSISEARCH      0x0000C000

#define ADSI_DIALECT_LDAP           0
#define ADSI_DIALECT_SQL            1


Miscellaneous constants

The following two constants are used by to specify the level of security to use to open objects from a directory service. They are used in IADsOpenDSObject and documented by each system provider. See ADSI System Providers.

#define  ADS_SECURE_AUTHENTICATION    ( 0x1 )
#define  ADS_USE_ENCRYPTION    ( 0x2 )

#define  ADS_READONLY_SERVER   ( 0x4 )


ADSI Enumeration Definitions

Active Directory Service Interfaces methods use the enumeration definitions defined in the following section.


ADS_DEREF_* constants

ADS_DEREFENUM

Values from the ADS_DEREFENUM.

enum {
    ADS_DEREF_NEVER        = 0,
    ADS_DEREF_SEARCHING    = 1,
    ADS_DEREF_FINDING      = 2,
    ADS_DEREF_ALWAYS       = 3
    }    ADS_DEREFENUM;

Elements

ADS_DEREF_NEVER
Never dereference aliases.
ADS_DEREF_SEARCHING
TBD.
ADS_DEREF_FINDING
TBD.
ADS_DEREF_ALWAYS
Always dereference aliases.


ADS_SCOPEENUM

Values from the ADS_SCOPEENUM enumeration specify the search scope.

typedef enum {
    ADS_SCOPE_BASE        = 0,
    ADS_SCOPE_ONELEVEL    = 1,
    ADS_SCOPE_SUBTREE     = 2
    }    ADS_SCOPEENUM;

Elements

ADS_SCOPE_BASE
Limit the search to the base level.
ADS_SCOPE_ONELEVEL
Limit the search to only one level.
ADS_SCOPE_SUBTREE
Limit the search to the given subtree.


ADS_SEARCHPREF

typedef enum {
    ADS_SEARCHPREF_ASYNCHRONOUS = 0,
    ADS_SEARCHPREF_DEREF_ALIASES,
    ADS_SEARCHPREF_SIZE_LIMIT,
    ADS_SEARCHPREF_TIME_LIMIT,
    ADS_SEARCHPREF_ATTRIBTYPES_ONLY,
    ADS_SEARCHPREF_SEARCH_SCOPE,
    ADS_SEARCHPREF_TIMEOUT,
    ADS_SEARCHPREF_PAGESIZE,
    ADS_SEARCHPREF_PAGED_TIME_LIMIT,
    ADS_SEARCHPREF_PAGE_CHASE_REFERRALS,
    ADS_SEARCHPREF_PAGE_SORT_ON
} ADS_SEARCHPREF_ENUM;

typedef ADS_SEARCHPREF_ENUM ADS_SEARCHPREF;

Elements

ADS_SEARCHPREF_ASYNCHRONOUS
Calls to ExecuteSearch are executed asynchronously.
ADS_SEARCHPREF_DEREF_ALIASES
Object aliases (for example, shortcuts) should be resolved when found.
ADS_SEARCHPREF_SIZE_LIMIT
The size limit for the search specified in an ADS_SEARCHPREF_INFO structure should be observed.
ADS_SEARCHPREF_TIME_LIMIT
The time limit for the search specified in an ADS_SEARCHPREF_INFO structure should be observed.
ADS_SEARCHPREF_ATTRIBTYPES_ONLY
The search should obtain only the types of attributes, not their values.
ADS_SEARCHPREF_SEARCH_SCOPE
The search scope specified in an ADS_SEARCHPREF_INFO structure should be observed. The search scope can be restricted to the current level or to the subtree of which the current level is the base.
ADS_SEARCHPREF_TIMEOUT
The timeout period for the search specified in an ADS_SEARCHPREF_INFO structure should be observed.
ADS_SEARCHPREF_PAGESIZE
Specifies the page size of the search results for implementations this feature.
ADS_SEARCHPREF_PAGED_TIME_LIMIT
Specifies the time limit for each page of search results (as opposed to the time limit for the entire search).
ADS_SEARCHPREF_CHASE_REFERRALS
If the root of the search specified is not in the naming context of the server or when the search results cross a naming context (for example, when you have child domains and search in the parent domain), the server sends a referral message to the client which the client can choose to ignore or chase.
ADS_SEARCHPREF_SORT_ON
TBD.


ADS_STATUS

Values from the ADS_STATUS enumeration indicate if a search preference has been set and if not, why not.

typedef enum {
    ADS_STATUS_S_OK     = 0,
    ADS_STATUS_INVALID_SEARCHPREF,
    ADS_STATUS_INVALID_SEARCHPREFVALUE
} ADS_STATUSENUM;
typedef ADS_STATUSENUM ADS_STATUS, *PADS_STATUS;

Elements

ADS_STATUS_S_OK
The search preference was set successfully.
ADS_STATUS_INVALID_SEARCHPREF
The search preference specified in the dwSearchPref member of the ADS_SEARCHPREF_INFO structure is invalid. Search preferences must be taken from the ADS_SEARCHPREF enumeration.
ADS_STATUS_INVALID_SEARCHPREFVALUE
The value specified in the vValue member of the ADS_SEARCHPREF_INFO structure is invalid for the corresponding search preference.

Remarks

The IDirectorySearch::SetSearchPreferences method writes values from the ADS_STATUS enumeration to the dwStatus member of an ADS_SEARCHPREF_INFO structure to indicate whether the corresponding search preference was set. Callers can use this status value to decide whether to execute a search.


ADSTYPE

Specifies the type used to interpret an ADSI extended syntax string.

enum ADSTYPEENUM {
    ADSTYPE_INVALID = 0,
    ADSTYPE_DN_STRING,
    ADSTYPE_CASE_EXACT_STRING,
    ADSTYPE_CASE_IGNORE_STRING,
    ADSTYPE_PRINTABLE_STRING,
    ADSTYPE_NUMERIC_STRING,
    ADSTYPE_BOOLEAN,
    ADSTYPE_INTEGER,
    ADSTYPE_OCTET_STRING,
    ADSTYPE_UTC_TIME,
    ADSTYPE_LARGE_INTEGER,
    ADSTYPE_PROV_SPECIFIC,
    ADSTYPE_OBJECT_CLASS
} ;

typedef ADSTYPEENUM ADSTYPE;

Elements

ADSTYPE_INVALID
An invalid type.
ADSTYPE_DN_STRING
The distinguished name (path) of a directory service object.
ADSTYPE_CASE_EXACT_STRING
A string that must be interpreted case-sensitively.
ADSTYPE_CASE_IGNORE_STRING
A string that must be interpreted case-insensitively.
ADSTYPE_PRINTABLE_STRING
A string that can be displayed onscreen or printed.
ADSTYPE_NUMERIC_STRING
Numerals that are to be interpreted as text.
ADSTYPE_BOOLEAN
A Boolean value.
ADSTYPE_INTEGER
An integer value.
ADSTYPE_OCTET_STRING
A string of eight-bit characters.
ADSTYPE_UTC_TIME
The time expressed in Universal Coordinated Time (UCT).
ADSTYPE_LARGE_INTEGER
A long integer value.
ADSTYPE_PROV_SPECIFIC
A provider-specific string.
ADSTYPE_OBJECT_CLASS
The object class.


ADSI Function List

The following is a list of ADSI helper functions.

ADsGetObject | ADsGetLastError | ADsBuildVarArrayInt
ADsOpenObject | ADsSetLastError | ADsBuildVarArrayStr
ADsBuildEnumerator |  |
ADsEnumerateNext |  |
ADsFreeEnumerator |  |


ADsBuildEnumerator

Builds an enumerator object for the specified Active Directory container object.

HRESULT ADsBuildEnumerator(
  IADsContainer * pADsContainer,  //The object to be enumerated
  IEnumVARIANT **ppEnumVariant  //Enumerator object
);

Parameters

pADsContainer
[in] Pointer to the IADsContainer interface on the object to be enumerated.
ppEnumVariant
[out] Indirect pointer to the IEnumVARIANT interface on the enumerator object created for the specified container object.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The enumerator object has been built successfully.

Remarks

The ADsBuildEnumerator helper function encapsulates the code required to create an enumerator object. It calls the IADsContainer::get__NewEnum method to create an enumerator object and then calls the QueryInterface method of IUnknown to get a pointer to the IEnumVARIANT interface for that object. The enumeration object is the Automation mechanism to enumerate over containers. Use ADsFreeEnumerator to release this enumerator object.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADsEnumerateNext, ADsFreeEnumerator


ADsBuildVarArrayInt

Builds a VARIANT array from an array of DWORDS.

HRESULT ADsBuildVarArrayInt(
  LPDWORD lpdwObjectTypes,  //Array of DWORD values
  DWORD dwObjectTypes,  //Number of entries
  VARIANT *pVar         //Resulting variant array
);

Parameters

lpdwObjectTypes
[in] Array of DWORD values.
dwObjectTypes
[in] Number of DWORD entries in the given array.
pVar
[out] Pointer to the resulting VARIANT array of values.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The array has been built successfully.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADsBuildVarArrayStr


ADsBuildVarArrayStr

Builds a VARIANT array from an array of Unicode strings.

HRESULT ADsBuildVarArrayStr(
  LPWSTR *lppPathNames,  //Array of Unicode strings
  DWORD dwPathNames,     //Number of entries
  VARIANT * pVar         //Resulting variant array
);

Parameters

lppPathNames
[in] Array of Unicode strings.
dwPathNames
[in] Number of Unicode entries in the given array.
pVar
[out] Pointer to the resulting VARIANT array of values.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The array has been built successfully.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADsBuildVarArrayInt


ADsEnumerateNext

Populates a VARIANT arrray with elements fetched from the indicated enumerator object.

HRESULT ADsEnumerateNext(
  IEnumVARIANT *pEnumVariant,  //Enumerator object
  ULONG cElements,             //Number of elements requested
  VARIANT FAR *pvar,           //Array of values fetched
  ULONG FAR *pcElementsFetched  //Number of elements fetched
);

Parameters

pEnumVariant
[in] Pointer to the IEnumVARIANT interface on the enumerator object.
cElements
[in] Number of elements requested.
pvar
[in] Pointer to the array of elements retrieved.
pcElementsFetched
[out] Actual number of elements retrieved, which can be smaller than the number of elements requested.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The VARIANT array has been populated successfully.

Remarks

The ADsEnumerateNext helper function populates a VARIANT array with elements fetched from an enumerator object. The number of elements retrieved can be smaller than the number requested.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADsBuildEnumerator, ADsFreeEnumerator


ADsFreeEnumerator

Frees an enumerator object previously created through ADsBuildEnumerator.

HRESULT ADsFreeEnumerator(
  IEnumVARIANT * pEnumVariant  //Enumerator object
);

Parameters

pEnumVariant
[out] Pointer to the IEnumVARIANT interface on the enumerator object to be freed.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The enumerator object has been freed successfully.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADsBuildEnumerator


ADsGetLastError

Retrieves the calling thread's last-error code value. This function acts in the same manner as the Win32 function GetLastError.

HRESULT ADsGetLastError(
  LPDWORD lpError,      //Indirect pointer to error code
  LPWSTR lpErrorBuf,    //Indirect pointer to error string
  DWORD dwErrorBufLen,  //Max length of ErrorBuf
  LPWSTR lpNameBuf,     //Indirect pointer to provider name
  DWORD dwNameBufLen    //Max length of NameBuf
);

Parameters

lpError
[out] Pointer to the location that receives the error code.
lpErrorBuf
[out] Pointer to the location that receives the null-terminated string describing the error.
dwErrorBufLen
[in] Size (in characters) of the lpErrorBuf buffer. If the buffer is too small to receive the error string, the string is truncated, but still null-terminated. A buffer of at least 256 bytes is recommended.
lpNameBuf
[out] Pointer to the location that receives the null-terminated string describing the name of the provider that raised the error.
dwNameBufLen
[in] Size (in characters) of the lpNameBuf buffer. If the buffer is too small to receive the error string, the string is truncated, but still null-terminated.

Return Values

S_OK
The last error was retrieved successfully.
E_POINTER
One or more of the parameters passed in is bad.
ERROR_BAD_DEVICE
The threadID for the current thread could not be found in that table anywhere. This should never happen.

Remarks

The ADsEnumerateNext helper function populates a VARIANT array with elements fetched from an enumerator object. The number of elements retrieved can be smaller than the number requested.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADsBuildEnumerator, ADsFreeEnumerator


ADsGetObject

In Active Directory, bind to an object given its path and primary interface identifier (IID).

HRESULT ADsGetObject(
  LPWSTR lpszPathName,  //The ADsPath name of the object
  REFIID riid,          //IID of primary interface
  VOID ** ppObject      //Interface on that object
);

Parameters

lpszPathName
[in] The path name to use to bind to the object in the underlying directory service.
riid
[in] Interface identifier for the primary interface on this object.
ppObject
[out] Indirect pointer to the riid Interface identifier.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
Binding to the specified object has been successful.

Remarks

The ADsGetObject helper function is called by the C/C++ client to bind to an Active Directory object. Like Visual Basic's internal GetObject() function, ADsGetObject takes as input a display name and returns a pointer to the requested interface.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also


ADsOpenObject

In Active Directory, bind to an object using username and password credentials.

HRESULT ADsOpenObject(
  LPWSTR lpszPathName,  //The ADsPath name of the object
  LPWSTR lpszUserName,  //User name to use for credentials
  LPWSTR lpszPassword,  //Password to use for credentials
  DWORD dwReserved,     //Provider-specific flags
  REFIID riid,          //IID of primary interface
  VOID FAR * FAR *ppObject  //Interface on that object
);

Parameters

lpszPathName
[in] The path name to use to bind to the object in the underlying directory using the lpszUserName and lpszPassword credentials.
lpszUserName
[in] The user name to supply to the directory service to use for credentials.
lpszPassword
[in] The password to supply to the directory service to use for credentials.
dwReserved
[in] Provider-specific flags. See IADsOpenDSObject.
riid
[in] Interface identifier for the primary interface on this object.
ppObject
[out] Indirect pointer to the riid Interface identifier.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
Binding to the specified object has been successful.

Remarks

The ADsOpenObject helper function is called by the C/C++ client to bind to an Active Directory object using the username and password as credentials for the appropriate directory service. This function is the code equivalent of calling the IADsOpenDSObject::OpenDsObject method.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADSI Namespace Object, IADsOpenDSObject


ADsSetLastError

Sets the calling thread's last-error code value. This function can be used by Active Directory providers to set extended errors. It saves away the error infomation in a "per thread" data structure. This function acts in the same manner as the Win32 function SetLastError.

VOID ADsSetLastError(
  DWORD dwErr,      //Error code
  LPWSTR pszError,  //Pointer to error string
  LPWSTR            //Pointer to provider name
);

Parameters

dwErr
[in] The error code that occurred. If this is a Windows-defined error, pszError is ignored. If this is ERROR_EXTENDED_ERROR, it indicates the provider has a network-specific error to report.
pszError
[in] String describing the network-specific error.
pszProviderName
[in] String naming the Active Directory provider raising the error.

Return Values

None.

Remarks

The ADsEnumerateNext helper function populates a VARIANT array with elements fetched from an enumerator object. The number of elements retrieved can be smaller than the number requested.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.

See Also

ADsBuildEnumerator, ADsFreeEnumerator


ADSI Interface Definitions

The following ADSI interfaces are grouped by function.

  • Standard ADSI interfaces that provide the basic Active Directory object management functions. See Interfaces for Active Directory Object Management.
  • ADSI interfaces that use persistent information from a directory service. See Interfaces for Active Directory Objects Represented in the Underlying Directory Service.
  • ADSI interfaces that use dynamic information from a directory service. See Interfaces for Active Directory Objects Not Represented in the Underlying Directory Service.
  • ADSI interfaces that allow an ADSI client to establish its credentials to a server for a namespace and use security features supported by the directory service. See Security Interfaces.
  • ADSI interfaces that allow non-Automation clients low-overhead access to directory objects. See Non-Automation Interfaces.


Interfaces for Active Directory Object Management

The following interfaces support the methods and properties that manage the basic Active Directory object.


Interfaces for Active Directory Objects Represented in the Underlying Directory Service

The following interfaces provide access to data in a namespace that is persistent. This information includes user accounts, file directories, file shares, organizational hierarchies, and even such lists as print jobs waiting in a print queue.

IADsUser | IADsService | IADsLocality
IADsMembers | IADsFileService | IADsO
IADsGroup | IADsFileShare | IADsOU
IADsCollection | IADsPrintQueue |
IADsComputer | IADsPrintJob |
IADsDomain |  |


Interfaces for Active Directory Objects Not Represented in the Underlying Directory Service

The following interfaces provide methods that do not access a directory service's persistent data, but provide methods for namespaces that can work with volatile information, such as issuing commands to control processes over a network.

IADsComputerOperations | IADsServiceOperations
IADsPrintQueueOperations | IADsFileServiceOperations
IADsPrintJobOperations | IADsResource
 | IADsSession


Security Interfaces

The following interfaces allows an ADSI client applications to supply credentials to the underlying directory service and to use ACLs and security descriptors.

IADsOpenDSObject | IADsSecurityDescriptor | IADsAccessControlEntry
IADsAccessControlList |  |


Non-Automation Interfaces

The remaining Active Directory Service Interfaces provide C/C++ programmers with vtable access to methods governing managing and searching for directory service objects.


Interface Property Methods

All ADSI interfaces that are not pure COM interfaces are implemented as dual interfaces, meaning that they support client access through both vtable methods and IDispatch methods. Early-bound clients written in languages such as C and C++ can call interface methods directly. Late-bound clients written in languages such as Java, Visual Basic and VBScript can access an interface's properties by calling dispinterface methods that get and set the values of those properties.

Each get_<property> method takes a single out parameter. This parameter is a method-allocated address of a variable of the property's data type. On return, this variable contains the current value of the requested property. The caller is responsible for releasing the allocated memory for the variable when the property is no longer needed.

Each put_<property> method takes a single in parameter of the corresponding property's data type, which contains the new property value.

All parameters and return types must be within the subset of those defined by the VARIANT data type. All methods on a dual interface return an HRESULT value to indicate success or failure.

For more information about getting and setting properties on ADSI objects, see Property Cache.


IADs

The IADs interface provides methods for getting and setting information about ADSI objects. COM objects supporting this interface form the building blocks of a directory service implementation. Active Directory objects may represent all elements in a directory service, including users, computers, services, how user accounts and computers are organized, and the hierarchical directory trees of all the file systems on the network.

Properties accessed by IADs are defined on the ADSI Object. The basic functionality supplied by this interface includes providing:

  • Identifiers for both name and type of object.
  • Binding information that uniquely identifies the object instance in a directory tree.
  • Methods to retrieve an interface pointer on the parent container object, which controls the creation and deletion of every Active Directory object.
  • Methods to retrieve the schema definition of the object, that is the well-defined relationship of this object to others in the directory service.
  • Methods to set and retrieve individual property values by name.
  • A simple caching system for the properties of an object.

ADSI Objects can contain other objects. Container objects support the additional IADsContainer interface.

The flexibility and uniformity provided by using Active Directory objects to represent all aspects of a directory service allows both network administrators and Active Directory providers a simple, consistent view of various underlying directory services.

When to Implement

Implement IADs only when you are providing an Active Directory implementation for your directory service.

If you are adding functionality or properties to existing Active Directory objects, you must define and implement a custom COM interface to do so.

When to Use

All ADSI client applications or tools call these methods to communicate with directory service objects. For example, code written to expand a directory tree upward uses the get_Parent (Visual Basic, .Parent) method to determine if this object is contained by another level in the directory hierarchy. If you have an interface pointer to an instance of this object through an enumeration, you can retrieve its ADsPath name using Visual Basic (Visual Basic, .Name). If you are browsing through the directory service to see what methods and properties are supported, call get_Schema (Visual Basic, .Schema) to get the ADsPath name of the object that represents this schema class of object in the schema definition. Use the Get method with the property names retrieved from the schema object to get the values of all the properties currently defined on the object.

If you need to identify the ADSI User objects for every implementation, retrieve one user object by enumerating the schema object for the class name User, retrieve the GUID for the Active Directory object type User with get_GUID (Visual Basic, .GUID), set the enumeration filter for that GUID, and enumerate through all the providers' ADSI Namespace Objects to find the User objects for every implementation.

Consult the documentation for the specific providers in use to determine what ADSI errors are returned for their providers. This includes errors which indicate a request may not have been completely processed.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the property values for this object as they exist in the underlying directory service.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.


IADs Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADs interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Class | R/O | HRESULT get_Class ([out] BSTR *pbstrClass);
GUID | R/O | HRESULT get_GUID ([out] BSTR *pbstrGUID);
Name | R/O | HRESULT get_Name ([out] BSTR *pbstrName);
ADsPath | R/O | HRESULT get_ADsPath ([out] BSTR *pbstrADsPath);
Parent | R/O | HRESULT get_Parent ([out] BSTR *pbstrParent);
Schema | R/O | HRESULT get_Schema ([out] BSTR *pbstrSchema);

Property Descriptions

Class
Gets the name of the schema class of this object.
GUID
Gets an optional provider-specific unique identifier for objects of this schema class.

Notes to Implementers You can use this property to uniquely identify the schema class of this object. If you do not provide a GUID, return E_ADS_PROPERTY_NOT_SUPPORTED when this property is read.

Name
Gets the relative name of the object as named within the underlying directory service. This is the leaf name of this object, which distinguishes this object from its siblings.
ADsPath
Gets the ADsPath string of the object that uniquely identifies the object in a networked environment. The object can always be retrieved using this path.
Parent
Gets the ADsPath string of the parent container. There is no implied ability in Active Directory to form the ADsPath of a given object by concatenating the Parent and Name properties. While this operation might work in some providers, it is not guaranteed to work for other implementations. The ADsPath is guaranteed to be valid and should always be used to retrieve an object's interface pointer.
Schema
Gets the ADsPath string of the object that supports the IADsClass interface for this schema class.

See Also

IADsContainer


IADs::Get

Given the name of a property, IADs::Get Gets its single value in VARIANT structure from the property cache. Finding no value in the cache invokes an implicit IADs::GetInfo. Use IADs::GetEx to retrieve multi-valued properties.

HRESULT IADs::Get(
  BSTR bstrName,    //Name of the property
  VARIANT * pvProp  //Pointer to a location to hold the retrieved
                    // value.
);

Parameter

bstrName
[in] Name of the property as defined in the ADSI Schema Class Object for this object, for example "MyProperty".
pvProp
[out] Pointer to a location to receive the value of the property.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The property value was retrieved successfully.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADs::GetEx, IADs::Put, IADs::PutEx, Property Cache


IADs::GetEx

Given the name of a property, IADs::GetEx Gets single or multi-values in VARIANT structures from the property cache. Finding no value in the cache invokes an implicit IADs::GetInfoEx. IADs::Get can also be used to retrieve single valued properties.

HRESULT IADs::GetEx(
  BSTR bstrName,    //Name of the property
  VARIANT * pvProp  //Value(s) of the property
);

Parameter

bstrName
[in] Name of the property as defined in the ADSI Schema Class Object for this object, for example "MyProperty".
pvProp
[out] Pointer to a location to receive the value(s) of the property.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The property value was retrieved successfully.

See Also

IADs::Get, IADs::Put, IADs::PutEx, Property Cache


IADs::GetInfo

Gets all the current values for the properties for this ADSI object from the underlying directory store, refreshing the cached values. Calling this method after changing property values but before calling IADs::SetInfo results in losing those changed values. After this call, the cache reflects the property values in the underlying namespace directory store.

GetInfo is called explicitly to refresh all of the ADSI object's cached properties from the underlying namespace. To refresh specific properties, use GetInfoEx.

An implicit GetInfo is invoked if a Get is performed on a specific property in the property cache an no value is found.

HRESULT IADs::GetInfo(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The current set of property values for this object have been refreshed.

Remarks

GetInfo does not affect the objects stored in a container. A call to this method affects the properties of the container, not its contents.

Notes to Implementers

Both GetInfo and SetInfo may require multiple accesses to the underlying directory to load or store the properties in the Active Directory object. It is technically possible for a GetInfo or SetInfo operation to be only partially successful. You are expected to complete as much of the requested operation as possible before returning. Active Directory provides several standard error codes to indicate that a request was not completely processed. See ADSI Errors.

A caller can obtain a property value from an ADSI object at any time after obtaining a pointer on an interface on the object (e.g., through GetObject or through an ADSI enumeration). The caller need not call GetInfo first. If the property in question has not been previously retrieved, the provider is responsible for retrieving and caching it to satisfy the request.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

ADSI Property Object, IADs::GetInfoEx, Property Cache


IADs::GetInfoEx

Gets specific current values for the properties for this Active Directory object from the underlying directory store, refreshing the cached values. Calling this method after changing property values but before calling IADs::SetInfo results in losing those changed values. After this call, the cache reflects the property values in the underlying namespace directory store.

GetInfoEx is called explicitly to refresh some of an ADSI object's cached properties from the underlying namespace. To refresh all the properties, use GetInfo.

HRESULT IADs::GetInfoEx(
  VARIANT vProperties,  //Property names
  LONG lReserved  //Reserved for future use.
);

Parameter

vHints
[in] Array of BSTR entries that list the properties to load into the Active Directory property cache. Each property name must match one in this object's schema class definition.
lReserved
[in] Word reserved for future use.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The current set of property values for this object have been refreshed.

Remarks

GetInfoEx does not affect the objects stored in a container. A call to this method affects the properties of the container, not its contents.

Notes to Implementers

If vHints is empty and no hints are specified, provide as much smart network access as possible. Both GetInfo, GetInfoEx, and SetInfo may require multiple accesses to the underlying directory to load or store the properties in the Active Directory object. It is technically possible for a GetInfo, GetInfoEx or SetInfo operation to be only partially successful. You are expected to complete as much of the requested operation as possible before returning. Active Directory provides several standard error codes to indicate that a request was not completely processed.

A caller can obtain a property value from an ADSI object at any time after obtaining the object (e.g., through GetObject or through an ADSI enumeration). The caller need not call GetInfo or GetInfoEx first. If the property in question has not been previously retrieved, the provider is responsible for retrieving and caching it to satisfy the request.

QuickInfo

Windows NT: Use version 4.0 Service Pack 2 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

ADSI Property Object, IADs::GetInfo, Property Cache


IADs::Put

Saves the value for a property for an Active Directory object by name into the property cache. Use IADs::PutEx to save multi-valued properties to the property cache or to remove a property from an object. These values are not persisted to the underlying directory service until a IADs::SetInfo is called.

HRESULT IADs::Put(
  BSTR bstrName, //Name of the property
  VARIANT vProp  //Value of the property
);

Parameter

bstrName
[in] Name of the property as defined in the ADSI Schema Class Object for this object, for example "FullName".
vProp
[in] Value of the property.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The property value has been set successfully.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADs::Get, IADs::GetEx, IADs::PutEx, ADSI Property Object, Property Cache


IADs::PutEx

Uses the name of a property to save a single or multi-valued property into the property cache. This overwrites any value currently in the property cache. The values in the cache are not written to the underlying directory service until an IADs::SetInfo occurs.

HRESULT IADs::PutEx(
  LONG lnControlCode,  //Multi-value control code
  BSTR bstrName,       //Name of the property
  VARIANT vProp        //Value of the property
);

Parameter

lnControlCode
[in] Values for the control code indicate controls to be passed on to the underlying directory server. These controls do not operate on the property values in the property cache. For example, the control code setting ADS_PROPERTY_CLEAR means that when an IADs::SetInfo flushes the cache to the underlying DS, an ADSI provider-specific "Clear Property" command is passed on to the DS for the named property. If no SetInfo occurs, the property entry in the cache remains as is and subsequent GetInfo or GetInfoEx calls retrieve the contents of the property cache.

Values for the multi-value control code can be any of the following.

ADS_PROPERTY_CLEAR
Instruct the DS to remove the property from the object
ADS_PROPERTY_UPDATE
Instruct the DS to replaces the current value with the element(s) in the passed VARIANT array.
bstrName
[in] Name of the property as defined in the ADSI Schema Class Object for this object, for example "FullName".
vProp
[in] Value of the property.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The property value has been set successfully.

See Also

IADs::Get, IADs::GetEx, IADs::Put, ADSI Property Object, Property Cache


IADs::SetInfo

Saves the current values for the properties for this Active Directory object from the property cache to the underlying directory store. This is analogous to flushing a buffer out to disk.

HRESULT IADs::SetInfo(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The property values in the cache have been saved to the underlying directory.

Remarks

SetInfo does affects only the objects that are newly created in a container. It does not affect objects that were already stored in a container. Except for newly created objects, a call to this method affects the properties of the container, not its contents.

At the time of the SetInfo call, if any property cache values have been written with a control code such as ADS_PROPERTY_UPDATE or ADS_PROPERTY_CLEAR, it is at this time that the appropriate requests are passed on to the underlying directory service.

Notes to Implementers

Both GetInfo and SetInfo may require multiple accesses to the underlying directory to load or store the properties in the ADSI object. It is technically possible for a GetInfo or SetInfo operation to be only partially successful. You are expected to complete as much of the requested operation as possible before returning. Active Directory provides several standard error codes to indicate that a request was not completely processed. See ADSI Errors.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADs::GetInfo


IADsAccessControlEntry

The IADsAccessControlEntry interface manages the contents of individual access control entries (ACEs) in the access control list (ACL).

When to Implement

Providers using an ACL to manage user access to directory service resources must implement IADsAccessControlEntry for each entry in the ACL.

When to Use

Call IADSAccessControlEntry to get and set properties on an ACE.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods or gets/sets one of its properties.

IADsAccessControlEntry Methods | Description
get/put_AccessMask | Gets/sets the access mask for an ACE.
get/put_AceType | Gets/sets the ACE type.
get/put_AceFlags | Gets/sets ACE flag values.
get/put_Flags | Gets/sets flag values.
get/put_ObjectType | Gets/sets object type.
get/put_InheritedObjectType | Gets/sets inherited object type.
get/put Trustee | Gets/sets trustee.

See Also

IAccessControlList, IADsSecurityDescriptor, Using Credentials and Security


IADsAccessControlEntry Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsAccessControlEntry interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
AccessMask | R/W | HRESULT get_AccessMask ([out] LONG * plnAccessMask); HRESULT put_AccessMask ([in] LONG lnAccessMask);
AceType | ReadW | HRESULT get_AceType ([out] LONG * plAceType); HRESULT put_AceType ([in] LONG lnAceType);
AceFlags | R/W | HRESULT get_AceFlags ([out] LONG * plnAceFlags); HRESULT put_AceFlags ([in] LONG lnAceFlags);
Flags | R/W | HRESULT get_Flags ([out] LONG * lnflags); HRESULT put_Flags ([in] LONG lnflags);
ObjectType | R/W | HRESULT get_ObjectType ([out] BSTR * bstrObjectType); HRESULT put_ObjectType ([in] BSTR bstrObjectType);
InheritedObjectType | R/W | HRESULT get_InheritedObjectType ([out] BSTR * bstrInheritedObjectType); HRESULT put_InheritedObjectType ([in] BSTR bstrInheritedObjectType);
Trustee | R/W | HRESULT get_SecurityIdentifier ([out] BSTR * pbstrSecurityId); HRESULT put_SecurityIdentifier ([in] BSTR bstrSecurityId);

Property Descriptions

AccessMask
Flags defining access permissions granted or denied by this entry.
AceType
Flag indicating the type of ACE.
AceFlags
Flags determining whether other containers or objects can inherit the ACE from the primary object to which the ACL is attached.
Flags
TBD.
ObjectType
TBD.
InheritedObjectType
TBD.
Trustee
TBD.

See Also

IADsAccessControlList


IADsAccessControlList

The IADsAccessControlList interface manages individual access control entries (ACEs) in an access control list (ACL) and copies the entire ACL.

When to Implement

Providers using an ACL to manage user access to directory service resources must implement IADsAccessControlList to create the ACL.

Implementations of ADSI objects and interfaces vary according to individual provider requirements. For information on provider-specific implementations, see ADSI System Providers.

When to Use

Call IADsAccessControlList to manage one or more entries in an ACL.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods or gets/sets one of its properties.

IADsAccessControlList Methods | Description
get/put_AclRevision | Gets/sets the ACL revision number.
get/put_AceCount | Gets/sets number of ACEs in theACL.
AddAce | Adds an entry to the ACL..
RemoveAce | Removes an entry from the ACL.
CopyAccessList | Copies the ACL.
_NewEnum | Gets pointer to enumerator object.

See Also

IADsAccessControlEntry, IADsSecurityDescriptor, Using Credentials and Security


IADsAccessControlList Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsAccessControlList interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
AclRevision | R/W | HRESULT get_AclRevision ([out] LONG *lnAclRevision) HRESULT put_AclRevision ([in] LONG lnAclRevision)
AceCount | R/W | HRESULT get AceCount ([out] LONG *lnAceCount) HRESULT put AceCount ([in] LONG lnAceCount)
_NewEnum | R/O | HRESULT get__NewEnum ([out] IUnknown *ppEnumerator);

Property Descriptions

AclRevision

The revision level of an access control list. This value should be ACL_REVISION. All ACEs in an ACL must be at the same revision level.

AceCount
The number of access control entries in the access control list.
_NewEnum
Returns an enumerator dependent object that implements IEnumVARIANT.


IADsAccessControlList::AddAce

Adds one or more access control entries (ACEs) to the access control list (ACL).

HRESULT AddAce(
  IDispatch * pAccessControlEntry  //Entries to be added
);

Parameters

[in] pAccessControlEntry
Array of ACEs to be added to the ACL. Cannot be NULL.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The ACE was added successfully.

See Also

IADsAccessControlEntry


IADsAccessControlList::RemoveAce

Removes one or more access control entries (ACEs) from the access control list (ACL).

HRESULT RemoveAce(
  IDispatch * pAccessControlEntry  //
);

Parameters

pAccessControlEntry
[in] Array of ACEs to be removed from the ACL.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The ACEs were successfully removed.

See Also

IADsAccessControlEntry


IADsAccessControlList::CopyAccessList

Copies all access control entries (ACEs) in the access control list (ACL) to the caller's process space.

HRESULT CopyAccessList(
  IDispatch * ppAccessControlEntry  //Entries to be added
);

Parameters

ppAccessControlEntry
[out] Address of a method-allocated array of IDispatch interface pointers to copies of the ACEs that make up the ACL. If this parameter is NULL on return, CopyAccessList could not copy the ACL.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The ACE was copied successfully.

Remarks

The caller is responsible for calling Release on the copies ACEs through their IDispatch pointers.

See Also

IADsAccessControlEntry, IADsSecurityDescriptor


IADsAccessControlList::_NewEnum

Returns a pointer to an enumerator object that can be used to enumerate ACEs in an ACL.

HRESULT _NewEnum(
  IUnknown ** ppEnumerator  //Interface on enumerator object
);

Parameter

ppEnumerator
[retval, out] Returns a pointer to IEnumVARIANT, which can be used to enumerate the access control entries in an access control list.

Return Values

This method supports the standard return values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED and E_FAIL, as well as the following:

S_OK
Returned the pointer successfully.

See Also

IEnumVARIANT, IADsAccessControlEntry, IADsSecurityDescriptor


IADsClass

The IADsClass interface enables a COM object to provide current schema class definitions for the type of Active Directory objects that can be created in a directory service. IADsClass, IADsProperty, and IADsSyntax make up the interfaces available on schema management objects to view and modify definitions for the schema class objects that define a directory service, including interfaces, properties, methods, containment relationships, and provider-specific rules.

Properties accessed by IADsClass are defined on the ADSI Schema Class Object.

Names of schema classes are those identified through the IADs::get_Schema method. Don't confuse the schema class name with the system CLSID class identifier property which indicates the COM object that implements this COM class.

When to Implement

Implement IADsClass when you are providing an Active Directory implementation for your directory service, or when you are adding functionality to an already existing provider implementation. If your directory service does not support extensible schemas, create an ADSI Schema Container Object that has properties that cannot be modified.

When to Use

Call the methods on IADsClass when you are browsing the ADSI Schema Container Objects in a schema container. These methods define which types of schema classes can contain or be contained by other schema class types. Call these methods whenever you access information about the type of schema object an Active Directory object is. The IADsClass:get_PrimaryInterface method identifies the IID for the interface that QueryInterface uses at run-time to determine whether an object is of a specific schema class.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsClass Methods | Description
get_PrimaryInterface | IID for interface defining this schema class.
get/put_CLSID | CLSID of code implementing this schema class.
get/put_OID | Directory service-specific Object Identifier.
get/put_Abstract | Whether or not this schema class is abstract.
get/put_Auxiliary | Whether or not this schema class is auxiliary.
get/put_MandatoryProperties | List of required properties needed before saving this object.
get/put_OptionalProperties | List of optional properties for this object.
get/put_NamingProperties | List of naming attributes for this object..
get/put_DerivedFrom | Immediate superclasses of this schema class.
get/put_AuxDerivedFrom | Immediate superclasses of this schema class.
get/put_PossibleSuperiors | List of classes that can contain instances of this class.
get/put_Containment | Legal objects types that can be contained within this container.
get/put_Container | Whether or not this is a container object.
get/put_HelpFileName | Optional help file name.
get/put_HelpFileContext | Optional help file context ID.
Qualifiers | Optional collection of provider-specific qualifiers for this property.

See Also

ADSI Schema Class Object, ADSI Schema Container Object


IADsClass Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsClass interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Abstract | R/W | HRESULT get_Abstract ([out] BOOLEAN *pbAbstract); HRESULT put_Abstract ([in] BOOLEAN bAbstract);
AuxDerivedFrom | R/W | HRESULT get_AuxDerivedFrom ([out] VARIANT *pvAuxDerivedFrom); HRESULT put_AuxDerivedFrom ([in] VARIANT vAuxDerivedFrom);
Auxiliary | R/W | HRESULT get_Auxiliary ([out] BOOLEAN *pbAuxiliary); HRESULT put_Auxiliary ([in] BOOLEAN bAuxiliary);
CLSID | R/W | HRESULT get_CLSID ([out] BSTR *pbstrCLSID); HRESULT put_CLSID ([in] BSTR bstrCLSID);
Container | R/W | HRESULT get_Container ([out] BOOLEAN *pbContainer); HRESULT put_Container| ([in] BOOLEAN bContainer);
Containment | R/W | HRESULT get_Containment ([out] VARIANT *pvContainment); HRESULT put_Containment ([in] VARIANT vContainment);
DerivedFrom | R/W | HRESULT get_DerivedFrom ([out] VARIANT *pvDerivedFrom); HRESULT put_DerivedFrom ([in] VARIANT vDerivedFrom);
HelpFileContext (optional) | R/W | HRESULT get_HelpFileContext ([out] BSTR *pbstrHelpFileContext); HRESULT put_HelpFileContext ([in] BSTR bstrHelpFileContext);
HelpFileName (optional) | R/W | HRESULT get_HelpFileName ([out] BSTR *pbstrHelpFileName); HRESULT put_HelpFileName ([in] BSTR bstrHelpFileName);
MandatoryProperties | R/W | HRESULT get_MandatoryProperties ([out] VARIANT *pvarMandatoryProperties); HRESULT put_MandatoryProperties ([in] VARIANT varMandatoryProperties);
OptionalProperties | R/W | HRESULT get_OptionalProperties ([out] VARIANT *pvarOptionalProperties); HRESULT put_OptionalProperties ([in] VARIANT varOptionalProperties);
NamingProperties | R/W | HRESULT get_NamingProperties ([out] VARIANT *pvarNamingProperties); HRESULT put_NamingProperties ([in] VARIANT varNamingProperties);
OID | R/W | HRESULT get_OID ([out] BSTR *pbstrOID); HRESULT put_OID ([in] BSTR bstrOID);
PossibleSuperiors | R/W | HRESULT get_PossibleSuperiors ([out] VARIANT *pvSuperiors); HRESULT put_PossibleSuperiors ([in] VARIANT vSuperiors);
PrimaryInterface | R/O | HRESULT get_PrimaryInterface ([out] BSTR *pbstrGUID);

Property Descriptions

Abstract
Boolean value indicating whether this class is Abstract or non-abstract. When TRUE this class is an Abstract class and cannot be directly instantiated in the directory service. Abstract classes can only be used as superclasses.
Auxiliary
Boolean value indicating whether or not this class is Auxiliary. When TRUE this class is an Auxiliary class and cannot be directly instantiated in the DS. Auxiliary classes can only be used as superclasses of other Auxiliary classes or as a source of additional properties on structural classes.
AuxDerivedFrom
Array of ADsPath strings that indicate the Auxiliary classes contributing to this class.
CLSID
Optional provider-specific CLSID that associates a COM object with this class.
Container
Property that determines if this class is an Active Directory container.
Containment
Container types that can contain objects of this class. Each container name is an element in a BSTR array.
DerivedFrom
Array of ADsPath strings that indicate which classes this class was derived from.
HelpFileContext
Context ID inside HelpFileName where specific information on this class can be found.
HelpFileName
Name of a help file (no path) that contains further information about objects of this class.
MandatoryProperties
SAFEARRAY of BSTRs listing the properties that must be set for this class to be written to storage.
NamingProperties
SAFEARRAY of BSTRs listing the properties that are for naming attributes of this schema class. For example, in NDS, "CN" and "OU" are naming properties.
OID
Provider-specific Object Identifier defining this class. This is provided to allow schema extension via Active Directory in directory services that require provider-specific OIDs for classes.
OptionalProperties
SAFEARRAY of BSTRs listing the properties that are optional for this schema class.
PossibleSuperiors
Array of ADsPath strings that indicate the schema classes that can contain instances of this class.
PrimaryInterface
Optional provider-specific identifier GUID that associates an interface with objects of this schema class. For example, the "User" class is defined by supporting IADsUser; the Primary interface is identified by IID_IADsUser. This must be in the standard string format of a GUID as defined by COM. This GUID is the value that will appear in the IADs::get_GUID property in instances of this class for providers that implement this property. Identifying a schema class by IID of the class code's primary interface enables the use of QueryInterface at run time to determine whether an object is of the desired class.


IADsClass::Qualifiers

Optional method returning a collection of Active Directory objects describing additional qualifiers of this schema class.

HRESULT IADsClass::Qualifiers(
  IADsCollection ** ppQualifiers  //Collection of additional
                                  // constraints
);

Parameter

ppQualifiers
[out] Address of IADsCollection* pointer variable that receives the interface pointer to the ADSI collection object representing additional limits for this schema class.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The IADsCollection interface pointer has been successfully retrieved.

Remarks

There is no standard ADSI qualifier object definition.

Notes to Callers

Active Directory implementations call this method when determining if there are any provider-specific constraints on the uses or values of this schema class.

Notes to Implementers

Return E_NOTIMPL if you do not support this interface.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsProperty::Qualifiers


IADsCollection

The IADsCollection interface enables a dependent COM object to define and manage the logical grouping of arbitrary sets of named data elements in Active Directory. Collections differ from arrays of elements since individual items can be added or deleted without re-ordering the entire array.

Collection objects can represent one or more items that have no physical underlying existence in the directory. For example, a collection object can represent a list of print jobs in a queue or a list of active sessions connected to a server. The implementation of a collection object may also save its data to persistent storage.

To manage lists of Active Directory object references, for example, users in a specific group, use the IADsMembers.

IADsCollection supports no properties.

When to Implement

Implement IADsCollection only when you are providing an Active Directory implementation for your directory service.

When to Use

Use the IADsCollection methods when you manage sets of data elements of an arbitrary nature. Collection objects can be saved to persistent storage in the underlying directory service and so can be used to represent any arbitrary information represented in a single Automation Variant type format. Collections can also represent volatile information that has no correspondence to the underlying directory service (for example, a list of print jobs or a list of communications sessions active in a server).

When you need to manage a list of Active Directory object references, use IADsMembers. When you are working with Active Directory objects that contain other objects, for instance when working with the Active Directory hierarchical directory structure or the network topology, use IADsContainer.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADsCollection Methods | Description
get__NewEnum | Get interface on an enumerator object.
Add | Add an object to the collection.
Remove | Remove an object from the collection.
GetObject | Gets the specified item.

See Also

ADSI Collection Object, ADSI Enumerator Object


IADsCollection::Add

Add a named item to this ADSI collection.

HRESULT IADsCollection::Add(
  BSTR bstrName,  //Name of item
  VARIANT varItem //Item to add to the collection
);

Parameter

bstrName
[in] Name of the item. IADsCollection::GetObject and IADsCollection::Remove reference the item by this name.
varItem
[in] Value of the item.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The named item has been successfully added.

Remarks

Collections for a directory service can also consist of a set of objects that cannot be changed.

Notes to Implementers

Collections that do not support direct addition of new items must return E_NOTIMPL.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsCollection::Remove


IADsCollection::get__NewEnum

Gets an dependent enumerator object that implements IEnumVARIANT for this ADSI collection object. Note that when C++/C software references this method, there are two underscore characters in the function name (get__NewEnum, put__NewEnum).

HRESULT IADsCollection::_NewEnum(
  IUnknown ** ppEnumerator  //Interface on enumerator object
);

Parameter

ppEnumerator
[out] Indirect pointer to the IUnknown interface on the enumerator object for this collection.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The interface pointer on the enumerator object for this collection has been successfully retrieved.

See Also

IEnumVARIANT, ADSI Enumerator Object


IADsCollection::GetObject

Gets the IADs interface of the Active Directory object in this container identified by the object's schema class and relative name.

HRESULT IADsCollection::GetObject(
  BSTR bstrName,    //Name of item
  VARIANT pvarItem  //Value retrieved
);

Parameter

bstrName
[in] Name of the item used by IADsCollection::Add when added to the collection.
pvarItem
[in] Current value of the item.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The interface pointer on the specified object in this collection has been successfully retrieved.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IEnumVARIANT, ADSI Enumerator Object


IADsCollection::Remove

Removes the named item from this ADSI collection object.

HRESULT IADsCollection::Remove(
  BSTR bstrItemToBeRemoved  //Name of item to remove
);

Parameter

bstrItemToBeRemoved
[in] Name of the item as it was specified by IADsCollection::Add.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The named item has been successfully removed from this collection object.

Remarks

Collections for a directory service can also consist of a set of objects that cannot be changed.

Notes to Implementers

Collections that do not support direct removal of items must return E_NOTIMPL.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsCollection::Add


IADsComputer

The IADsComputer interface enables a COM object in Active Directory to manage the information representing a computer (server, client, workstation, etc.) on a network.

Properties accessed by IADsComputer are defined on the ADSI Computer Object.

When to Implement

Implement IADsComputer only when you are providing an Active Directory implementation for your directory service.

When to Use

Call the methods on this interface when you are referencing the information describing the physical computer or its network addresses.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke |  | Calls one of the object's methods, or gets/sets one of its properties.

IADs Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsComputer Methods | Description
get_ComputerID | Gets/sets globally unique identifier for this machine.
get_Site | Gets/sets globally unique identifier for this site.
get/put_Description | Gets/sets description of this computer.
get/put_Location | Gets/sets physical location of this computer.
get/put_PrimaryUser | Gets/sets contact person for this computer.
get/put_Owner | Gets/sets licensed user of this computer.
get/put_Division | Gets/sets division to which this computer belongs.
get/put_Department | Gets/sets department to which this computer belongs.
get/put_Role | Gets/sets ole of this computer (server, workstation, etc.)
get/put_OperatingSystem | Gets/sets installed operating system in use.
get/put_OperatingSystemVersion | Gets/sets version of installed operating system in use.
get/put_Model | Gets/sets make/model of this computer.
get/put_Processor | Gets/sets type of processor.
get/put_ProcessorCount | Gets/sets number of processors installed in this computer.
get/put_MemorySize | Gets/sets size of RAM in MB.
get/put_StorageCapacity | Gets/sets size of disk space in MB.
get/put_NetAddresses | Gets/sets binding information.


IADsComputer Property Methods

The methods of the IADsComputer interface read and write the properties described in this topic. For more information see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
ComputerID | R/O | HRESULT get_ComputerID ([out] BSTR *pbstrComputerID);
Department | R/W | HRESULT get_Department ([out] BSTR *pbstrDepartment); HRESULT put_Department ([in] BSTR bstrDepartment);
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
Division | R/W | HRESULT get_Division ([out] BSTR *pbstrDivision); HRESULT put_Division ([in] BSTR bstrDivision);
Location | R/W | HRESULT get_Location ([out] BSTR *pbstrLocation); HRESULT put_Location ([in] BSTR bstrLocation);
MemorySize | R/W | HRESULT get_MemorySize ([out] LONG *plMemorySize); HRESULT put_MemorySize ([in] LONG lMemorySize);
Model | R/W | HRESULT get_Model ([out] BSTR *pbstrModel); HRESULT put_Model ([in] BSTR bstrModel);
NetAddresses | R/W | HRESULT get_NetAddresses ([out] VARIANT *pvNetAddresses); HRESULT put_NetAddresses ([in] VARIANT vNetAddresses);
OperatingSystem | R/W | HRESULT get_OperatingSystem ([out] BSTR *pbstrOperatingSystem); HRESULT put_OperatingSystem ([in] BSTR bstrOperatingSystem);
OperatingSystemVersion | R/W | HRESULT get_OperatingSystemVersion ([out] BSTR *pbstrOperatingSystemVersion); HRESULT put_OperatingSystemVersion ([in] BSTR bstrOperatingSystemVersion);
Owner | R/W | HRESULT get_Owner ([out] BSTR *pbstrOwner); HRESULT put_Owner ([in] BSTR bstrOwner);
PrimaryUser | R/W | HRESULT get_PrimaryUser ([out] BSTR *pbstrPrimaryUser); HRESULT put_PrimaryUser ([in] BSTR bstrPrimaryUser);
Processor | R/W | HRESULT get_Processor ([out] BSTR *pbstrProcessor); HRESULT put_Processor ([in] BSTR bstrProcessor);
ProcessorCount | R/W | HRESULT get_ProcessorCount ([out] LONG *plProcessorCount); HRESULT put_ProcessorCount ([in] LONG lProcessorCount);
Role | R/W | HRESULT get_Role ([out] BSTR *pbstrRole); HRESULT put_Role ([in] BSTR bstrRole);
Site | R/O | HRESULT get_Site ([out] BSTR *pbstrSite);
StorageCapacity | R/W | HRESULT get_StorageCapacity ([out] LONG *plStorageCapacity); HRESULT put_StorageCapacity ([in] LONG lStorageCapacity);

Property Descriptions

ComputerID
Get the globally unique identifier assigned to each machine, which serves as the authoritative identifier.
Department
Gets and sets the department (e.g. OU or Organizational Unit) within a company that this computer belongs to.
Description
Gets and sets the description of this computer.
Division
Gets and sets the division (e.g. Organization) within a company that this computer belongs to.
Location
Gets and sets the physical location of the machine where this machine is typically located.
MemorySize
Gets and sets the size of RAM in MB.
Model
Gets and sets the make/model of this machine.
NetAddresses
Gets an array of NetAddress fields that represent the addresses by which this computer can be reached. NetAddress is a provider-specific BSTR composed of two substrings separated by a colon (":"). The left-hand substring indicates the address type, and the right-hand substring is a string representation of an address of that type. For example, TCP/IP addresses are of the form "IP:100.201.301.45. IPX type addresses are of the form "IPX:10.123456.80".
OperatingSystem
Gets and sets the name of the operating system used on this machine.
OperatingSystemVersion
Gets and sets the operating system version number.
Owner
Gets and sets the name of the person that typically uses this machine and has a license to run the installed software.
PrimaryUser
Gets and sets the name of the contact person in case something needs to be changed on this machine.
Processor
Gets and sets the type of processor.
ProcessorCount
Gets and sets the number of processors.
Role
Gets and sets the role of this machine: for example, workstation, server, domain controller.
Site
Gets the globally unique identifier identifying the site this machine was installed in. A site represents a physical region of good connectivity in a network.
StorageCapacity
Gets and sets the disk space in MB.

See Also

IADsComputerOperations, ADSI Computer Object


IADsComputerOperations

The IADsComputerOperations interface provides methods on a COM object in ADSI to retrieve the status of a computer over a network and to remotely shut it down.

The property accessed by IADsComputerOperations is defined on ADSI Computer Object.

When to Implement

Implement IADsComputerOperations only when you are providing an Active Directory implementation for a directory service that supports computer control over a network.

When to Use

Call the methods on this interface when you are querying the current status of a computer or controlling it over a network.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsComputerOperations Methods | Description
Status | Returns the current operations status
Shutdown | Executes shutdown with optional reboot.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsComputer, ADSI Computer Object


IADsComputerOperations::Shutdown

Causes a computer under Active Directory control to execute the shutdown operation with an optional reboot.

HRESULT IADsComputerOperations::Shutdown(
  boolean bReboot  //TRUE means reboot after shutting down
);

Parameter

bReboot
[in] If TRUE then reboot the computer after the shutdown is complete.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The shutdown command has been issued successfully.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsComputer, ADSI Computer Object


IADsComputerOperations::Status

Causes a computer under Active Directory control to execute the shutdown operation with an optional reboot.

HRESULT IADsComputerOperations::Status(
  IDispatch ** ppObject  //TBD.
);

Parameter

ppObject
[out, retval] Computer Operations status code.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The shutdown command has been issued successfully.

See Also

IADsComputer, ADSI Computer Object


IADsContainer

The IADsContainer interface enables an ADSI container object to create, delete and manage other Active Directory objects. Container objects are used both to organize the Active Directory hierarchical architecture and to directly represent the hierarchical nature of directory trees in a file system.

Properties accessed by IADsContainer are defined on the ADSI Container Object.

Note Every ADSI container object supports both IADs and IADsContainer. IADs::GetInfo does not affect the objects stored in the container but affects only the properties of the container. IADs::SetInfo called on a container affects any newly created objects within the container and the container's properties.

When to Implement

Implement IADsContainer only when you are providing an Active Directory implementation for your directory service. Every Active Directory object that contains other Active Directory objects must support this interface.

When to Use

Call these methods to enumerate or manage the life-cycle of Active Directory objects contained by this object. For example, you can recursively navigate down a hierarchical directory tree. By calling QueryInterface for the IADsContainer method, you can tell if there are further levels on the tree. If the interface is not supported, you are at a leaf. If the interface is supported, you are at another container, and can call QueryInterface on that object.

In addition to representing a directory tree, ADSI containers are used to implement the Active Directory architecture. Examples of ADSI container objects include the ADSI Namespaces Object (contains ADSI Namespace Objects), the ADSI Namespace Object (contains all the roots of an Active Directory provider implementation), and other provider-specific containers.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke |  | Calls one of the object's methods, or gets/sets one of its properties.

IADsContainer Methods | Description
get_Count | Gets the number of Active Directory objects in container.
get__NewEnum | Get interface on an enumerator object.
Get/put_Filter | Gets/sets the filter on the schema classes to use for an enumeration.
Get/put_Hints | Gets/sets properties to load.
GetObject | Gets interface on a named object.
Create | Requests creation of specified object..
Delete | Deletes a specified object.
CopyHere | Copies a specified object within a directory service.
MoveHere | Moves a specified object within a directory service.


IADsContainer Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsContainer interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Compiler Syntax
_NewEnum | R/O | HRESULT get__NewEnum ([out] IUnknown *ppEnumerator);
Count | R/O | HRESULT get_Count ([out] LONG *plCount);
Filter | R/W | HRESULT get_Filter ([out] VARIANT *pvFilter); HRESULT put_Filter ([in] VARIANT vFilter);
Hints | R/W | HRESULT get_Hints ([out] VARIANT *pvHints); HRESULT put_Hints ([in] VARIANT vHints);

Property Descriptions

_NewEnum
Returns an enumerator dependent object that implements IEnumVARIANT.
Count
Gets the number of items in the container. If the filter is set then count returns only the number of items that fit the filter description.
Filter
Gets and sets the filter on the object classes that can be retrieved in a given enumeration. The client can also give hints (see below) about which properties of the objects it uses after the enumeration. If Filter is not set or set to empty, all objects of all classes are retrieved by the enumerator. Otherwise, each array entry is a schema class name in BSTR format or another format specified by the provider.
Hints
The vHints parameter allows the client to indicate which properties to load, so the provider can attempt to optimize network access. If no hints are specified, the VARIANT vHints is marked as empty, and the provider is expected to provide as much smart network access as possible. Otherwise, each entry in the array should have the following format is a BSTR value identifying a property name found in the schema definition for this object type.

See Also

ADSI Container Object, ADSI Enumerator Object


IADsContainer::CopyHere

Creates a new copy of the specified Active Directory object in this container. Copies can only be made within containers in one Active Directory provider's implementation, not across directory systems.

HRESULT IADsContainer::CopyHere(
  BSTR bstrSourceObject,  //Name of the object to copy
  BSTR bstrNewName,       //Optional name for the new object
  IADs ** ppNewObject     //Interface on the new object
);

Parameter

bstrSourceObject
[in] The object to be copied.
bstrNewName
[in] Optional name of the new object within the container.
ppNewObject
[out] Indirect pointer to the IADs interface on the copied object.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The specified object has been successfully copied to this container.

Remarks

The destination container must be in the same directory service as the source container. Copying objects across directory service implementations is not permitted.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsContainer::MoveHere


IADsContainer::Create

Sets up a request to create an Active Directory object of the specified schema class and name in this container object. The object is not actually created until IADs::SetInfo on the new object saves the properties and initiates the action. This allows for setting mandatory properties on the new object.

HRESULT IADsContainer::Create(
  BSTR bstrClass,         //Name of the schema class of this object
  BSTR bstrRelativeName,  //Relative name of the object to create
  IDispatch ** ppNewObject     //Interface on the new object
);

Parameter

bstrClass
[in] Name of the schema class object to create, as it is found through the IADs::get_Schema method.
bstrRelativeName
[in] Name of the object as it is known in the underlying directory and identical to the one retrieved through the IADs::get_Name method.
ppNewObject
[out] Indirect pointer to the IDispatch interface on the newly created object.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The specified object has been successfully created within this container object.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsContainer::Delete


IADsContainer::Delete

Deletes the specified Active Directory object from this container object.

HRESULT IADsContainer::Delete(
  BSTR bstrClass,        //Name of the schema class of this object
  BSTR bstrRelativeName  //Relative name of the object to create
);

Parameter

bstrClass
[in] Name of the schema class object to delete, as it is found through the IADs::get_Schema method.
bstrRelativeName
[in] Name of the object as it is known in the underlying directory and identical to the one retrieved through the IADs::get_Name method.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The specified object has been successfully deleted from this container object.

Remarks

When you delete an object, make sure you delete the interface pointers to that object. Deleting an object removes it from the underlying file system immediately. Any interface pointers held by the application for the deleted object are still valid because the interface pointers refer to Active Directory objects in memory. SetInfo and GetInfo calls using interface pointers for a deleted object return an error.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsContainer::Create


IADsContainer::get__NewEnum

Gets a dependent enumerator object that implements IEnumVARIANT for this ADSI container object. Note that when C++/C software references this method, there are two underscore characters in the function name (get__NewEnum, put__NewEnum).

HRESULT IADsContainer::_NewEnum(
  IUnknown ** ppEnumerator  //Interface on enumerator object
);

Parameter

ppEnumerator
[out] Indirect pointer to the IUnknown interface on the enumerator object for this container.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The interface pointer on the enumerator object for this collection has been successfully retrieved.

See Also

IEnumVARIANT, ADSI Enumerator Object


IADsContainer::GetObject

Gets the IADs interface of the Active Directory object in this container identified by the object's schema class and relative name.

HRESULT IADsContainer::GetObject(
  BSTR bstrClass,        //Schema class of the object
  BSTR bstrRelativeName, //Relative name of the object
  IDispatch ** ppNamedObject  //Interface to use on the object
);

Parameter

bstrClass
[in] Name of the object as it is known in the underlying directory and identical to the one retrieved through the IADs::get_Name method. If the class name is NULL, the provider returns the first item found in the container.
bstrRelativeName
[in] Name of the object as it is known in the underlying directory and identical to the one retrieved through the IADs::get_Name method.
ppNamedObject
[out] Indirect pointer to the IDispatch interface on the specified object.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The interface pointer on the specified object in this container has been successfully retrieved.

Remarks

This is the most common way of retrieving an interface pointer on an Active Directory object.

Notes to Implementers

If the schema class name is not provided, retrieve an interface pointer on the first object found in the container with the specified name.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

ADsGetObject


IADsContainer::MoveHere

Moves the specified object to this ADSI container. Moves can only be made within that container in one Active Directory provider's implementation, not across directory systems.

HRESULT IADsContainer::MoveHere(
  BSTR bstrSourceObject,  //Name of the object to move
  BSTR bstrNewName,       //Name for the new object
  IDispatch ** ppNewObject     //Interface on the new object
);

Parameter

bstrSourceObject
[in] The string specifying the object to be moved.
bstrNewName
[in] A string that names the new object within the container.
ppbstrNewObject
[out] Indirect pointer to the IDispatch interface on the moved object.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The specified object has been successfully moved to this container.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsContainer::CopyHere


IADsDomain

The IADsDomain interface enables a COM object in Active Directory to manage a common set of rules concerning passwords that apply to the accounts on a domain of computers or servers.

Properties accessed by IADsDomain are defined on the ADSI Domain Object.

When to Implement

Implement IADsDomain only when you are providing an Active Directory implementation for a directory service that supports domains.

Under the Windows NT implementation, this interface is implemented on the object WinNTDomain.

When to Use

Call the methods and properties of this interface when you are managing the password rules of domain members.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke |  | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsDomain Methods | Description
get_IsWorkgroup | TRUE if the "domain" is actually a workstation that is a member of a workgroup.
get/put_MinPasswordLength | Gets/sets minimum number of characters required.
get/put_MinPasswordAge | Gets/sets minimum age before allowing a password change.
get/put_MaxPasswordAge | Gets/sets age at which password must be changed.
get/put_MaxBadPasswordsAllowed | Gets/sets maximum bad password logins before lockout.
get/put_PasswordHistoryLength | Gets/sets number of passwords saved.
get/put_PasswordAttributes | Gets/sets password restrictions.
get/put_AutoUnlockInterval | Gets/sets minimum time elapsed before account automatically re-enabled.
get/put_LockoutObservationInterval | Gets/sets time window for monitoring account.


IADsDomain Property Methods

The methods of the IADsDomain interface read and write the properties described in this topic. For more information see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
AutoUnlockInterval | R/W | HRESULT get_AutoUnlockInterval ([out] LONG *plAutoUnlockInterval); HRESULT put_AutoUnlockInterval ([in] LONG lAutoUnlockInterval);
IsWorkgroup | R/O | HRESULT get_IsWorkgroup ([out] VARIANT_BOOL *retval);
LockoutObservationInterval | R/W | HRESULT get_ LockoutObservationInterval ([out] LONG *plLockoutObservationInterval); HRESULT put_ LockoutObservationInterval ([in] LONG lLockoutObservationInterval);
MinPasswordAge | R/W | HRESULT get_MinPasswordAge ([out] LONG *plMinPasswordAge); HRESULT put_MinPasswordAge ([in] LONG lMinPasswordAge);
MinPasswordLength | R/W | HRESULT get_MinPasswordLength ([out] LONG *plMinPasswordLength); HRESULT put_MinPasswordLength ([in] LONG lMinPasswordLength);
MaxBadPasswordsAllowed | R/W | HRESULT get_ MaxBadPasswordsAllowed ([out] LONG *plMaxBadPasswordsAllowed); HRESULT put_ MaxBadPasswordsAllowed ([in] LONG lMaxBadPasswordsAllowed);
MaxPasswordAge | R/W | HRESULT get_MaxPasswordAge ([out] LONG *plMaxPasswordAge); HRESULT put_MaxPasswordAge ([in] LONG lMaxPasswordAge);
PasswordAttributes | R/W | HRESULT get_PasswordAttributes ([out] LONG *plPasswordAttributes); HRESULT put_PasswordAttributes ([in] LONG lPasswordAttributes);
PasswordHistoryLength | R/W | HRESULT get_PasswordHistoryLength ([out] LONG *plPasswordHistoryLength); HRESULT put_PasswordHistoryLength ([in] LONG lPasswordHistoryLength);

Property Descriptions

AutoUnlockInterval
Gets and sets the minimum time elapsed before account is automatically re-enabled.
IsWorkGroup
Tests whether or not the domain is actually a workstation that is a member of a workgroup.
LockoutObservationInterval
Gets and sets the time window during which the bad password count is monitored and accumulated to decide if the account needs to be locked out. For example, if the number of bad password attempts on an account exceed the threshold (Maximum Bad Passwords Allowed) during the specified time period (Lockout Observation Interval) the account will be locked out by setting the appropriate property in the Login Parameter property set.
MinPasswordAge
Gets and sets the minimum password age before allowing the password to be changed.
MinPasswordLength
Gets and sets the minimum number of characters that must be typed in for a password.
MaxBadPasswordsAllowed
Gets and sets the maximum number of bad password logins until the account becomes locked out.
MaxPasswordAge
Gets and sets the age at which the password must be changed by the owner.
PasswordAttibutes
Gets and sets other restrictions on passwords. The following restrictions are currently defined:
Attribute | Value
PASSWORD_ATTR_NONE | 0x00000000
PASSWORD_ATTR_MIXED_CASE | 0x00000001
PASSWORD_ATTR_COMPLEX | 0x00000002

Note For PASSWORD_ATTR_COMPLEX, the password must include at least one punctuation mark or non-printable character.

PasswordHistoryLength
The number of previous passwords saved in the history list. The user cannot reuse a password that is in the history list.

See Also

ADSI Domain Object


IADsFileService

The IADsFileService interface enables a COM object in Active Directory to manage the information describing a software file service provided by a specific computer. Use IADsFileServiceOperations to retrieve interface pointers to the collections of active sessions or open resources used by a file service. IADsService and IADsServiceOperations manage information and provide controls over a network for a software service that is not a file service.

Properties accessed by IADsFileService are defined on an ADSI Service Object that represents a file service.

When to Implement

Implement IADsFileService only when you are providing an Active Directory implementation for a directory service that publishes the availability of file services on a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

Under the Windows NT implementation, this interface is implemented on WinNTService.

When to Use

Call the methods on IADsFileService to manage general file service information.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsService Properties and Methods | Description
get/put_HostComputer | Host of this service.
get/put_DisplayName | Display name of this service.
get/put_Version | Version of this service.
get/put_ServiceType | Process type in which this service runs.
get/put_StartType | At what time this service starts.
get/put_Path | Path and filename of executable.
get/put_StartupParameters | Parameters passed on start-up.
get/put_ErrorControl | Actions for service failure.
get/put_LoadOrderGroup | The load order group for this service.
get/put_ServiceAccountName | Authentication account name.
get/put_ServiceAccountPath | Path to user object for authentication.
get/put_Dependencies | Other load groups or services this service needs.

IADsFileService Methods | Description
get/put_Description | Description of the file service.
get/put_MaxUserCount | Maximum number of users allowed to run service concurrently.


IADsFileService Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsFileService interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
MaxUserCount | R/W | HRESULT get_MaxUserCount ([out] LONG *plMaxUserCount); HRESULT put_MaxUserCount ([in] LONG lMaxUserCount);

Property Descriptions

Description
Gets and sets the description of the file service.
MaxUserCount
Gets and sets the maximum number of users allowed on the service at one time.

See Also

IADsService, IADsFileServiceOperations, IADsServiceOperations, ADSI Service Object


IADsFileServiceOperations

The IADsFileServiceOperations interface support properties and methods that control a software file service published on a network.

Properties accessed by IADsFileServiceOperations are defined on the ADSI Service Object when it represents a file service.

When to Implement

Implement IADsFileServiceOperations only when you are providing an Active Directory implementation for a directory service that supports controlling file over a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

When to Use

Call the methods and properties of this interface when you are controlling a software file service available over a network.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsServiceOperations Properties and Methods | Description
Status | Gets the status of the service.
Start | Start the service.
Stop | Stop the service.
Pause | Pause the service.
Continue | Continue the service.
SetPassword | Sets password to be used by service manager to create security context.

IADsFileServiceOperations Methods | Description
Sessions | Gets an interface pointer on a collection object that represents current open sessions on this file service.
Resources | Gets an interface pointer on a collection object that represents current open resources for this file service.

See Also

IADsFileService, IADsServiceOperations, IADsService, ADSI Service Object


IADsFileServiceOperations::Resources

Gets an interface pointer IADsCollection on a collection that consists of the resource objects that represent the current open resources on this file service.

HRESULT IADsFileServiceOperations::Resources(
  IADsCollection ** ppResources  // Current open resources for this
                                 // file service.
);

Parameter

ppResources
[out] Indirect pointer to the IADsCollection interface that can then be used to enumerate the ADSI Resource Objects that represent the current open resources in use for this file service.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The interface pointer on the resource collection object has been successfully retrieved.

Remarks

Traditional directory services supply information only about directory service elements that are represented in the underlying data store. Information about resources for file services may not be available from the underlying store.

Notes to Implementers

If your object does not support dependent resource objects for file services, return E_NOTIMPL from this method.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsFileService, ADSI Service Object


IADsFileServiceOperations::Sessions

Gets an interface pointer IADsCollection on a collection that consists of the session objects that represent the current sessions in use for this file service.

HRESULT IADsFileServiceOperations::Sessions(
  IADsCollection ** ppSessions  // Current open sessions in use for
                                // this file service.
);

Parameter

ppSessions
[out] Indirect pointer to the IADsCollection interface that can then be used to enumerate the ADSI Session Objects that represent the current open sessions for this file service.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The interface pointer on the session collection object has been successfully retrieved.

Remarks

Traditional directory services supply information only about directory service elements that are represented in the underlying data store. Information about sessions for file services may not be available from the underlying store..

Notes to Implementers

If your object does not support dependent session objects for file services, return E_NOTIMPL from this method.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsFileService, ADSI Service Object


IADsFileShare

The IADsFileShare interface enables a COM object in Active Directory to represent a published file sharing point of a file service in a directory.

Properties accessed by IADsFileShare are defined on the ADSI FileShare Object.

When to Implement

Implement IADsFileShare only when you are providing an Active Directory implementation for a directory service that publishes the file share points of services on a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

When to Use

Call the methods on IADsFileShare when you are referencing or publishing information about a file share point for a file service.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke |  | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsFileShare Methods | Description
get_CurrentUserCount | Current number of users connected to this share.
get/put_Description | Description of the file share.
get/put_HostComputer | ADsPath reference to the host computer.
get/put_Path | File system path to shared directory.
get/put_MaxUserCount | Maximum number of users allowed to access share at any one time.


IADsFileShare Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsFileshare interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
CurrentUserCount | R/O | HRESULT get_CurrentUserCount ([out] LONG *plCurrentUserCount);
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
HostComputer | R/W | HRESULT get_HostComputer ([out] BSTR *pbstrHostComputer); HRESULT put_HostComputer ([in] BSTR bstrHostComputer);
MaxUserCount | R/O | HRESULT get_MaxUserCount ([out] LONG *plMaxUserCount);
Path | R/W | HRESULT get_Path ([out] BSTR *pbstrPath); HRESULT put_Path ([in] BSTR bstrPath);

Property Descriptions

CurrentUserCount
Gets the current number of users connected to the share.
Description
Gets and sets the description of the file share.
HostComputer
Gets and sets an ADsPath reference to the host computer.
MaxUserCount
Gets and sets the maximum number of users allowed to access the share at one time.
Path
Gets and sets the file system path to the shared directory.

See Also

ADSI FileShare Object, ADSI Service Object


IADsGroup

The IADsGroup interface enables a COM object in Active Directory to manage the information that describes and manages group membership.

Properties accessed by IADsGroup are defined on the ADSI Group Object.

When to Implement

Implement IADsGroup only when you are providing an Active Directory implementation for a directory service that supports group memberships.

When to Use

Call the methods on this interface to reference the description of a group membership.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke |  | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsGroup Properties and Methods | Description
get/put_Description | Description of the group membership.
Members | Gets an IADsMembers interface on the members object that is the collection of ADSI objects that represent the members of this group.
IsMember | Tests for membership.
Add | Adds an object to a group.
Remove | Removes an object from a group.


IADsGroup Property Methods

The methods of the IADsGroup interface read and write the properties described in this topic. For more information see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);

Property Description

Description
Gets and sets the text that describes the group.

See Also

ADSI Group Object


IADsGroup::Add

Adds an ADSI object to an existing group.

HRESULT IADsGroup::Add(
  BSTR bstrNewItem  //ADsPath of the object to add
);

Parameter

bstrNewItem
[in] ADsPath of the object being added to the group.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The named object has been successfully added to this group.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsMembers, ADSI Group Object, ADSI Members Object


IADsGroup::IsMember

Determines if an Active Directory object is a member of the specified group.

HRESULT IADsGroup::IsMember(
  BSTR bstMember,         //ADsPath of object to check
  VARIANT_BOOL * bMember  //TRUE if object is a member
);

Parameter

pbstrName
[in] ADsPath name of the Active Directory object to be checked for membership in the group object that supports this interface method.
bMember
[out] TRUE if this object is a member of this group.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The indicated object is a member of this group.
Notes to Implementers

If a group is allowed to have other groups as members, you may need to support this as a recursive method.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsMembers, ADSI Group Object, ADSI Members Object


IADsGroup::Members

Gets the IADsMembers interface on the ADSI collection object that represents the members of this group.

HRESULT IADsGroup::Members(
  IADsMembers ** ppMembers  //Interface on the members collection
                            // object
);

Parameter

ppMembers
[out] Pointer to the IADsMembers interface that supports methods to identify, manage, and filter members of this group.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The IADsMembers interface pointer on this group object has been successfully retrieved.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsMembers, ADSI Group Object, ADSI Members Object


IADsGroup::Remove

Removes the specified ADSI object from this group. This does not affect the ADSI object itself, just its membership in this group.

HRESULT IADsGroup::Remove(
  BSTR bstrItemToBeRemoved  //ADsPath of the object
);

Parameter

bstrItemToBeRemoved
[in] ADsPath of the object to be removed from the group.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The object was successfully removed.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsMembers, ADSI Group Object, ADSI Members Object


IADsLocality

The IADsLocality interface enables a COM object in Active Directory to manage the data representing geographical location of an accout. This interface is one of several that provide support for directory services that organize accounts by country, locality (geographical location), organization (company), and organizational unit (department). Properties accessed by IADsLocality are defined on the ADSI Locality Object.

When to Implement

Implement IADsLocality when you are providing an Active Directory implementation for your directory service that organizes directory entries by geographical location.

When to Use

Call the methods on this interface when you are expanding a directory that organizes accounts by physical location.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsLocality Methods | Description
get/put_Description | Description of this region.
get/put_LocalityName | Name of this region.
get/put_PostalAddress | Post office address of this region.
get/put_SeeAlso | Any other information relevant to this region.


IADsLocality Property Methods

The methods of the IADsLocality interface read and write the properties described in this topic. For more information see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
LocalityName | R/W | HRESULT get_LocalityName ([out] BSTR *pbstrLocalityName); HRESULT put_LocalityName ([in] BSTR bstrLocalityName);
PostalAddress | R/W | HRESULT get_PostalAddress ([out] BSTR *pbstrPostalAddress); HRESULT put_PostalAddress ([in] BSTR bstrPostalAddress);
SeeAlso | R/W | HRESULT get_SeeAlso ([out] BSTR *pbstrSeeAlso); HRESULT put_SeeAlso ([in] BSTR bstrSeeAlso);

Property Descriptions

Description
Gets and sets the text that describes the locality.
LocalityName
Gets and sets the CLSID of the code implementing the Active Directory object for this schema class.
PostalAddress
Gets and sets the main postal address of the locality.
SeeAlso
Gets and sets an array of ADsPath names of other directory objects which may be relevant to this object.

See Also

ADSI Locality Object


IADsMembers

The IADsMembers interface enables a dependent COM object to define and manage lists of Active Directory object references.

Properties accessed by IADsMembers are defined on the ADSI Members Object.

To manage sets of arbitrary data elements that are not object references, use IADsCollection.

When to Implement

Implement IADsMembers only when you are providing an Active Directory implementation for your directory service that supports group memberships for individual accounts.

When to Use

Use the IADsMembers methods when you manage associations among Active Directory objects. Examples of members of a group in the Active Directory architecture are:

  1. The collection of ADSI Group Objects that represent the groups to which a user belongs.
  2. The collection of ADSI Members Objects that represent the members of a group.

When you need to manage a list of Active Directory object references, use IADsMembers. When you are working with Active Directory objects that contain other objects, for instance when working with the Active Directory hierarchical directory structure or the network topology, use IADsContainer.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADsMembers Properties and Methods | Description
get_Count | Gets the number of members..
get__NewEnum | Retrieve interface on an enumerator object.
get/put_Filter | Gets and sets the filter for selection.


IADsMembers Property Methods

The methods of the IADsMembers interface read and write the properties described in this topic. For more information see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Count | R/O | HRESULT get_Count ([out] LONG *plCountr);
_NewEnum | R/O | HRESULT get__NewEnum ([out] IUnknown *ppEnumerator);
Filter | R/W | HRESULT get_Filter ([out] VARIANT *pvFilter); HRESULT put_Filter ([in] VARIANT vFilter);

Property Descriptions

Count
Gets the number of items in the container. If the filter is set then count returns only the number of items that fit the filter description.
_NewEnum
Returns an enumerator dependent object that implements IEnumVARIANT.
Filter
Gets and sets the filter. The syntax of the entries in the Filter array is the same as the Filter used on the IADsContainer interface.

See Also

ADSI Collection Object, ADSI Group Object, ADSI Enumerator Object, ADSI Members Object


IADsMembers::get__NewEnum

Gets an dependent enumerator object that implements IEnumVARIANT for this ADSI collection object. Note that when C++/C software references this method, there are two underscore characters in the function name (get__NewEnum, put__NewEnum).

HRESULT IADsMembers::_NewEnum(
  IUnknown ** ppEnumerator  //Interface on enumerator object
);

Parameter

ppEnumerator
[out] Indirect pointer to the IUnknown interface on the enumerator object for this collection.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The interface pointer on the enumerator object for this collection has been successfully retrieved.

See Also

IEnumVARIANT, ADSI Enumerator Object


IADsNamespaces

The IADsNamespaces interface enables a COM container object in Active Directory to enumerate all the top-level provider container objects currently installed.

Properties accessed by IADsNamespaces are defined on the ADSI Namespaces Object.

When to Implement

You do not need to Implement IADsNamespaces. This is part of the Active Directory services software component.

When to Use

Since you can always get an interface pointer to the ADSI NameSpaces Object using its pre-defined name "ADS://" or "@ADS!", the method supported by IADsNamespaces supplies you with a starting point in the directory. Using the default container ADsPath name, you can quickly obtain an IADs interface pointer through ADSIGetObject (or GetObject) to start browsing through the entire directory structure.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.
get/put_DefaultContainer | The default container name for the current user.


IADsNamespaces Property Methods

The methods of the IADsNamespaces interface read and write the properties described in this topic. For more information see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
DefaultContainer | R/W | HRESULT get_Default ([out] BSTR *pbstrDefault); HRESULT put_Default ([in] BSTR bstrDefault);

Property Descriptions

DefaultContainer
Gets and sets the directory service-specific ADsPath name for an Active Directory container object. Active Directory defines the default container property to provide a quick way of getting a pointer to a previously-defined Active Directory container object. Providers need to supply this property on a "per-user" basis, that is, the logged-on user providing the context in which to run. The default container is an ADsPath name that, by definition, identifies an object to which you can bind. Setting the default container, unlike setting properties through other Active Directory interfaces that use the property cache, takes place immediately.

Notes to Callers The bstrClass parameter in IADsContainer::GetObject is ignored. Enumerating the namespaces container object always yields the list of provider namespace objects.

Notes to Implementers IADsContainer::GetObject takes a bstrClass parameter that allows the caller to specify the type of object to look for. Because the namespaces object contains only namespace objects, this parameter should be ignored.

See Also

ADSI Namespaces Object


IADsO

The IADsO interface enables a COM object in Active Directory to manage the data representing the organization to which an account belongs. This interface is one of several that provide support for directory services that organize accounts by country, locality (geographical location), organization (company), and organizational unit (department).

Properties accessed by IADsO are defined on the ADSI Organization Object.

When to Implement

Implement IADsO when you are providing an Active Directory implementation for your directory service that organizes directory entries by organization.

When to Use

Call the methods on this interface when you are expanding a directory that organizes accounts by physical location.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsO Methods | Description
get/put_Description | Description of the organization, such as company name.
get/put_LocalityName | Physical location of the organization.
get/put_PostalAddress | Post office address of the organization.
get/put_TelephoneNumber | Telephone number.
get/put_FaxNumber | Fax number.
get/put_SeeAlso | Other information relevant to this organization.


IADsO Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsO interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
FaxNumber | R/W | HRESULT get_FaxNumber ([out] BSTR *pbstrFaxNumber); HRESULT put_FaxNumber ([in] BSTR bstrFaxNumber);
LocalityName | R/W | HRESULT get_LocalityName ([out] BSTR *pbstrLocalityName); HRESULT put_LocalityName ([in] BSTR bstrLocalityName);
PostalAddress | R/W | HRESULT get_PostalAddress ([out] BSTR *pbstrPostalAddress); HRESULT put_PostalAddress ([in] BSTR bstrPostalAddress);
TelephoneNumber | R/W | HRESULT get_TelephoneNumber ([out] BSTR *pbstrTelephoneNumber); HRESULT put_TelephoneNumber ([in] BSTR bstrTelephoneNumber);
SeeAlso | R/W | HRESULT get_SeeAlso ([out] BSTR *pbstrSeeAlso); HRESULT put_SeeAlso ([in] BSTR bstrSeeAlso);

Property Descriptions

Description
Gets and sets the text that describes the locality.
FaxNumber
Gets and sets the fax number associated with the organization.
LocalityName
Gets and sets the locality name. The locality name identifies a geographical area in which the container is physically located.
PostalAddress
Gets and sets the main postal address of the locality.
TelephoneNumber
Gets and sets the telephone number associated with the organization.
SeeAlso
Gets and sets an array of ADsPath names of other directory objects which may be relevant to this object.

See Also

ADSI Organization Object


IADsOpenDSObject

In order to supply a security context in which to open an object from the underlying directory service, the IADsOpenDSObject interface provides a means to specify a client's credentials. Once these credentials are established, they apply to any actions on this object or on any objects contained within this object. When this object is released, the security context is also released.

When to Implement

Implement IADsOpenDSObject only when you are providing an Active Directory implementation for your directory service. Every provider implements this interface on the ADSI Namespace object.

When to Use

Call the IADsOpenDSObject method when you are binding to an Active Directory object and need to pass a set of credentials to the directory service for permission to bind to and create this object.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADsOpenDSObject Methods | Description
OpenDSObject | Gets the IDispatch interface on the specified object.

See Also

ADSI Namespace Object, ADSI Schema Class Object, IADsClass


IADsOpenDSObject::OpenDSObject

Binds to an ADSI object using the given credentials, retrieving an IDispatch pointer on the specified object.

HRESULT IADsOpenDSObject::OpenDSObject(
  BSTR bstrDNName,       //ADsPath of the object to bind to
  BSTR bstrUserName,     //User Name to be used
  BSTR bstrPassword,     //Password to be used
  long lnReserved,       //Binding options
  IDispatch ** ppADSIObj  //Interface on an ADSI object
);

Parameter

bstrDNName
[in] ADsPath of the ADSI object.
bstrUserName
[in] The user name to be used for securing permission from the namespace server.
bstrPassword
[in] The password to be used for securing permission from the namespace server.
lnReserved
[in] Flags that define the binding options. There are two flags defined:
FLAG | Value
ADSI_USE_SECURE_AUTHENTICATION | 0x00000001
ADSI_USE_ENCRYPTION | 0x00000010

See Notes to Implementers below.

ppADSIObj
[out] Indirect pointer to an IDispatch interface on

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The IDispatch interface has been successfully retrieved using these credentials.

Remarks

To use default credentials, set bstrUserName and bstrPassword to NULL.

Notes to Implementers

The behavior of OpenDSObject when lnFlags is set is provider-specific. Namespaces that require high security may ignore these flags and always require authentication. For provider-specific details, see Microsoft Platform SDK ADSI reference section.

QuickInfo

Windows NT: Use version 4.0 Service Pack 2 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

ADSI Namespace Object, IADsOpenDSObject


IADsOU

The IADsOU interface enables a COM object in Active Directory to manage the data representing the organizational unit to which an account belongs. This interface is one of several that provide support for directory services that organize accounts by country, locality (geographical location), organization (company), and organizational unit (department).

Properties accessed by IADsOU are defined on the ADSI OrganizationalUnit Object.

When to Implement

Implement IADsOU when you are providing an Active Directory implementation for your directory service that organizes directory entries by organizational unit.

When to Use

Call the methods on this interface when you are expanding a directory that organizes accounts by physical location.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsOU Methods | Description
get/put_Description | Description of the organizational unit.
get/put_LocalityName | Physical location of the unit.
get/put_PostalAddress | Post office address of the unit.
get/put_TelephoneNumber | Telephone number of the unit.
get/put_FaxNumber | Fax number of the unit.
get/put_SeeAlso | Other information relevant to the unit.
get/put_BusinessCategory | General business functions.


IADsAccessOU Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsOU interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
BusinessCategory | R/W | HRESULT get_BusinessCategory ([out] BSTR *pbstrBusinessCategory); HRESULT put_BusinessCategory ([in] BSTR bstrBusinessCategory);
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
FaxNumber | R/W | HRESULT get_FaxNumber ([out] BSTR *pbstrFaxNumber); HRESULT put_FaxNumber ([in] BSTR bstrFaxNumber);
LocalityName | R/W | HRESULT get_LocalityName ([out] BSTR *pbstrLocalityName); HRESULT put_LocalityName ([in] BSTR bstrLocalityName);
PostalAddress | R/W | HRESULT get_PostalAddress ([out] BSTR *pbstrPostalAddress); HRESULT put_PostalAddress ([in] BSTR bstrPostalAddress);
TelephoneNumber | R/W | HRESULT get_TelephoneNumber ([out] BSTR *pbstrTelephoneNumber); HRESULT put_TelephoneNumber ([in] BSTR bstrTelephoneNumber);
SeeAlso | R/W | HRESULT get_SeeAlso ([out] BSTR *pbstrSeeAlso); HRESULT put_SeeAlso ([in] BSTR bstrSeeAlso);

Property Descriptions

BusinessCategory
Gets and sets a string indicating the general business function(s) performed by the organizational unit, for example "Accounting".
Description
Gets and sets the text that describes the locality.
FaxNumber
Gets and sets the fax number associated with the organization.
LocalityName
Gets and sets the CLSID of the code implementing the Active Directory object for this schema class.
PostalAddress
Gets and sets the main postal address of the locality.
TelephoneNumber
Gets and sets the telephone number associated with the organization.
SeeAlso
Gets and sets an array of ADsPath names of other directory objects which may be relevant to this object.

See Also

ADSI OrganizationalUnit Object


IADsPrintJob

The IADsPrintJob interface enables a COM object in Active Directory to manage general information about a print job. Use IADsPrintJobOperations for managing the print job itself across a network. The collection of print jobs managed by any one print queue is available through IADsPrintQueueOperations::PrintJobs.

Properties accessed by IADsPrintJob are defined on the ADSI PrintJob Object.

When to Implement

Implement IADsPrintJob only when you are providing an Active Directory implementation for a directory service that supports providing information about print jobs across a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

The collection of print jobs managed by any one print queue is available through the IADsPrintQueueOperations::PrintJobs method.

When to Use

Call methods on this interface to reference general information about a print job, such as the associated end-user, print queue, priority, or times.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsPrintJob Methods | Description
get_HostPrintQueue | ADsPath naming the print queue processing this print job
get_User | Name of user submitting print job.
get_UserPath | ADsPath name to user object for user submitting the print job.
get_TimeSubmitted | Time job submitted to the print queue.
get_TotalPages | Total number of pages in the print job.
get_Size | Size of the print job in bytes.
get/put_Description | Description of the print job.
get/put_Priority | Priority of the print job.
get/put_StartTime | Earliest time job should be printed.
get/put_UntilTime | Latest time job should be printed.
get/put_Notify | User to notify when job complete.
get/put_NotifyPath | ADsPath for user object of user to notify when jobis complete.


IADsPrintJob Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsPrintJob interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
HostPrintQueue | R/O | HRESULT get_HostPrintQueue ([out] BSTR *pbstrHostPrintQueue);
Notify | R/W | HRESULT get_Notify ([out] BSTR *pbstrNotify); HRESULT put_Notify ([in] BSTR bstrNotify);
NotifyPath | R/W | HRESULT get_NotifyPath ([out] BSTR *pbstrNotifyPath); HRESULT put_NotifyPath ([in] BSTR bstrNotifyPath);
Priority | R/W | HRESULT get_Priority ([out] LONG *plPriority); HRESULT put_Priority ([in] LONG lPriority);
Size | R/O | HRESULT get_Size ([out] LONG *plSize);
StartTime | R/W | HRESULT get_StartTime ([out] DATE *pdateStartTime); HRESULT put_StartTime ([in] DATE dateStartTime);
TimeSubmitted | R/O | HRESULT get_TimeSubmitted ([out] DATE *pdateTimeSubmitted);
TotalPages | R/O | HRESULT get_TotalPages ([out] LONG *plTotalPages);
UntilTime | R/W | HRESULT get_UntilTime ([out] DATE *pdateUntilTime); HRESULT put_UntilTime ([in] DATE dateUntilTime);
User | R/O | HRESULT get_User ([out] BSTR *pbstrUser);
UserPath | R/O | HRESULT get_UserPath ([out] BSTR *pbstrUserPath);

Property Descriptions

Description
Gets and sets the description of the print job.
HostPrintQueue
Gets the ADsPath string that references the Print Queue which is processing the print job.
Notify
Gets and sets the user to notify when job processing is complete.
NotifyPath
Gets and sets the ADsPath for the user object of the user to notify when job processing is complete.
Priority
Gets and sets the priority of the print job.
Size
Gets the size of the print job in bytes.
StartTime
Gets and sets the earliest time the job should be printed.
TimeSubmitted
Gets the time that the job was submitted to the queue.
TotalPages
Gets the total number of pages in the print job.
UntilTime
Gets and sets the latest time the job should be printed.
User
Gets the name of user that submitted the print job.
UserPath
Gets the ADsPath of the user object for the user that submitted this print job.

See Also

IADsPrintJobOperations, IADsPrintQueueOperations::PrintJobs, ADSI PrintQueue Object, ADSI PrintJob Object


IADsPrintJobOperations

The IADsPrintJobOperations interface enables a COM object in Active Directory to support methods that control a print job across a network.

IADsPrintJobOperations does not provide access to any properties.

When to Implement

Implement IADsPrintJobOperations only when you are providing an Active Directory implementation for a directory service that supports examining and controlling print jobs over a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

When to Use

Call the methods and properties of this interface when you are browsing through or controlling print jobs over a network.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsPrintJobOperations Properties and Methods | Description
get_Status | Status of print job.
get_TimeElapsed | Elapsed time in seconds since job started printing.
get_PagesPrinted | Number of pages completed.
get/put_Position | Numeric position of print job in print queue.
Pause | Pauses processing of this print job.
Resume | Resumes processing of this print job.


IADsPrintJobOperations Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsPrintJobOperations interface read and write the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Status | R/O | HRESULT get_Status ([out] long *plStatus);
TimeElapsed | R/O | HRESULT get_TimeElapsed ([out] long *plTimeElapsed);
PagesPrinted | R/O | HRESULT get_PagesPrinted ([out] long *plPagesPrinted);
Position | R/W | HRESULT get_Position ([out] LONG *plPosition); HRESULT put_Position ([in] LONG lPosition);

Property Descriptions

Status
Integer value indicating current status of service. The following values are defined:
Status | Hex Value
ADS_JOB_PAUSED | 0x00000001
ADS_JOB_ERROR | 0x00000002
ADS_JOB_DELETING | 0x00000004
ADS_JOB_PRINTING | 0x00000010
ADS_JOB_OFFLINE | 0x00000020
ADS_JOB_PAPEROUT | 0x00000040
ADS_JOB_PRINTED | 0x00000080
ADS_JOB_DELETED | 0x00000100

TimeElapsed
Gets the time elapsed, in seconds, since the job started printing.
PagesPrinted
Gets the number of pages complete.
Position
Gets and sets the numeric position of the job in the queue.

See Also

IADsPrintJob, IADsPrintQueue, ADSI PrintJob Object, ADSI PrintQueue Object


IADsPrintJobOperations::Pause

Temporarily halts the processing of the print job currently active. To continue the processing, use IADsPrintJobOperations::Resume.

HRESULT IADsPrintJobOperations::Pause(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The pause command was successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsPrintJobOperations::Resume, ADSI PrintJob Object


IADsPrintJobOperations::Resume

Continues the processing of the print job that was temporarily halted using the IADsPrintJobOperations::Pause method.

HRESULT IADsPrintJobOperations::Resume(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The resume command was successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsPrintJobOperations::Pause, ADSI PrintJob Object


IADsPrintQueue

The IADsPrintQueue interface enables a COM object in Active Directory to manage information about a print queue service on a network. Use IADsPrintQueueOperations methods to actually control the print queue. To list or modify the jobs in a queue, use IADsPrintQueueOperations::PrintJobs to retrieve an interface on the collection of ADSI PrintJob Objects.

Properties accessed by IADsPrintQueue are defined on the ADSI PrintQueue Object.

When to Implement

Implement IADsPrintQueue only when you are providing an Active Directory implementation for a directory service that supports print queue services on a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

When to Use

Call the methods on this interface when you are browsing through a print queue's collection of print jobs.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsPrintQueue Methods | Description
get/put_PrinterPath | Path by which a shared printer can be accessed.
get/put_Model | Name of the driver used by this print queue.
get/put_Datatype | Data type that can be processed by this print queue.
get/put_PrintProcessor | Print processor associated with this print queue.
get/put_Description | Description of this print queue.
get/put_Location | Administrator's description of print queue location.
get/put_StartTime | Time at which print queue starts processing jobs.
get/put_UntilTime | Time at which print queue stops processing jobs.
get/put_DefaultJobPriority | Default priority assigned to each print job.
get/put_Priority | Priority of this printer object's job queue for connected devices.
get/put_BannerPage | File system path to banner page file used to separate jobs.
get/put_PrintDevices | Names of print devices that this print queue uses as spooling devices.
get/put_NetAddresses | Binding information.


IADsPrintQueue Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsPrintQueue interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
BannerPage | R/W | HRESULT get_BannerPage ([out] BSTR *pbstrBannerPage); HRESULT put_BannerPage ([in] BSTR bstrBannerPage);
Datatype | R/W | HRESULT get_Datatype ([out] BSTR *pbstrDatatype); HRESULT put_Datatype ([in] BSTR bstrDatatype);
DefaultJobPriority | R/W | HRESULT get_DefaultJobPriority ([out] LONG *plDefaultJobPriority); HRESULT put_DefaultJobPriority ([in] BSTR lDefaultJobPriority);
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
HostComputer | R/W | HRESULT get_HostComputer ([out] BSTR *pbstrHostComputer); HRESULT put_HostComputer ([in] BSTR bstrHostComputer);
Location | R/W | HRESULT get_Location ([out] BSTR *pbstrLocation); HRESULT put_Location ([in] BSTR bstrLocation);
Model | R/W | HRESULT get_Model ([out] BSTR *pbstrModel); HRESULT put_Model ([in] BSTR bstrModel);
PrintDevices | R/W | HRESULT get_PrintDevices ([out] VARIANT *pvPrintDevices); HRESULT put_PrintDevices ([in] VARIANT vPrintDevices);
PrinterPath | R/W | HRESULT get_PrinterPath ([out] BSTR *pbstrPrinterPath); HRESULT put_PrinterPath ([in] BSTR bstrPrinterPath);
PrintProcessor | R/W | HRESULT get_PrintProcessor ([out] BSTR *pbstrPrintProcessor); HRESULT put_PrintProcessor ([in] BSTR bstrPrintProcessor);
Priority | R/W | HRESULT get_Priority ([out] LONG *plPriority); HRESULT put_Priority ([in] LONG lPriority);
StartTime | R/W | HRESULT get_StartTime ([out] DATE *pdateStartTime); HRESULT put_StartTime ([in] DATE dateStartTime);
UntilTime | R/W | HRESULT get_UntilTime ([out] DATE *pdateUntilTime); HRESULT put_UntilTime ([in] DATE dateUntilTime);

Property Descriptions

BannerPage
Gets and sets the file system path that points to the banner page used to separate print jobs. If NULL no banner page is used.
DataType
Gets and sets the data type that can be processed by this queue.
DefaultJobPriority
Gets and sets the default priority assigned to each print job.
Description
Gets and sets the text description of this print queue.
HostComputer
Gets and sets the ADsPath string that references the host computer.
Location
Gets and sets the location of the queue as described by an administrator.
Model
Gets and sets the name of driver used by this print queue.
PrintDevices
Gets and sets a SAFEARRAY of BSTR containing the names of the print devices to which this print queue spools jobs.
PrinterPath
Gets and sets the string that references the path by which a shared printer can be accessed.
PrintProcessor
Gets and sets the print processor associated with this queue.
Priority
Gets and sets the priority of this Printer object's job queue for any connected devices. All jobs in higher priority Print Queue objects will be processed before those in lower priority Print Queue objects.
StartTime
Gets and sets the time at which the queue should begin processing jobs. The date portion of the time is ignored.
UntilTime
Gets and sets the time at which the queue should stop processing jobs.
Non-persistent Properties accessed through IADsPrintQueueOperations Access Compiler Syntax
Status R/O HRESULT get_Status
([out] LONG *plStatus);

Status
Integer value indicating current status of service. The following values are defined:
ADS_PRINTER_PAUSED | 0x00000001
ADS_PRINTER_PENDING_DELETION | 0x00000002
ADS_PRINTER_ERROR | 0x00000003
ADS_PRINTER_PAPER_JAM | 0x00000004
ADS_PRINTER_PAPER_OUT | 0x00000005
ADS_PRINTER_MANUAL_FEED | 0x00000006
ADS_PRINTER_PAPER_PROBLEM | 0x00000007
ADS_PRINTER_OFFLINE | 0x00000008
ADS_PRINTER_IO_ACTIVE | 0x00000100
ADS_PRINTER_BUSY | 0x00000200
ADS_PRINTER_PRINTING | 0x00000400
ADS_PRINTER_OUTPUT_BIN_FULL | 0x00000800
ADS_PRINTER_NOT_AVAILABLE | 0x00001000
ADS_PRINTER_WAITING | 0x00002000
ADS_PRINTER_PROCESSING | 0x00004000
ADS_PRINTER_INITIALIZING | 0x00008000
ADS_PRINTER_WARMING_UP | 0x00010000
ADS_PRINTER_TONER_LOW | 0x00020000
ADS_PRINTER_NO_TONER | 0x00040000
ADS_PRINTER_PAGE_PUNT | 0x00080000
ADS_PRINTER_USER_INTERVENTION | 0x00100000
ADS_PRINTER_OUT_OF_MEMORY | 0x00200000
ADS_PRINTER_DOOR_OPEN | 0x00400000
ADS_PRINTER_SERVER_UNKNOWN | 0x00800000
ADS_PRINTER_POWER_SAVE | 0x01000000

See Also

IADsPrintQueueOperations, ADSI PrintQueue Object, ADSI PrintJob Object


IADsPrintQueueOperations

The IADsPrintQueueOperations interface enables a COM object in Active Directory to support properties and methods that control a print job across a network.

Properties accessed by IADsPrintQueueOperations are defined on the ADSI PrintQueue Object.

When to Implement

Implement IADsPrintQueueOperations only when you are providing an Active Directory implementation for a directory service that supports controlling print jobs over a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

When to Use

Call the methods and properties of this interface when you are examining or controlling a print job over a network.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADsPrintQueueOperations Methods | Description
get_Status | Current status of print queue service.
PrintJobs | Retrieve an interface pointer on a collection object that represents print jobs managed by this print queue.
Pause | Pause print queue processing of print jobs.
Resume | Resume print queue processing of print jobs.
Purge | Purge all jobs from a print queue.


IADsPrintQueueOperations Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsPrintQueueOperations interface read and write the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Status | R/W | HRESULT get_Name ([out] BSTR *pbstrName); HRESULT put_Name ([in] BSTR bstrName);

Property Descriptions

Status
Current status of the print queue service.

See Also

IADsPrintQueue, ADSI PrintJob Object, ADSI PrintQueue Object


IADsPrintQueueOperations::Pause

Suspends the processing of print jobs within a print queue service.

HRESULT IADsPrintQueueOperations::Pause(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The pause command was successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsPrintQueueOperations::Resume


IADsPrintQueueOperations::PrintJobs

Gets an IADsCollection interface pointer on the collection object that represents the print jobs being processed by this print queue object. This collection can be enumerated using the standard Automation enumeration methods on IEnumVARIANT. To delete a print job, use IADsCollection::Remove method on the retrieved interface pointer.

HRESULT IADsPrintQueueOperations::PrintJobs(
  IADsCollection ** ppPrintJobs  //Interface pointer on collection
                                 // of print jobs
);

Parameter

ppPrintJobs
[out] Indirect pointer to the IADsCollection interface on the collection object that includes all the ADSI PrintJob Objects that have been added to this print queue.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The IADsCollection interface pointer was successfully retrieved.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

ADsEnumerateNext, ADSI PrintJob Object, ADSI PrintQueue Object


IADsPrintQueueOperations::Purge

Empties a print queue of all print jobs without processing them.

HRESULT IADsPrintQueueOperations::Purge(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The purge command was successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.


IADsPrintQueueOperations::Resume

Resumes the processing of the print jobs within a print queue service that has previously been suspended.

HRESULT IADsPrintQueueOperations::Resume(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The resume command was successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsPrintQueueOperations::Pause


IADsProperty

The IADsProperty interface enables a COM object to manage a single property definition for a schema class object in Active Directory. IADsClass, IADsProperty, and IADsSyntax make up the interfaces available on schema management objects to view and modify definitions for the schema class objects that define a directory service, including interfaces, properties, methods, containment relationships, and provider-specific rules.

Properties accessed by IADsProperty are defined on the ADSI Property Object.

IADsProperty supports methods that describe a property by its name, syntax, value bounds, and any optional attributes that have been defined.

When to Implement

Implement IADsProperty only when you are providing an ADSI implementation for your directory service.

Note Within a schema class, property names must be unique and valid for use in name-bound operations. Although standard Active Directory practice represents all properties within a class rather than as a global list of properties, the underlying directory service may require property names to be globally unique and have consistent syntax. The provider must ensure there are no name collisions when adding new properties at creation time. Active Directory does allow multiple names for the same property.

When to Use

Call IADsProperty methods when determining at run-time what properties are supported by an ADSI schema class object. These methods are also used when adding new properties and property objects to a specific implementation of Active Directory.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsProperty Property Methods | Description
get/put_OID | Directory-specific object identifier.
get/put_Syntax | Relative path of syntax object.
get/put_MaxRange | Upper limit of values.
get/put_MinRange | Lower limit of values.
get/put_MultiValued | Whether or not this Is a multi-valued property.
Qualifiers | Optional additional provider-specific constraints on this property.


IADsProperty Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsProperty interface read and write the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
OID | R/W | HRESULT get_OID ([out] BSTR* bstrOID) HRESULT put_OID ([in ]bstr bstrOID)
Syntax | R/W | HRESULT get_Syntax ([out] BSTR* bstrSyntax) HRESULT put_Syntax ([in] BSTRbstrSyntax)
MaxRange | R/W | HRESULT get_MaxRange ([out] LONG * lnMaxRange) HRESULT put_MaxRange ([in] LONG lnMaxRange)
MinRange | R/W | HRESULT get_MinRange ([out] LONG * lnMinRange) HRESULT put_MinRange ([in] LONG lnMinRange)
MultiValued | R/W | HRESULT get_MultiValues ([out] VARIANT* fMultivalued) HRESULT put_MultiValues ([in] VARIANTfMultivalued)

Property Descriptions

OID
Directory-specific object identifier.
Syntax
Relative path of syntax object.
MaxRange
Upper limit of values.
MinRange.
Lower limit of values.
MultiValue.
Whether property is multi-valued or single-valued.

See Also

ADSI Property Object, ADSI Schema Class Object, ADSI Syntax Object


IADsProperty::Qualifiers

Optional method returning a collection of Active Directory objects describing additional qualifiers of this property.

HRESULT IADsProperty::Qualifiers(
  IADsCollection ** ppQualifiers  //Collection of additional
                                  // constraints
);

Parameter

ppQualifiers
[out] Indirect pointer to the IADsCollection interface on the ADSI collection object that represents additional limits for this property.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The IADsCollection interface pointer has been successfully retrieved.

Remarks

Active Directory implementations call this method when determining if there are any provider-specific constraints on the uses or values of this property.

Notes to Implementers

Return E_NOTIMPL if you do not support this interface.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsClass::Qualifiers


IADsPropertyEntry

The IADsPropertyEntry interface manages a property node in the property cache. .

When to Implement

Implement this interface only on a custom directory service provider. For information on how this interface is implemented on system-supplied providers, see ADSI System Providers.

When to Use

Call the methods of IADsPropertyEntry to manage individual property attributes and values. Use IADsPropertyList to manage the entire list of properties defined on an object.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods or gets/sets one of its properties.

IADsPropertyEntry Methods | Description
get/put_Name | Gets/sets the name of the property entry.
get/put_ADS_Type | Gets/sets the ADS data type of the property entry.
get/put_ControlCode | Gets/sets
get/put_Values | Gets/sets the current values of a property entry.

See Also

IADsPropertyList, IADsPropertyValue, Property Cache


IADsPropertyEntry Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsPropertyEntry interface read and write the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Name | R/W | HRESULT get_Name ([out] BSTR *pbstrName); HRESULT put_Name ([in] BSTR bstrName);
ADsType | R/W | HRESULT get_ADsType ([out] LONG *plADsType); HRESULT put_ADsType ([in] LONG lADsType);
ControlCode | R/W | HRESULT get_ControlCode ([out] LONG * pControlCode; HRESULT put_ControlCode ([in] LONG lnControlCode);
Values | R/W | HRESULT get_Values ([out] VARIANT *pvValues); HRESULT put_Values ([in] VARIANT vValues);

Property Descriptions

Name
Name of the property entry as it is in the schema.
ADsType
The data type, taken from the ADSTYPE enumeration, of the Name property.
ControlCode
One of the values from ADS_PROPERTY_* constants to indicate the operation to perform on the named property.
Values
A VARIANT array with ValueCount entries of pointers to IADsPropertyValue interfaces, each leading to an ADSI PropertyValue object that represents one value.

Return Values

Each property method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The property was successfully obtained or written.

See Also

ADSTYPE, Using Directory Service Queries , IADsPropertyList, IADsPropertyValue, Property Cache


IADsPropertyList

The IADsPropertyList interface manages a property list node in a namespace. With this interface, you can enumerate the properties in the list, add and remove properties, or purge the entire list in one step.

When to Implement

Implement this interface only on a custom directory service provider. For information on how this interface is implemented on system-supplied providers, see ADSI System Providers

When to Use

Call the methods of IADsPropertyList to manage properties as discrete entities. To manage individual property attributes and values, use the IADsPropertyEntry interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods or gets/sets one of its properties.

IADsPropertyList Methods | Description
get_PropertyCount | Gets the number of properties in the property list.
Next | Gets the next item in the property list.
Skip | Skips a specified number of items in the property list.
Reset | Specifies the current item as the first one in the property list..
Add | Adds a new property to the end of the list.
Remove | Removes a property from the list.
Item | Gets a property that is specified by name or by index.
Get/Put PropertyItem | Gets/sets the value of a named property.
ResetPropertyItem | Resets the value of a named property.
PurgePropertyList | Deletes all properties from the list.


IADsPropertyList Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsPropertyList interface read and write the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
PropertyCount | R/O | HRESULT get_PropertyCount ([out] LONG * plCount)

Property Descriptions

PropertyCount
The number of properties in the property list.

See Also

IADsPropertyEntry, IADsPropertyValue, Property Cache


IADsPropertyList::get_PropertyCount

Gets the number of items in the property list.

HRESULT get_PropertyCount(
  LONG * plCount  //Property count
);

Parameters

plCount
[out] Address of a caller-allocated variable that contains the property count.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The number of items in the property list was returned.


IADsPropertyList::Next

Gets the value of the next item in the property list.

HRESULT Next(
  VARIANT * pVariant  //Value of next item
);

Parameters

pVariant
[out] Address of a caller-allocated variable that contains the value of the next item in the property list.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The item was successfully obtained.
S_FALSE
The current item is the last one in the list. No item was obtained.


IADsPropertyList::Skip

Skips a specified number of items in the property list.

HRESULT Skip(
  ULONG cElements  //Number of elements to be skipped
);

Parameters

cElements
[in] Number of elements to be skipped. If 0, E_FAIL is returned.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The items were skipped.
S_FALSE
Skipping the number of items would exceed the length of the list. No items were skipped.


IADsPropertyList::Reset

Specifies the current item as the first one in the property list.

HRESULT Reset(void);

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The list was reset.


IADsPropertyList::Item

Gets an item from the property list.

HRESULT Item(
  VARIANT varIndex,  //Index or name of requested property
  VARIANT * pVariant //Value of requested property
);

Parameters

[in] varIndex
Index or name of the requested property.
[out] pVariant
Address of a method-allocated VARIANT variable containing the value of the property.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The item was obtained.

Remarks

The caller is responsible for freeing the VARIANT variable allocated by Item.


IADsPropertyList::GetPropertyItem

Gets an item from the property list.

HRESULT GetPropertyItem(
  BSTR bstrName,      //Name of requested item
  LONG lnADsType,     //ADSI type of the property
  VARIANT * pVariant  //Property item requested
);

Parameters

[in] bstrName
Name of the requested property.
[in] lnADsType
Type to be used in interpreting the requested property. Values are taken from the ADSTYPE enumeration.
[out] pVariant
Address of a method-allocated variant containing the requested property item. If pVariant is NULL on return, GetPropertyItem could not obtain the requested item.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The property item was successfully obtained.

Remarks

The caller is responsible for freeing the VARIANT variable allocated by GetPropertyItem.


IADsPropertyList::PutPropertyItem

Changes the value for an item in the property list.

HRESULT PutPropertyItem(
  VARIANT VarData      //Property value to be written
);

Parameters

[in] VarData
New property values to be written.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The value was written to the property list.


IADsPropertyList::ResetPropertyItem

Resets value of item in property list to original value.

HRESULT ResetPropertyItem(
..VARIANT VarEntry       //Property entry to be reset
);

Parameters

[in] VarData
Entry to be reset.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The value was written to the property list.


IADsPropertyList::PurgePropertyList

Deletes all items from the property list.

HRESULT PurgePropertyList(void);

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The property list was purged.


IADsPropertyValue

The IADsPropertyValue interface enables directory service clients to set or retrieve the value of each property entry in an ADSI property cache.

When to Implement

Implement this interface only on a custom directory service provider. For information on how this interface is implemented on system-supplied providers, see ADSI System Providers.

When to Use

Call the methods of IADsPropertyValue to read or write the value of each individual entry in an ADSI property cache. To manage entire entries, call IADsPropertyEntry. To manage the entire set of entries in a property cache, call IADsPropertyList.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods or gets/sets one of its properties.

IADsPropertyValue Methods | Description
Clear | Clears the PropertyValue object's current value.
get/put_ADsType | Gets/sets a property value's data type.
get/put_DNString | Gets/sets an object's distinguished name (pathname).
get/put_CaseExactString | Gets/sets the value of a case-sensitive string.
get/put_CaseIgnoreString | Gets/sets the value of a case-insensitive string.
get/put_PrintableString | Gets/sets the value of a printable string.
get/put_NumericString | Gets/sets the value of a string consisting of numeric characters.
get/put_Boolean | Gets/sets a Boolean value.
get/put_Integer | Gets/sets an integer value.
get/put_OctetString | Gets/sets the value of a string of eight-bit characters.
get/put_SecurityDescriptor | Gets/sets a security descriptor.
get/put_LargeInteger | Gets/sets a large-integer value.
get/put_UTCTime | Gets/sets a Coordinated Universal Time value.

See Also

ADSI PropertyValue Object; IADsPropertyEntry, IADsPropertyList, Property Cache


IADsPropertyValue Property Methods

Properties in Vtable Order

Property | Access | Method Prototype
ADSType | R/W | HRESULT get_ADSType ([out] LONG *ADSTypel) HRESULT put_ADSType ([in] LONG ADSType);
DNString | R/W | HRESULT get_DNString ([out] BSTR *bstrDNString); HRESULT put_DNString ([in] BSTR bstrDNString);
CaseExactString | R/W | HRESULT get_CaseExactString ([out] BSTR *bstrCaseExactString); HRESULT put_CaseExactString ([in] BSTR bstrCaseExactString);
CaseIgnoreString | R/W | HRESULT get_CaseIgnoreString ([out] BSTR *bstrCaseIgnoreString); HRESULT put_CaseIgnoreString ([in] BSTR bstrCaseIgnoreString);
PrintableString | R/W | HRESULT get_PrintableString ([out] BSTR *bstrPrintableStrin); HRESULT put_PrintableString ([in] BSTR bstrPrintableString)
NumericString | R/W | HRESULT get_NumericString ([out] BSTR *bstrNumericStrin); HRESULT put_NumericString ([in] BSTR bstrNumericString)
Boolean | R/W | HRESULT get_Boolean ([out] LONG *lnBoolean); HRESULT put_Boolean ([in] LONG lnBoolean)
Integer | R/W | HRESULT get_Integer ([out] LONG *lnInteger); HRESULT put_Integer ([in] LONG lnInteger)
OctetString | R/W | HRESULT get_OctetString ([out] BSTR *bstrOctetString); HRESULT put_OctetString ([in] BSTR *bstrOctetString)
SecurityDescriptor | R/W | HRESULT get_SecurityDescriptor ([out] IDISPATCH **ppSecurityDescriptor); HRESULT put_SecurityDescriptor ([in] IDISPATCH *pSecurityDescriptor);
LargeInteger | R/W | HRESULT get_LargeInteger ([out] IDISPATCH ** ppLargeInteger) HRESULT put_LargeInteger ([in] IDISPATCH * pLargeInteger
UTCTime | R/W | HRESULT get_UTCTime ([out] DATE * daUTCTime HRESULT put_UTCTime ([in] DATE daUTCTime)

Property Descriptions

ADSType
The data type of the value of the property, taken from the ADSTYPE enumeration, of the value property.
DNString
String identifying the distinguished name (path) of a directory service value object.
CaseExactString
String to be interpreted case-sensitively
CaseIgnoreString
String to be interpreted without regard to case.
PrintableString
Displayable or printable string.
NumericString
Numerals to be interpreted as text.
Boolean
Boolean value.
Integer
Integer value.
Octet String
String of one-byte characters.
SecurityDescriptor
Pointer to the IADsSecurityDescriptor interface.
LargeInteger
Pointer to the IDispatch interface.
UTCTime
A date expressed in Coordinated Universal Time (UTC) format.

See Also

ADSTYPE; IADsPropertyList; IADsPropertyEntry; IADsSecurityDescriptor, Property Cache


IADsResource

The IADsResource interface enables a COM object in Active Directory to manage information about a specific open resource in use by a file service, usually over a network.

Properties accessed by IADsResource are defined on the ADSI Resource Object.

When to Implement

Implement IADsResource only when you are providing an Active Directory implementation for a directory service that supports managing open resources over a network for a file service. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

When to Use

Call the methods on this interface when you are referencing information about a currently open resource.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsResource Properties | Description
get_User | Name of user for the Resource.
get_UserPath | ADsPath of user object for the user who opened the resource.
get_Path | File system path of opened resource.
get_LockCount | Number of locks on the resource.


IADsResource Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsResource interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
LockCount | R/O | HRESULT get_LockCount ([out] LONG *plLockCount);
Path | R/O | HRESULT get_Path ([out] BSTR *pbstrPath);
User | R/O | HRESULT get_User ([out] BSTR *pbstrUser);
UserPath | R/O | HRESULT get_UserPath ([out] BSTR *pbstrUserPath);

Property Descriptions

LockCount
Gets the number of locks on the resource.
Path
Gets the file system path of the opened resource.
User
Gets the name of user who opened the resource.
UserPath
Gets the ADsPath of the user object for the user who opened the resource.

See Also

IADsFileServiceOperations::Resources, ADSI Resource Object


IADsSecurityDescriptor

The IADsSecurityDescriptor interface provides access to properties on an ADSI security descriptor object. The IADsSecurityDescriptor interface also provides a method for copying a security descriptor.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods or gets/sets one of its properties.

IADsSecurityDescriptor Methods | Description
get/put_Revision | Gets/puts the revision number assigned to the security descriptor.
get/put_Control | Gets/puts the Security_Descriptor_Control flag.
get/put_Owner | Gets/puts the owner of the object associated with the security descriptor.
get/put_OwnerDefaulted | TBD
get/put_Group | Gets/puts the group that owns the object associated with the security descriptor.
get/put_GroupDefaulted | TBD
get/put_DiscretionaryAclt | Gets/puts the discretionary ACL associated with the security descriptor.
get/put_DaclDefaulted | TBD
get/put_SystemAcl | Gets/puts the system ACL associated with the security descriptor.
get/put_SaclDefaulted | TBD
CopySecurityDescriptor | Copies the security descriptor.

See Also

IADsAccessControlEntry, IADsAccessControlList, ADSI AccessControlList Object, Using Credentials and Security


IADsSecurityDescriptor Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsSecurityDescriptor interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Revision | R/W | HRESULT get_Revision ([out] LONG *plRevision); HRESULT put_Revision ([in]LONG lRevision)
Control | R/W | HRESULT get_Control ([out] LONG *plControl); HRESULT put_Control ([in] LONG lControl)
Owner | R/W | HRESULT get_Owner ([out] BSTR *pbstrOwnerl); HRESULT put_Owner ([in] BSTR bstrOwner)
OwnerDefaulted | R/W | HRESULT get_OwnerDefaulted ([out] VARIANT_BOOL * fOwnerDefaulted); HRESULT put_OwnerDefaulted ([in] VARIANT_BOOL fOwnerDefaulted)
Group | R/W | HRESULT get_Group(BSTR *pbstrGroupl); HRESULT put_Group(BSTR bstrGroup)
GroupDefaulted |  | HRESULT get_GroupDefaulted ([out] VARIANT_BOOL * fGroupDefaulted); HRESULT put_GroupDefaulted ([out] VARIANT_BOOL fGroupDefaulted);
DiscretionaryAcl | R/W | HRESULT get_DiscretionaryAcl ([out] IDispatch **ppIDispDACL) HRESULT put_DiscretionaryAcl ([in] IDispatch *pIDispDACL)
DaclDefaulted |  | HRESULT get_DaclDefaulted ([out] VARIANT_BOOL * fDaclDefaulted); HRESULT put_DaclDefaulted ([out] VARIANT_BOOL fDaclDefaulted);
SystemAcl | R/W * | HRESULT get_SystemAcl ([out] IDispatch **ppIDispSACL) HRESULT put_SystemAcl ([in] IDispatch *pIDispSACL)
SaclDefaulted |  | HRESULT get_SaclDefaulted ([out] VARIANT_BOOL * fSaclDefaulted); HRESULT put_SaclDefaulted ([out] VARIANT_BOOL fSaclDefaulted);

Property Descriptions

Revision
Revision level of the security descriptor. This value is taken from the Win32 ACL_REVISION_INFORMATION structure. All ACEs in an ACL must be at the same revision level.
Control
Flags that qualify the meaning of the security descriptor. Values are taken from the Win32 SECURITY_DESCRIPTOR_CONTROL structure.
Owner
Owner of the object.
OwnerDefaulted
TBD
Group
Group to which the owner's security ID belongs.
GroupDefaulted
TBD
DiscretionaryAcl
Discretionary access control list that specifies types of access allowed to the object for specified users and groups.
DaclDefaulted
TBD
SystemAcl
System access control list used to generate audit records for the object.
SaclDefaulted
TBD

See Also

IADsAccessControlEntry, IADsAccessControlList, ADSI AccessControlList Object, Using Credentials and Security


IADsSecurityDescriptor::CopySecurityDescriptor

Copies an ADSI security descriptor object, which provides security information about an object.

HRESULT CopySecurityDescriptor(
  IDispatch ** ppSecurityDescriptor  //
);

Parameters

[out] ppSecurityDescriptor
Pointer to a security descriptor object.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK

See Also

IADsAccessControlEntry, IADsAccessControlList, ADSI AccessControlList Object, Using Credentials and Security


IADsService

The IADsService interface enables a COM object in Active Directory to manage the information stored in the underlying directory service describing a software service provided by a specific computer. For managing aspects of the service that are not persistently stored, such as controlling the service over the network, use IADsServiceOperations methods. For software services that are specifically file services, use the similarly designed IADsFileService and IADsFileServiceOperations interfaces.

Properties accessed by IADsService are defined on the ADSI Service Object.

When to Implement

Implement IADsService only when you are providing an Active Directory implementation for a directory service that publishes the availability of services on a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

Under the Windows NT implementation, this interface is implemented on an WinNTService object.

When to Use

Call the methods and properties of this interface when you are managing information describing a software service available through a network.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsService Properties and Methods | Description
get/put_HostComputer | Host of this service.
get/put_DisplayName | Display name of this service.
get/put_Version | Version of this service.
get/put_ServiceType | Process type in which this service runs.
get/put_StartType | At what time this service starts.
get/put_Path | Path and filename of executable.
get/put_StartupParameters | Parameters passed on start-up.
get/put_ErrorControl | Actions for service failure.
get/put_LoadOrderGroup | The load order group for this service.
get/put_ServiceAccountName | Authentication account name.
get/put_ServiceAccountPath | Path to user object for authentication.
get/put_Dependencies | Other load groups or services this service needs.


IADsService Property Methods

The methods of the IADsService interface read and write the properties described in this topic. For more information see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Dependencies | R/W | HRESULT get_Dependencies ([out] VARIANT *pvServiceDepend); HRESULT put_Dependencies ([in] VARIANT vServiceDepend);
DisplayName | R/W | HRESULT get_DisplayName ([out] BSTR *pbstrDisplayName); HRESULT put_DisplayName ([in] BSTR bstrDisplayName);
ErrorControl | R/W | HRESULT get_ErrorControl ([out] LONG *plErrorControl); HRESULT put_ErrorControl ([in] LONG lErrorControl);
HostComputer | R/W | HRESULT get_HostComputer ([out] BSTR *pbstrHostComputer); HRESULT put_HostComputer ([in] BSTR bstrHostComputer);
LoadOrderGroup | R/W | HRESULT get_LoadOrderGroup ([out] BSTR *pbstrLoadOrderGroup); HRESULT put_LoadOrderGroup ([in] BSTR bstrLoadOrderGroup);
Path | R/W | HRESULT get_Path ([out] BSTR *pbstrPath); HRESULT put_Path ([in] BSTR bstrPath);
ServiceAccountName | R/W | HRESULT get_ServiceAccountName ([out] BSTR *pbstrServiceAccountName); HRESULT put_ServiceAccountName ([in] BSTR bstrServiceAccountName);
ServiceAccountPath | R/W | HRESULT get_ServiceAccountPath ([out] BSTR *pbstrServiceAccountPath); HRESULT put_ServiceAccountPath ([in] BSTR bstrServiceAccountPath);
ServiceType | R/W | HRESULT get_ServiceType ([out] LONG *plServiceType); HRESULT put_ServiceType ([in] LONG lServiceType);
StartType | R/W | HRESULT get_StartType ([out] LONG *plStartType); HRESULT put_StartType ([in] LONG lStartType);
StartupParameters | R/W | HRESULT get_StartupParameters ([out] BSTR *pbstrStartupParameters); HRESULT put_StartupParameters ([in] BSTR bstrStartupParameters);
Version | R/W | HRESULT get_Version ([out] BSTR *pbstrVersion); HRESULT put_Version ([in] BSTR bstrVersion);

Property Descriptions

Dependencies
Array of BSTR names of services or load groups that must be loaded in order for this service to load. The syntax for the entry is "Service:" followed by the service name or "Group:" followed by the load group name.
DisplayName
Gets and sets the friendly display name of the service.
ErrorControl
Gets and sets what action that should be taken if this service fails on startup. Valid values are:
ADS_SERVICE_ERROR_IGNORE | 0x00000000
ADS_SERVICE_ERROR_NORMAL | 0x00000001
ADS_SERVICE_ERROR_SEVERE | 0x00000002
ADS_SERVICE_ERROR_CRITICAL | 0x00000003

HostComputer
Gets and sets the ADsPath string of the host of this service.
LoadOrderGroup
Name of the load order group that this service is a member of.
Path
Path and filename to the executable of this service.
ServiceAccountName
Name of the account that this service uses to authenticate itself on startup.
ServiceType
Gets and sets the description of how a service manifests itself on the host computer. ServiceType is a bit mask that can contain the logical OR of the supported service type constant values. Valid values are:·
ADS_SERVICE_KERNEL_DRIVER | 0x00000001
ADS_SERVICE_FILE_SYSTEM_DRIVER | 0x00000002
ADS_SERVICE_OWN_PROCESS | 0x00000010
ADS_SERVICE_SHARE_PROCESS | 0x00000020

StartType
Gets and sets when this service starts. Valid values are defined by referencing the Win32 SERVICE_XXX constants and are as follows:
ADS_SERVICE_BOOT_START
SERVICE_BOOT_START
ADS_SERVICE_SYSTEM_START
SERVICE_SYSTEM_START
ADS_SERVICE_AUTO_START
SERVICE_AUTO_START
ADS_SERVICE_DEMAND_START
SERVICE_DEMAND_START
ADS_SERVICE_DISABLED
SERVICE_DISABLED
StartupParameters
Parameters passed to the service on startup.
Version
Gets and sets the version of the service.
Property Access Method Prototype
Status R/O HRESULT get_Status
([out] LONG *plStatus);

Property Descriptions

Status
The service status. Values can be:
ADS_SERVICE_STOPPED | 0X00000001
ADS_SERVICE_START_PENDING | 0X00000002
ADS_SERVICE_STOP_PENDING | 0x00000003
ADS_SERVICE_STOP_RUNNING | 0x00000004
ADS_SERVICE_CONTINUE_PENDING | 0x00000005
ADS_SERVICE_PAUSE_PENDING | 0x00000006
ADS_SERVICE_PAUSED | 0x00000007
ADS_SERVICE_ERROR | 0x00000008

See Also

IADsFileService, IADsFileServiceOperations, IADsServiceOperations, ADSI Service Object


IADsServiceOperations

The IADsServiceOperations interface enables a COM object in Active Directory to manage the information that is not stored in the underlying directory service for a software service provided by a specific computer. For managing service information that is persistently stored, use IADsService properties and methods. For software services that are specifically file services, use the similarly designed IADsFileServiceOperations and IADsFileService interfaces.

Properties accessed by IADsServiceOperations are defined on the ADSI Service Object.

When to Implement

Implement IADsServiceOperations only when you are providing an Active Directory implementation for a directory service that supports controlling software services over a network. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

When to Use

Call the methods and properties of this interface when you are managing the password or controlling a software service available on your network.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsServiceOperations Properties and Methods | Description
get_Status | Gets the status of the service.
Start | Start the service.
Stop | Stop the service.
Pause | Pause the service.
Continue | Continue the service.
SetPassword | Sets password to be used by service manager to create security context.


IADsServiceOperations Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsServiceOperations interface read and write the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Status | R/O | HRESULT get_Status ([out] LONG * pstatus)

Property Descriptions

Status
Status of service.

See Also

IADsFileService, IADsFileServiceOperations, IADsService, ADSI Service Object


IADsServiceOperations::Continue

Resumes a service that has been halted with the IADsServiceOperations::Pause method.

HRESULT IADsServiceOperations::Continue(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The continue command has been successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsService, ADSI Service Object


IADsServiceOperations::Pause

Pauses a service that has been started with the IADsServiceOperations::Start method.

HRESULT IADsServiceOperations::Pause(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The pause command has been successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsService, ADSI Service Object


IADsServiceOperations::SetPassword

Sets the password for the account used by the service manager when creating the security context for this service.

HRESULT IADsServiceOperations::SetPassword(
  BSTR bstrNewPassword  //The new password.
);

Parameter

bstrNewPassword
[in] The password to be stored as the new password.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The SetPassword command has been successfully issued.

Remarks

The property IADsService::get_ServiceAccountName identifies the account for which this password is to be set.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsService, ADSI Service Object


IADsServiceOperations::Start

Starts a service published and currently available on the network.

HRESULT IADsServiceOperations::Start(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The start command has been successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsService, ADSI Service Object


IADsServiceOperations::Stop

Stops a currently active service on the network.

HRESULT IADsServiceOperations::Stop(void);

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The stop command has been successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsService, ADSI Service Object


IADsSession

The IADsSession interface enables a COM object in Active Directory to manage the information describing a connected session on a file service over a network.

Properties accessed by IADsSession are defined on the ADSI Session Object.

When to Implement

Implement IADsSession only when you are providing an Active Directory implementation for a directory service that represents open sessions across a network for a file service. If your directory service does not support this functionality, return E_NOTIMPL for this interface.

Under the Windows NT implementation, this interface is implemented on a dependent ADSI Session Object.

When to Use

Call the methods and properties of this interface when you are managing data the connected sessions of a software file service available through a network.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsSession Methods | Description
get_User | Name of user for the session.
get_UserPath | ADsPath of the user object for the user.
get_Computer | Name of client workstation.
get_ComputerPath | ADsPath of computer object for client workstation.
get_ConnectTime | Number of minutes since session start.
get_IdleTime | Number of minutes session has been idle.


IADsSession Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsSession interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
Computer | R/O | HRESULT get_Computer ([out] BSTR *pbstrComputer);
ComputerPath | R/O | HRESULT get_ComputerPath ([out] BSTR *pbstrComputerPath);
ConnectTime | R/O | HRESULT get_ConnectTime ([out] LONG *plConnectTime);
IdleTime | R/O | HRESULT get_IdleTime ([out] LONG *plIdleTime);
User | R/O | HRESULT get_User ([out] BSTR *pbstrUser);
UserPath | R/O | HRESULT get_UserPath ([out] BSTR *pbstrUserPath);

Property Descriptions

Computer
Gets the name of the client workstation.
ComputerPath
Gets the ADsPath of the computer object for the client workstation.
ConnectTime
Gets the number of minutes that have elapsed since the session started.
IdleTime
Gets the idle time of the session, in minutes.
User
Gets the name of the user of the session.
UserPath
Gets the ADsPath of the user object for the user of this session.

See Also

IADsFileServiceOperations::Sessions, ADSI Session Object


IADsSyntax

The IADsSyntax interface enables a COM object to identify which syntax among the available Automation Virtual Types its data represents. Active Directory defines a standard set of syntax objects that can be used uniformly across multiple directory service implementations. IADsClass, IADsProperty, and IADsSyntax make up the interfaces available on schema management objects to view and modify definitions for the schema class objects that define a directory service, including interfaces, properties, methods, containment relationships, and provider-specific rules.

Properties accessed by IADsSyntax, as well as the standard ADSI syntax objects, are defined on ADSI Syntax Object.

When to Implement

Implement IADsSyntax only when you are providing an Active Directory implementation for your directory service. Every provider must implement this interface. If you have a syntax that cannot be directly mapped to a VARTYPE supported by Active Directory, use an array of unsigned bytes (VT_UI1|VT_ARRAY).

Automation Data Types supported by Active Directory are:

When to Use

Call the IADsSyntax methods when you are processing the property values of any ADSI schema class object instance.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsSyntax Properties | Description
get/put_OleAutoDataType | The Automation virtual type constant, VT_xxxx.


IADsSyntax Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsSyntax interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
OleAutoDataType | R/W | HRESULT get_OleAutoDataType ([out] LONG *plAutoDataType); HRESULT put_OleAutoDataType ([in] LONG lAutoDataType);

Property Descriptions

OleAutoDataType
Gets and sets a long containing the value of the VT_xxx constant for the Automation Virtual Type representing this syntax.

Notes to Implementers

Provider syntaxes that cannot be mapped to an Automation Virtual Type should be mapped to an array of unsigned bytes, VT_UI1|VT_ARRAY.

See Also

ADSI Property Object, ADSI Schema Class Object, ADSI Syntax Object


IADsUser

The IADsUser interface enables a COM object in Active Directory to manage information that represents an end-user account on a network.

Properties accessed by IADsUser are defined on the ADSI User Object.

When to Implement

Implement IADsUser only when you are providing an Active Directory implementation for a directory service.

When to Use

Call the methods on this interface when you are referencing information about an end-user account. This occurs for applications from as simple as creating address books to complex network administration programs that monitor bad password attempts.

Methods in VTable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDispatch Methods | Description
GetTypeInfoCount | Gets the number of type descriptions.
GetTypeInfo | Gets a description of object's programmable interface.
GetIDsOfNames | Maps name of method or property to DISPID.
Invoke | Calls one of the object's methods, or gets/sets one of its properties.

IADs Properties and Methods | Description
get_Name | Gets the object's relative name.
get_Class | Gets the object's schema class name.
get_GUID | Gets the object's globally unique identifier.
get_ADsPath | Gets the object's ADsPath that uniquely identifies this object from all others.
get_Parent | Gets the object's ADsPath string for its parent container.
get_Schema | Gets the ADsPath string to the schema class definition object for this object.
GetInfo | Reloads the changes on this object and its dependents.
SetInfo | Saves the changes on this object and its dependents.
Get | Gets the value for a property by name.
Put | Sets the value for a property by name.
GetEx | Gets the value for a single or multi-valued property by name.
PutEx | Sets the value for a single or multi-valued property by name.
GetInfoEx | Reloads specific property values for this object as they exist in the underlying directory service.

IADsUser Properties | Description
get_BadLoginAddress | Address of last node considered an "Intruder"
get_BadLoginCount | Number of bad logon attempts since last reset.
get_LastLogin | Date and time of last network login.
get_LastLogoff | Date and time of last network logoff.
get_LastFailedLogin | Date and time of last failed network login.
get_PasswordLastChanged | Date and time of last password change.
get/put_Description | Description of the user account.
get/put_Division | Gets and sets the division within a company (organization).
get/put_Department | Organizational unit within the organization.
get/put_EmployeeID | End-user's employee identification.
get/put_FullName | End-user's full name.
get/put_FirstName | End-user's first name.
get/put_LastName | End-user's last name.
get/put_OtherName | End-user's additional name.(nickname, middle name)
get/put_NamePrefix | End-user's prefix (Mr. Ms., Hon.)
get/put_NameSuffix | End-user's suffix (Jr., III).
get/put_Title | End-user's title within the organization.
get/put_Manager | End-user's manager.
get/put_TelephoneHome | End-user's list of home phone numbers.
get/put_TelephoneMobile | End-user's list of mobile phone numbers.
get/put_TelephoneNumber | End-user's list of work-related phone numbers.
get/put_TelephonePager | End-user's list of pager phone numbers.
get/put_FaxNumber | End-user's list of fax phone numbers.
get/put_OfficeLocations | Array of end-user locations.
get/put_PostalAddresses | Array of end-user post office addresses.
get/put_PostalCodes | Array of zip codes for the Postal Addresses.
get/put_SeeAlso | Array of ADsPaths of other objects related to this user.
get/put_AccountDisabled | Whether or not the account is disabled.
get/put_AccountExpirationDate | Date and time after which user cannot log in.
get/put_GraceLoginsAllowed | Number of times user can log on after password has expired.
get/put_GraceLoginsRemaining | Number of grace logins left before locking account.
get/put_IsAccountLocked | Whether or not account is locked.
get/put_LoginHours | Time periods during each day of week indicating valid login periods.
get/put_LoginWorkstations | Workstations and their net addresses for this end-user.
get/put_MaxLogins | Maximum number of simultaneous logins.
get/put_MaxStorage | Maximum amount of disk space allowed.
get/put_PasswordExpirationDate | Date and time when password will expire.
get/put_PasswordMinimumLength | Minimum number of characters allowed in a password.
get/put_PasswordRequired | Whether or not password is required.
get/put_RequireUniquePassword | Whether or not new password must be different than one in the password history list.
get/put_EmailAddress | End-user's email address.
get/put_HomeDirectory | End-user's home directory.
get/put_Languages | Array of language names for the end-user.
get/put_Profile | End-user's profile path.
get/put_LoginScript | End-user's logon script path.
get/put_Picture | Array of bytes with the end-user's an image.
get/put_HomePage | End-user's URL defining a home page.
Groups | Determining the groups to which this end-user belongs.
SetPassword | Sets the password.
ChangePassword | Changes password from specified old value to a new value.


IADsUser Property Methods

Property methods take the form of either get_<property> or put_<property>. The property methods of the IADsUser interface get or set the properties described below. For more information, see Interface Property Methods.

Properties in Vtable Order

Property | Access | Method Prototype
AccountDisabled | R/W | HRESULT get_AccountDisabled ([out] BOOLEAN *pbAccountDisabled); HRESULT put_AccountDisabled ([in] BOOLEAN bAccountDisabled);
AccountExpirationDate | R/W | HRESULT get_AccountExpirationDate ([out] DATE *pdateAccountExpirationDate); HRESULT put_AccountExpirationDate ([in] DATE dateAccountExpirationDate);
BadLoginAddress | R/O | HRESULT get_BadLoginAddress ([out] BSTR *pbstrBadLoginAddress);
BadLoginCount | R/O | HRESULT get_BadLoginCount ([out] LONG *plBadLoginCount);
Department | R/W | HRESULT get_Department ([out] BSTR *pbstrDepartment); HRESULT put_Department ([in] BSTR bstrDepartment);
DepartmentNumber | R/W | HRESULT get_DepartmentNumber ([out] BSTR *pbstrDepartmentNumber); HRESULT put_DepartmentNumber ([in] BSTR bstrDepartmentNumber);
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
Division | R/W | HRESULT get_Division ([out] BSTR *pbstrDivision); HRESULT put_Division ([in] BSTR bstrDivision);
EmailAddress | R/W | HRESULT get_EmailAddress ([out] BSTR *pbstrEmailAddress); HRESULT put_EmailAddress ([in] BSTR bstrEmailAddress);
EmployeeID | R/W | HRESULT get_EmployeeID ([out] BSTR *pbstrEmployeeID); HRESULT put_EmployeeID ([in] BSTR bstrEmployeeID);
FaxNumber | R/W | HRESULT get_FaxNumber ([out] VARIANT *pvarFaxNumber); HRESULT put_FaxNumber ([in] VARIANT varFaxNumber);
FirstName | R/W | HRESULT get_FirstName ([out] BSTR *pbstrFirstName); HRESULT put_FirstName ([in] BSTR bstrFirstName);
FullName | R/W | HRESULT get_FullName ([out] BSTR *pbstrFullName); HRESULT put_FullName ([in] BSTR bstrFullName);
GraceLoginsAllowed | R/W | HRESULT get_GraceLoginsAllowed ([out] LONG *plGraceLoginsAllowed); HRESULT put_GraceLoginsAllowed ([in] LONG lGraceLoginsAllowed);
GraceLoginsRemaining | R/W | HRESULT get_GraceLoginsRemaining ([out] LONG *plGraceLoginsRemaining); HRESULT put_GraceLoginsRemaining ([in] LONG lGraceLoginsRemaining);
HomeDirectory | R/W | HRESULT get_HomeDirectory ([out] BSTR *pbstrHomeDirectory); HRESULT put_HomeDirectory ([in] BSTR bstrHomeDirectory);
HomePage | R/W | HRESULT get_HomePage ([out] BSTR *pbstrHomePage); HRESULT put_HomePage ([in] BSTR bstrHomePage);
IsAccountLocked | R/W | HRESULT get_IsAccountLocked ([out] BOOLEAN *pbIsAccountLocked); HRESULT put_IsAccountLocked ([in] BOOLEAN bIsAccountLocked);
Languages | R/W | HRESULT get_Languages ([out] VARIANT *pvLanguages); HRESULT put_Languages ([in] VARIANT vLanguages);
LastFailedLogin | R/O | HRESULT get_LastFailedLogin ([out] DATE *pdateLastFailedLogin);
LastLogin | R/O | HRESULT get_LastLogin ([out] DATE *pdateLastLogin);
LastLogoff | R/O | HRESULT get_LastLogoff ([out] DATE *pdateLastLogoff);
LastName | R/W | HRESULT get_LastName ([out] BSTR *pbstrLastName); HRESULT put_LastName ([in] BSTR bstrLastName);
LoginHours | R/W | HRESULT get_LoginHours ([out] VARIANT *pvLoginHours); HRESULT put_LoginHours ([in] VARIANT vLoginHours);
LoginScript | R/W | HRESULT get_LoginScript ([out] BSTR *pbstrLoginScript); HRESULT put_LoginScript ([in] BSTR bstrLoginScript);
LoginWorkstations | R/W | HRESULT get_LoginWorkstations ([out] VARIANT *pvLoginWorkstations); HRESULT put_LoginWorkstations ([in] VARIANT vLoginWorkstations);
Manager | R/W | HRESULT get_Manager ([out] BSTR *pbstrManager); HRESULT put_Manager ([in] BSTR bstrManager);
MaxLogins | R/W | HRESULT get_MaxLogins ([out] LONG *plMaxLogins); HRESULT put_MaxLogins ([in] LONG lMaxLogins);
MaxStorage | R/W | HRESULT get_MaxStorage ([out] LONG *plMaxStorage); HRESULT put_MaxStorage ([in] LONG lMaxStorage);
NamePrefix | R/W | HRESULT get_NamePrefix ([out] BSTR *pbstrNamePrefix); HRESULT put_NamePrefix ([in] BSTR bstrNamePrefix);
NameSuffix | R/W | HRESULT get_NameSuffix ([out] BSTR *pbstrNameSuffix); HRESULT put_NameSuffix ([in] BSTR bstrNameSuffix);
OfficeLocations | R/W | HRESULT get_OfficeLocations ([out] VARIANT *pvOfficeLocations); HRESULT put_OfficeLocations ([in] VARIANT vOfficeLocations);
OtherName | R/W | HRESULT get_OtherName ([out] BSTR *pbstrOtherName); HRESULT put_OtherName ([in] BSTR bstrOtherName);
PasswordExpirationDate | R/W | HRESULT get_PasswordExpirationDate ([out] DATE *pdatePasswordExpirationDate); HRESULT put_PasswordExpirationDate ([in] DATE datePasswordExpirationDate);
PasswordLastChanged | R/O | HRESULT get_PasswordLastChanged ([out] DATE *pdatePasswordLastChanged);
PasswordMinimumLength | R/W | HRESULT get_PasswordMinimumLength ([out] LONG *plPasswordMinimumLength); HRESULT put_PasswordMinimumLength ([in] LONG lPasswordMinimumLength);
PasswordRequired | R/W | HRESULT get_PasswordRequired ([out] BOOLEAN *plPasswordRequired); HRESULT put_PasswordRequired ([in] BOOLEAN lPasswordRequired);
Picture | R/W | HRESULT get_Picture ([out] VARIANT *pvarPicture); HRESULT put_Picture ([in] VARIANT varPicture);
PostalAddresses | R/W | HRESULT get_PostalAddresses ([out] VARIANT *pvPostalAddresses); HRESULT put_PostalAddresses ([in] VARIANT vPostalAddresses);
PostalCodes | R/W | HRESULT get_PostalCodes ([out] VARIANT *pvPostalCodes); HRESULT put_PostalCodes ([in] VARIANT vPostalCodes);
Profile | R/W | HRESULT get_Profile ([out] BSTR *pbstrProfile); HRESULT put_Profile ([in] BSTR bstrProfile);
RequireUniquePassword | R/W | HRESULT get_RequireUniquePassword ([out] BOOLEAN *plRequireUniquePassword); HRESULT put_RequireUniquePassword ([in] BOOLEAN lRequireUniquePassword);
SeeAlso | R/W | HRESULT get_SeeAlso ([out] VARIANT *pvSeeAlso); HRESULT put_SeeAlso ([in] VARIANT vSeeAlso);
TelephoneHome | R/W | HRESULT get_TelephoneHome ([out] VARIANT *pvarTelephoneHome); HRESULT put_TelephoneHome ([in] VARIANT varTelephoneHome);
TelephoneMobile | R/W | HRESULT get_TelephoneMobile ([out] VARIANT *pvarTelephoneMobile ); HRESULT put_TelephoneMobile ([in] VARIANT varTelephoneMobile );
TelephoneNumber | R/W | HRESULT get_TelephoneNumber ([out] VARIANT *pvarTelephoneNumber); HRESULT put_TelephoneNumber ([in] VARIANT varTelephoneNumber);
TelephonePager | R/W | HRESULT get_TelephonePager ([out] VARIANT *pvarTelephonePager); HRESULT put_TelephonePager ([in] VARIANT varTelephonePager);
Title | R/W | HRESULT get_Title ([out] BSTR *pbstrTitle); HRESULT put_Title ([in] BSTR bstrTitle);

Property Descriptions

AccountDisabled
Gets and sets if the account is or should be disabled.
AccountExpirationDate
Gets and sets the date and time after which the user cannot log in.
BadLoginAddress
Gets the address of last node that is considered an Intruder (kept if Intruder detection is active).
BadLoginCount
If Intruder detection is active, gets the number of bad logon attempts since the last reset time.
Department
Gets and sets the department (OU or Organizational Unit) within the company to which the user belongs.
DepartmentNumber
Gets and sets department's charge number.
Description
Gets and sets the text description of the user.
Division
Gets and sets the division within a company (Organization).
EmailAddress
Gets and sets the user's e-mail address.
EmployeeID
Gets and sets the user's employee ID.
FaxNumber
Gets and sets the user's fax number.
FirstName
Gets and sets the user's first name.
FullName
Gets and sets the user's full name.
GraceLoginsAllowed
Gets and sets the number of times the user can log on after the password has expired.
GraceLoginsRemaining
Gets and sets how many grace logons are left before the account is locked.
HomeDirectory
Gets and sets the user's home directory.
HomePage
Gets and sets a string containing the URL of a home page for this user.
IsAccountLocked
Gets and sets if account is locked because of intruder detection.
Languages
Gets and sets an array of BSTR language names for the user.
LastName
Gets and sets the user's last name.
LoginHours
Gets and sets time periods for each day of the week during which logons are permitted for the user. Represented as a table of Booleans for the week, each indicating if that time slot is a valid logon time.
LoginScript
Gets and sets the logon script path.
LoginWorkstations
Gets and sets an array of BSTR addresses (or names) of workstations and net numbers at which the user can log on.
Manager
Gets and sets the user's manager.
MaxLogins
Gets and sets the number of simultaneous login sessions allowed.
MaxStorage
Gets and sets the maximum amount of disk space a user can have. Expressed in Kbytes.
NamePrefix
Prefix for the user's name, for example "Ms.", "Hon."
NameSuffix
Suffix for the user's name, for example "Jr.", "III".
OfficeLocations
Gets and sets an array of BSTR user locations.
OtherName
Gets and sets an additional name (for example, middle name) for the user.
PasswordExpirationDate
Gets and sets the date and time at which the password expires.
PasswordLastChanged
Gets the last time the password was changed.
PasswordMinimumLength
Gets and sets the minimum password length.
PasswordRequired
Gets and sets if the password is required.
Picture
Gets and sets an OctetString array of bytes that hold an image.
PostalAddresses
Gets and sets an array of BSTR postal addresses, multivalued in the case where the user has more than one address. The internal format of a PostalAddress should comply with CCITT F.401 as referenced in X.521-1993, which defines a PostalAddress as six elements of 30 bytes each, holding a street address, (optionally) Post Office Box, city or locality, state or province, Postal Code, and Country.
PostalCodes
Gets and sets an array of BSTR postal codes. Postal codes are positionally linked to the PostalAddresses array.
Profile
Gets and sets the path of user's profile.
RequireUniquePassword
Gets and sets if a new password must be different than those known through a password history.
SeeAlso
Gets and sets an array of ADsPaths of other objects related to this user.
TelephoneHome
Gets and sets an array of home telephone numbers for the user.
TelephoneMobile
Gets and sets an array of mobile telephone numbers for the user.
TelephonePager
Gets and sets an array of pager numbers for the user.
TelephoneNumber
Gets and sets an array of (usually work-related) telephone numbers associated with the user.
Title
Gets and sets the user's title.

See Also

ADSI User Object


IADsUser::ChangePassword

Changes the user's password from the specified old value to a new value.

HRESULT IADsUser::ChangePassword(
  BSTR bstrOldPassword,  //The current password
  BSTR bstNewPassword    //The new password
);

Parameter

bstrOldPassword
[in] The password as it currently exists.
BstrNewPassword
[out] The new password to use.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The ChangePassword command has been successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

ADSI User Object


IADsUser::Groups

Gets an IADsMembers pointer on a collection of ADSI group objects representing the groups to which this user belongs.

HRESULT IADsUser::Groups(
  IADsMembers ** ppGroups  //Interface on a members object
);

Parameter

ppGroups
[out] Indirect pointer to an IADsMembers interface on a members object that can be enumerated using IEnumVARIANT to determine the groups to which this end-user belongs.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The IADsMembers interface pointer on a group object representing this user's memberships in group was retrieved successfully.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

ADSI User Object


IADsUser::SetPassword

Sets the user's password to a specified value.

HRESULT IADsUser::SetPassword(
  BSTR bstrOldPassword,  //The old password
  BSTR bstrNewPassword,  //The new password
);

Parameter

bstrOldPassword
[in] The old password definition.
bstrNewPassword
[in] The new password definition.

Return Values

This method supports the standard return values E_FAIL and E_UNEXPECTED, as well as the following:

S_OK
The SetPassword command has been successfully issued.

QuickInfo

Windows NT: Use version 4.0 and later.
Windows CE: Unsupported.
Header: Declared in iads.h.

See Also

IADsUser, ADSI User Object


IDirectoryObject

The IDirectoryObject interface provides clients written in C and C++ with direct access to directory service objects. The interface enables access by means of a direct on-the-wire protocol, rather than through the ADSI property cache. In place of the properties supported by the IADS interface, IDirectoryOBject provides methods that support a critical subset of an object's housekeeping properties and provide access to its attributes. With IDirectoryObject, a client can get or set any number of object attributes with one method call. Unlike the corresponding Automation methods, which are transacted, those of IDirectoryObject are executed as soon as they are called. Because methods on this interface do not require creating an instance of a directory object, the performance overhead is very low.

When to Implement

ADSI providers who want to support non-Automation clients must implement IDirectoryObject on objects defined in their schemas.

When to Use

Clients written in languages such as C and C++ should call the methods of IDirectoryObject to optimize perfomance and take full advantage of native directory service interfaces. Implement this interface only on a custom directory service provider. For information on how this interface is implemented on system-supplied providers, see ADSI System Providers.

Automation clients cannot use IDirectoryObject. Instead, they should call the IADS interface.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDirectoryObject Methods | Description
GetObjectInformation | Gets information about a directory service object.
GetObjectAttributes | Gets one or more attributes of a directory service object.
SetObjectAttributes | Sets one or more attributes of a directory service object.
CreateDSObject | Creates a directory service object.
DeleteDSObject | Deletes a directory service object.

See Also

ADSI Object Model


IDirectoryObject::GetObjectInformation

Gets a pointer to a structure containing information about the identity and location of a directory service object.

HRESULT GetObjectInformation(
  PADS_OBJECT_INFO * ppObjInfo  //Information about the DS object
);

Parameters

ppObjInfo
[out] Address of a pointer to an ADS_OBJECT_INFO structure containing information about the requested directory service object. If ppObjInfo is NULL on return, GetObjectInformation cannot obtain the information requested.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The information was obtained successfully.

Remarks

The caller is responsible for releasing the ADS_OBJECT_INFO structure that GetObjectInformation creates.

Automation clients must call IADs::GetInfo


IDirectoryObject::GetObjectAttributes

Gets the definition of one or more specified attributes of the directory service object.

HRESULT GetObjectAttributes(
  LPWSTR * pAttributeNames,  //Names of requested attributes
  DWORD dwNumberAttributes,        //Number of attributes requested
  PADS_ATTR_INFO * ppAttributeEntries,  //Definitions of requested
                                       // attributes
  DWORD * pdwNumAttributesReturned  //Number of attributes obtained
);

Parameters

pAttributeNames
[in] Array of names of the attributes whose definitions are requested. If NULL, all of the object's attributes are requested.
dwNumberAttributes
[in] Size of the pAttributeNames array. If -1, all of the object's attributes are requested.
ppAttributeEntries
[out] Address of a pointer to an array of ADS_ATTR_DEF structures containing the requested attribute definitions. If NULL, no definitions could be obtained from the directory service object.
pdwNumAttributesReturned
[out] Address of a DWORD variable containing the number of attributes that GetObjectAttributes obtained.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The attribute definitions were obtained successfully.

Remarks

The caller is responsible for releasing the array of ADS_ATTR_DEF structures that GetObjectAttributes creates.


IDirectoryObject::SetObjectAttributes

Modifies specified attribute definitions of the directory service object.

HRESULT SetObjectAttributes(
  PADS_ATTR_INFO pAttributeEntries,
                             //Attributes and values to be set
  DWORD dwNumberAttributes,  //Number of attributes to be set
  DWORD * pdwNumAttributesModified
                             //Number of attributes set
);

Parameters

pAttributeEntries
[in] Array of attribute definitions to be modified. Each attribute definition contains the name of the attribute and the value it is to be set to as defined in ADS_ATTR_INFO. .
dwNumAttributes
[in] Number of attributes to be modified. This value should correspond to the size of the pAttributeEntries array.
pdwNumAttributesModified
[out] Pointer to a DWORD variable containing the number of attributes that SetObjectAttributes modified.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The attributes were set successfully.


IDirectoryObject::CreateDSObject

Creates a child of the current directory service object.

HRESULT CreateDSObject(
  LPWSTR pszRDNName,     //Relative path of new object
  PADS_ATTR_INFO pAttributeEntries,
                         //Attributes to be set
  DWORD dwNumAttributes  //Number of attributes being set
);

Parameters

pszRDNName
[in] Relative distinguished name (relative path) of the object to be created.
pAttributeEntries
[in] Array of ADS_ATTR_INFO structures containing attribute definitions to be set when the object is created. Each attribute definition contains the name and initial value of the attribute.
dwNumAttributes
[in] Number of attributes being set when the object is created.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The object was created successfully.

Remarks

All attributes to be initialized on creation must be specified in the pAttributeEntries array. Optional attributes may also be specified.

Once the object is created, the caller can access it by its relative distinguished name. No pointer to the object is necessary.


IDirectoryObject::DeleteDSObject

Deletes a directory service object

HRESULT DeleteDSObject(
  LPWSTR pszRDNName,  //Relative distinguished name of object
);

Parameters

pszRDNName
Relative distinguished name (relative path) of the object to be deleted.


IDirectorySearch

The IDirectorySearch interface provides clients written in C and C++ with vtable access to methods for querying underlying directory service data.

When to Implement

ADSI providers who want to supply non-Automation clients with vtable methods for querying their directory services must implement IDirectorySearch on every generic directory service object. Implement this interface only on a custom directory service provider. For information on how this interface is implemented on system-supplied providers, see ADSI System Providers.

When to Use

Call the methods of IDirectorySearch from a non-Automation client to query the directory service and to examine the query result.

Methods in Vtable Order

IUnknown Methods | Description
QueryInterface | Returns pointers to supported interfaces.
AddRef | Increments reference count.
Release | Decrements reference count.

IDirectorySearch Methods | Description
SetSearchPreference | Sets options for conducting a search
ExecuteSearch | Executes an individual search
AbandonSearch | Abandons search already under way.
GetFirstRow | Gets the first row of the search result.
GetNextRow | Gets the next row of the search result
GetPreviousRow | Gets the previous row of the search result
GetNextColumnName | Gets the name of the next column of the search result
GetColumn | Gets the item in a specified column from the current row of the search result
FreeColumn |
CloseSearchHandle | Releases the search result from memory.

See Also

Using Directory Service Queries


IDirectorySearch::SetSearchPreference

Specifies data to be obtained by a subsequent search.

HRESULT SetSearchPreference(
  PADS_SEARCHPREF_INFO pSearchPrefs,
                    //Search preferences to be set
  DWORD dwNumPrefs  //Number of preferences
);

Parameters

pSearchPrefs
[in] Caller-allocated array of ADS_SEARCHPREF_INFO structures containing the search preferences to be set.
dwNumPrefs
[in] The size of the pSearchPrefs array.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The search preference was set.
E_ADS_INVALID_SEARCHPREF
The specified search preference is not available in, or cannot be set by, the directory service.
E_ADS_INVALID_SEARCHPREF_VALUE
The specified search preference value is invalid. Values for the search preference must be defined in the ADS_SEARCHPREF enumeration.

See Also

ADS_SEARCHPREF_INFO, Using Directory Service Queries


IDirectorySearch::ExecuteSearch

Executes a search and passes the results to the caller.

HRESULT ExecuteSearch(
  LPWSTR pszSearchFilter,  //Search filter string in LDAP format
  LPWSTR pAttributeNames,  //Attributes to be obtained
  DWORD dwNumberAttributes,  //Size of pAttributeNames array
  PADS_SEARCH_HANDLE phSearchResult
                           //Search result handle
);

Parameters

[in] pszSearchFilter
Search filter string in LDAP format.
[in] pAttributeNames
Array of attribute names for which data is requested. If NULL, all attributes are requested and dwNumberAttributes must be -1.
[in] dwNumberAttributes
Size of the pAttributeNames array. If -1, all attributes are requested and pAttributeNames must be NULL.
[out] phSearchResult
Address of a method-allocated handle to the search result. The caller passes this handle to other methods of IDirectorySearch to examine the search result.If NULL, the search could not be executed.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The search was successfully completed.

Remarks

The caller is responsible for calling CloseSearchHandle to release the memory allocated for the search handle and search result.

See Also

Using Directory Service Queries


IDirectorySearch::AbandonSearch

Abandons search initiated with earlier call to ExecuteSearch.

HRESULT AbandonSearch(
  ADS_SEARCH_HANDLE hSearchResult,  //Search result handle
);

Parameters

[in] hSearchResult
Handle to the search result.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The next row was successfully obtained.
S_ADS_NOMORE_ROWS
The current row before the call was the last row in the search result. The current row was not changed.

See Also

Using Directory Service Queries


IDirectorySearch::GetFirstRow

Gets the first row of a search result.(

HRESULT GetFirstRow(
  ADS_SEARCH_HANDLE hSearchResult,  //Search result handle
);

Parameters

[in] hSearchResult
Handle to the search result.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The next row was successfully obtained.
S_ADS_NOMORE_ROWS
The current row before the call was the last row in the search result. The current row was not changed.

See Also

Using Directory Service Queries


IDirectorySearch::GetNextRow

Gets the next row of the search result.

HRESULT GetNextRow(
  ADS_SEARCH_HANDLE hSearchResult,  //Search result handle
);

Parameters

[in] hSearchResult
Handle to the search result.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The next row was successfully obtained.
S_ADS_NOMORE_ROWS
The current row before the call was the last row in the search result. The current row was not changed.

See Also

Using Directory Service Queries


IDirectorySearch::GetPreviousRow

Gets the previous row of the search result.

HRESULT GetPreviousRow(
  ADS_SEARCH_HANDLE hSearchResult,  //Search result handle
);

Parameters

[in] hSearchResult
Handle to the search result.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The previous row was successfully obtained.
S_ADS_NOMORE_ROWS
The current row before the call was the first row in the search result. The current row was not changed.

See Also

Using Directory Service Queries


IDirectorySearch::GetNextColumnName

Gets the name of the next column in the search result that contains data.

HRESULT GetNextColumnName(
  ADS_SEARCH_HANDLE hSearchResult,  //Search result handle
  LPWSTR * ppszColumnName           //Name of next column with data
);

Parameters

[in] hSearchResult
Handle to the search result.
[out] ppszColumnName
Address of a pointer to a method-allocated string containing the requested column name. If NULL, no subsequent rows contain data.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The name of the next column containing data was successfully obtained.

Remarks

The caller is responsible for freeing the memory allocated for the column name.

See Also

Using Directory Service Queries


IDirectorySearch::GetColumn

Gets data from a column of the current row of the search result.

HRESULT GetColumn(
  ADS_SEARCH_HANDLE hSearchResult,  //Search result handle
  LPWSTR szColumnName,              //Name of requested column
  PADS_SEARCH_COLUMN pSearchColumn  //Contents of the requested
                                    // column
);

Parameters

[in] hSearchResult
Handle to the search result.
[in] szColumnName
Name of the column whose data is requested.
[out] pSearchColumn
Address of a method-allocated ADS_SEARCH_COLUMN structure containing the column from current row of the search result.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The column was obtained.

Remarks

The caller is responsible for freeing the memory allocated for the column by calling FreeColumn.

See Also

ADS_SEARCH_COLUMN, Using Directory Service Queries


IDirectorySearch::FreeColumn

Releases memory allocated by GetColumn for data from a search result column.

HRESULT FreeColumn(
  PADS_SEARCH_COLUMN pSearchColumn  //Column data to be freed
);

Parameters

[in] pSearchColumn
Pointer to the column to be freed.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The column was freed.

See Also

Using Directory Service Queries


IDirectorySearch::CloseSearchHandle

Closes the handle to a search result and frees the memory allocated for the search result.

HRESULT CloseSearchHandle(
  ADS_SEARCH_HANDLE hSearchResult,  //Search result to be closed
);

Parameters

[in] hSearchResult
Handle to the search result to be closed.

Return Values

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK
The search result was closed.

Note to Implementers

The CloseSearchHandle method must free all memory allocated by ExecuteSearch, including the search result and the search result handle.

See Also

Using Directory Service Queries


ADSI Object Definitions

The Active Directory object definitions included in this document are examples of how COM objects can be used to support the Active Directory Service Interfaces. They are supplied here as a convenience.

All the properties accessed by property methods supported on Active Directory Service Interfaces are defined in this section.

ADSI client applications should be aware that ADSI providers may choose to support provider-specific interfaces on ADSI objects and may provide access to the underlying namespace data store attributes or properties using the late-bound methods for saving and retrieving properties by name: IADs::Get, IADs::GetEx, IADs::Put, and IADs::PutEx.

The following ADSI objects are grouped by function. There are several categories of ADSI objects:

  • Standard ADSI objects that are implement by all ADSI provider software. See Standard ADSI Objects.
  • ADSI objects that represent specific elements in the underlying directory service. See Example ADSI Objects.


Standard ADSI Objects

The following interfaces support the methods and properties that manage the basic Active Directory object.


Example ADSI Objects

The following COM objects support interfaces that provide methods that do not access a directory service's persistent data, but provide methods for namespaces that can work with volatile information, such as issuing commands to control processes over a network.

Objects that Represent Properties of an Object | Objects that Organize::
ADSI PropertyEntry Object | ADSI Collection Object
ADSI PropertyValue Object | ADSI Enumerator Object
 | ADSI Group Object
Objects that Represent Security |
ADSI AccessControlEntry Object |
ADSI AccessControlList Object |
ADSI SecurityDescriptor Object |
Objects that Represent a Directory Service Hierarchy: |
ADSI Computer Object |
ADSI Domain Object | Objects that Represent a Directory Service Schema:
ADSI FileShare Object | ADSI Schema Container Object
ADSI Service Object | ADSI Schema Class Object
ADSI FileService Object | ADSI Property Object
ADSI Resource Object | ADSI Syntax Object
ADSI Session Object |
ADSI PrintQueue Object |
ADSI PrintJob Object |
ADSI User Object |
ADSI Country Object |
ADSI Organization Object |
ADSI OrganizationalUnit Object |
ADSI Locality Object |


ADSI AccessControlEntry Object

An ADSI AccessControlEntry Object represents an access control entry (ACE). ADSI AccessControlList Objects manage one or more ACEs to create an access control list (ACL). Each ACE grants or denies a specific access privilege on an object.

When to Implement

Implement ADSI AccessControlEntry Objects when you are providing an Active Directory Service implementation that supports ACLs.

The ADSI SDK comes with a system implementation of this object in the Microsoft-supplied WinNT provider.

Interfaces typically supported on ADSI Directory Object |  | Description
IUnknown |  | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADsAccessControlEntry |  | ACE trustee and access type management.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

ADSI SecurityDescriptor Object, Using Credentials and Security


ADSI AccessControlList Object

An ADSI AccessControlList Object represents an access control list (ACL) that manages one or more ADSI AccessControlEntry Objects. Both discretionary and system ACLs use this object type to manage the ACEs defined on an object. The IADsSecurityDescriptor interface supports several property methods that contain pointers to this type of object.

When to Implement

Implement ADSI AccessControlList Objects when you are providing an Active Directory Service implementation that supports ACLs.

The ADSI SDK comes with a system implementation of this object in the Microsoft-supplied WinNT provider.

Interfaces typically supported on ADSI Directory Object |  | Description
IUnknown |  | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADsAccessControlList |  | ACL management of the ACE list that defines access on a given object.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

ADSI SecurityDescriptor Object


ADSI Collection Object

An Active Directory collection object is a COM object in Active Directory that manages one or more arbitrary sets of items.

Use an ADSI Collection Object when you are managing a collection of VARIANT items (for example, a list of VT_BSTR strings or a list of active print jobs). Use an ADSI Group Object when you are managing a collection of lists of object references (for example, users in a group).

Each collection, by Active Directory convention, consists of only one type of VARIANT data structure. Each item is added to the collection with an associated name that is used to retrieve that item. A collection differs from a straight array of items because items can be added and removed from the collection without having to manipulate the whole collection in memory.

List a collection through the standard Automation enumeration techniques provided through the IEnumVARIANT interface pointer on an ADSI Enumerator Object retrieved by IADsCollection::get__NewEnum.

Interfaces on ADSI Collection Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADsCollection | Collection management methods.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsCollection, ADSI Enumerator Object


ADSI Computer Object

ADSI Computer Object represents the information about a computer (server, client, workstation) on a network. In some directory services, a computer object can contain other computer objects or the services that computer provides. In other directory services, a computer object is a single device.

Interfaces typically supported on ADSI Computer Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsContainer | Object management and enumeration methods.
IADsComputer | Management methods for a computer object and its persistent properties.
IADsComputerOperations | Computer information management methods for non-persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsComputer, IADsComputerOperations


ADSI Container Object

An Active Directory container object is an Active Directory Object that contains other COM objects. An Active Directory object is created and managed through its parent container object. The containment relationship is defined through an Active Directory object's schema class object which provides on-line run-time definitions of what types of objects can be created within a specific container.

Containers are different from collections. Containers control the objects within them, providing methods to create, filter, retrieve, copy, move and delete them. Collections represent arbitrary sets of items and provide methods to filter and manipulate the sets.

When to Use

Container objects are used frequently when representing any hierarchical structure such as a directory tree. Container objects are used for the nodes in the directory tree that can be expanded to further levels of the tree for a directory instance.

Container objects occur throughout the Active Directory architecture as a natural consequence of the hierarchical nature of directory services. For example, the top-level container object in Active Directory is the ADSI Namespaces Object that contains an ADSI Namespace Object for every Active Directory provider.

Note Calling IADs::GetInfo and IADs::SetInfo, the caching routines for an object's properties, does not affect the objects stored in a container. Calling Get/SetInfo affects the properties of the container object, not the objects it manages.

Interfaces on ADSI Container Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties
IADs | Standard Active Directory object management methods.
IADsContainer | Object and persistent property management and enumeration methods.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADs, IADsContainer, ADSI Object


ADSI Country Object

ADSI Country Object is one of several optional Active Directory COM objects that is a directory service containers. Some directory services provide hierarchical groupings of directory entries using the concepts of country (ADSI Country Object), geographical location (ADSI Locality Object), company or organization (ADSI Organization Object), and department or organizational unit (ADSI OrganizationalUnit Object) to help manage security access rights. The containment relationships among these objects is entirely provider-dependent.

Interfaces typically supported on ADSI Country Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsContainer | Object management and enumeration methods.

QuickInfo

Windows NT: Use version 4.0 and later.


ADSI Directory Object

ADSI Directory Object represents any generic directory service element, such as a document, a file, or any other element that can be uniquely identified by an ADsPath. The directory object has the least overhead and gives the ADSI client the most control over its use and is not available to Automation clients.

Interfaces typically supported on ADSI Directory Object | Description
IUnknown | Universal COM object management and interface query methods.
IDirectoryObject | Standard Active Directory object management methods.

QuickInfo

Windows NT: Use version 4.0 and later.


ADSI Domain Object

ADSI Domain Object is an Active Directory container object that represents an instance of a directory for a domain on a network. A provider's directory service implementation determines the specific use of this object. For example, a domain container object might consist of all the computer objects on a network with the role of domain controller.

Interfaces typically supported on ADSI Domain Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsContainer | Object life-cycle management and enumeration methods.
IADsDomain | Management methods for a domain object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsDomain


ADSI Enumerator Object

An ADSI Enumerator Object is a dependent COM object in Active Directory that enumerates its Active Directory host object. ADSI Container Objects, ADSI Members Objects, and ADSI Collection Objects host enumerator objects. This object supports the Automation IEnumVARIANT interface, which is retrieved by the get__NewEnum ( _NewEnum) method supported by IADsContainer, IADsMembers, and IADsCollection. By convention, all items managed by an enumerator object are of the same Automation data type. An enumeration should not retrieve some items as VARIANTs of type VT_I4 and others as VARIANTs of type VT_BSTR. Active Directory objects interfaces are represented by the VT_UNKNOWN type.

When to Implement

Implement ADSI Enumerator Object only when you are providing Active Directory enumeration functionality for your directory service implementation.

Follow one of three models for caching collections during enumeration. The caching model affects the behavior of Active Directory when an object in a collection is deleted from the underlying directory service "outside" of Active Directory.

  1. Collections are cached. The collection of object instances is retrieved from the underlying directory in its entirety when get_NewEnum (_NewEnum) is called to create a new enumerator object. If the source object for an Active Directory object instance in the retrieved collection is deleted from the underlying directory, you do not become aware of the deletion until an IADs::GetInfo or IADs::SetInfo attempts to access the source instance.
  2. Collections are incrementally cached. The collection is retrieved from the underlying directory one object at a time when IEnumVARIANT::Next is called. Reset returns to the beginning of the collection in the cache and Next will return cached objects until the end of the cache is reached, at which point new objects are added from the underlying store. Once an Active Directory object instance is in the cache, you do not become aware of its deletion from the underlying directory until an IADs::GetInfo or IADs::SetInfo attempts to access the source instance.
  3. Collections are not cached. The collection is retrieved from the underlying directory one object at a time when IEnumVARIANT::Next is called. Reset returns to the beginning of the collection in the underlying store. Next and Reset operations cannot retrieve deleted objects, since the objects are fetched on-demand from the underlying directory. Only the "current" object is cached. If the current object is deleted, you do not become aware of its deletion from the underlying directory until an IADs::GetInfo or IADs::SetInfo attempts to access the source instance.

ADSI Container Object or ADSI Members Object enumerations yield one or more Active Directory interfaces. Cache the retrieved pointers for any Active Directory objects you intend to manipulate to avoid the overhead of obtaining a new interface pointer. For example, a Visual Basic program that enumerates a container and populates a listbox with names can cache the interface pointers associated with the names for later use. This approach provides greater performance than populating the listbox during enumeration and obtaining a new interface pointer when the user makes a selection.

Interfaces on ADSI Enumerator Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties
IEnumVARIANT | Iteration methods for stepping through the items in a container.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

ADsBuildEnumerator, ADsEnumerateNext, ADsFreeEnumerator


ADSI FileShare Object

ADSI FileShare Object represents a published file share point of a file service. A file share point is a node of a directory structure that is made accessible to other clients through a directory service file manager. File shares can be enumerated from an ADSI Service Object that is a file service container object.

Interfaces typically supported on ADSI FileShare Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsFileShare | Management methods for a file share object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsFileShare, ADSI Service Object


ADSI Group Object

ADSI Group Object represents a list, which can be persistently stored, of Active Directory member objects in the underlying directory service. Some directory implementations allow only users to be members of a group; others allow users, groups, and organizational units (departments) to be group members.

An ADSI Group Object hosts an ADSI Members Object and supports methods to add and remove member references from its collection.

Use an ADSI Collection Object when you are managing a collection of VARIANT items (for example, a list of numbers or a list of active print jobs). Use an ADSI Members Object when you are managing a collection of ADSI Objects references.

Interfaces typically supported on ADSI Group Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsGroup | Management methods for a group object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsCollection, IADsGroup, IADsMembers, ADSI Members Object


ADSI Locality Object

ADSI Locality Object is one of several optional Active Directory COM objects that is a directory service containers. Some directory services provide hierarchical groupings of directory entries using the concepts of country (ADSI Country Object), geographical location (ADSI Locality Object), company or organization (ADSI Organization Object), and department or organizational unit (ADSI OrganizationalUnit Object) to help manage security access rights. The containment relationships among these objects is entirely provider-dependent.

Interfaces typically supported on ADSI Locality Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsLocality | Management methods for a locality object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsLocality


ADSI Members Object

An Active Directory members object is a COM object that represents a collection of Active Directory object references (for example, users in a group). This object supports counting, filtering and enumerating its members. Use methods defined on the ADSI Group Object to control the actual addition and removal of member references.

List a members object through the standard Automation enumeration techniques provided through the IEnumVARIANT interface pointer on an ADSI Enumerator Object retrieved by IADsMembers::get__NewEnum.

Interfaces typically on ADSI Members Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties
IADsMembers | Member management and filtering methods for persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsCollection, IADsGroup, IADsMembers, ADSI Collection Object, ADSI Enumerator Object, ADSI Group Object


ADSI Namespace Object

ADSI Namespace Object is a COM container object that represents the second tier in Active Directory's hierarchical design. The top level container, ADSI Namespaces Object, contains an ADSI Namespace Object for every provider's Active Directory implementation. Enumerating an ADSI Namespace Object lists all the provider objects of that implementation.

The ADSI Namespace Object has no corresponding ADSI Schema Class Object which defines its schema class type, because it doesn't actually correspond to an entry in the directory but is a consequence of the Active Directory architecture.

Notes to Implementers

The ADSI Namespace Object is responsible for resolving ADsPath names in to Active Directory objects using the IParseDisplayName interface. Clients are not expected to access this interface directly. See ADSI Example Provider Component.

Interfaces supported on ADSI Namespace Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsOpenDSObject | Binds to an object with a set of credentials.
IParseDisplayName | Parses name into moniker.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADs, ADSI Namespaces Object


ADSI Namespaces Object

The ADSI Namespaces Object is the top-level COM container object of Active Directory. This object contains one top-level container ADSI Namespace Object for every Active Directory provider implementation that is installed and available for use. The Namespaces object may not contain any other type of object.

Interfaces typically supported on ADSI Namespaces Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsContainer | Object management and enumeration methods. See note below.
IADsNamespaces | Management methods for the top-level Active Directory object and its persistent properties.


ADSI Object

An Active Directory object is a COM object that represents a part of the natural hierarchical structure of directory trees or directory services supplied over a network.

All object creation and management occurs within a parent Active Directory Container Object. Active Directory objects that support sub-objects or dependent objects are Active Directory host objects. Every Active Directory object has a parent container, except the top most ADSI Namespaces Object.

Active Directory objects can be identified by:

Relative name
The leaf name of the object, that distinguishes it from sibling directory entries.
Schema Class Name
The schema class name identifies the type of object this is ("user", "computer", "domain"). Browsing the ADSI Schema Class Object corresponding to this type always yields the current definition of the well-known relationships of this object: what objects can contain this object, whether this object is a container, what CLSID provides an implementation, what properties and interfaces it supports, etc.). Every Active Directory object has a single primary interface that can be used with QueryInterface to identify the schema class of the object (IID_IADsUser, IID_IADsComputer, IID_IADsDomain).
ADsPath
An Active Directory naming convention to uniquely identify an Active Directory object regardless of directory service implementation. ADsPath strings are COM display names. Bind to an ADsPath name using GetObject in Visual Basic and ADsGetObject in C++/C . To bind to an object when the ADsPath name is not know, use IADsNamespaces::get_DefaultContainer. Both the URL (preferred format) and the OLE format are supported by all providers. ProgIDs (programmatic identifiers) are case sensitive and must match the value registered in the registry exactly.
ADsPath - URL format
"ADs:" or "WinNT:" or "Your_ProgID://Your_Provider_Specific_String"
ADsPath - OLE format
"@ADs!" or "@WinNT!" or "@Your_ProgID!Your_Provider_Specific_String"

When to Implement

Implement ADSI Objects only when you are providing an Active Directory implementation for your directory service. Because every directory entry on a directory tree on your network is represented by an Active Directory object, choose a very "light-weight" representation for performance reasons.

See ADSI for Providers.

Interfaces supported on ADSI Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods and persistent property management.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADs


ADSI Organization Object

ADSI Organization Object is one of several optional Active Directory COM objects that is a directory service containers. Some directory services provide hierarchical groupings of directory entries using the concepts of country (ADSI Country Object), geographical location (ADSI Locality Object), company or organization (ADSI Organization Object), and department or organizational unit (ADSI OrganizationalUnit Object) to help manage security access rights. The containment relationships among these objects is entirely provider-dependent.

Interfaces typically supported on ADSI Organization Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsContainer | Object management and enumeration methods.
IADsO | Management methods for an organization object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsO


ADSI OrganizationalUnit Object

ADSI OrganizationalUnit Object is one of several optional Active Directory COM objects that is a directory service containers. Some directory services provide hierarchical groupings of directory entries using the concepts of country (ADSI Country Object), geographical location (ADSI Locality Object), company or organization (ADSI Organization Object), and department or organizational unit (ADSI OrganizationalUnit Object) to help manage security access rights. The containment relationships among these objects is entirely provider-dependent.

Interfaces typically supported on ADSI OrganizationalUnit Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsContainer | Object management and enumeration methods.
IADsOU | Management methods for an organizational unit object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsOU


ADSI PrintJob Object

ADSI PrintJob Object represents the information about a single print job request from a client represented by an ADSI PrintQueue Object on a network. Print job objects are not stored in the underlying directory and do not have a parent container. They are managed through the IADsCollection interface retrieved through IADsPrintQueueOperations::PrintJobs interface.

Interfaces typically supported on ADSI PrintJob Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsPrintJob | Management methods for a print job object and its properties.
IADsPrintJobOperations | Management methods for a print job.

Properties accessed through IADsPrintJob | Access | Compiler Syntax
Description | R/W | HRESULT get_Description ([out] BSTR *pbstrDescription); HRESULT put_Description ([in] BSTR bstrDescription);
HostPrintQueue | R/O | HRESULT get_HostPrintQueue ([out] BSTR *pbstrHostPrintQueue);
Notify | R/W | HRESULT get_Notify ([out] BSTR *pbstrNotify); HRESULT put_Notify ([in] BSTR bstrNotify);
NotifyPath | R/W | HRESULT get_NotifyPath ([out] BSTR *pbstrNotifyPath); HRESULT put_NotifyPath ([in] BSTR bstrNotifyPath);
Priority | R/W | HRESULT get_Priority ([out] long *plPriority); HRESULT put_Priority ([in] long lPriority);
Size | R/O | HRESULT get_Size ([out] long *plSize);
StartTime | R/W | HRESULT get_StartTime ([out] DATE *pdateStartTime); HRESULT put_StartTime ([in] DATE dateStartTime);
TimeSubmitted | R/O | HRESULT get_TimeSubmitted ([out] DATE *pdateTimeSubmitted);
TotalPages | R/O | HRESULT get_TotalPages ([out] long *plTotalPages);
UntilTime | R/W | HRESULT get_UntilTime ([out] DATE *pdateUntilTime); HRESULT put_UntilTime ([in] DATE dateUntilTime);
User | R/O | HRESULT get_User ([out] BSTR *pbstrUser);
UserPath | R/O | HRESULT get_UserPath ([out] BSTR *pbstrUserPath);

Description
Gets and sets the description of the print job.
HostPrintQueue
Gets the ADsPath string that references the Print Queue which is processing the print job.
Notify
Gets and sets the user to notify when job processing is complete.
NotifyPath
Gets and sets the ADsPath for the user object of the user to notify when job processing is complete.
Priority
Gets and sets the priority of the print job.
Size
Gets the size of the print job in bytes.
StartTime
Gets and sets the earliest time the job should be printed.
TimeSubmitted
Gets the time that the job was submitted to the queue.
TotalPages
Gets the total number of pages in the print job.
UntilTime
Gets and sets the latest time the job should be printed.
User
Gets the name of user that submitted the print job.
UserPath
Gets the ADsPath of the user object for the user that submitted this print job.
Properties accessed through IADsPrintJobOperations Access Compiler Syntax
Status R/O HRESULT get_Status
([out] long *plStatus);
TimeElapsed R/O HRESULT get_TimeElapsed
([out] long *plTimeElapsed);
PagesPrinted R/O HRESULT get_PagesPrinted
([out] long *plPagesPrinted);
Position R/W HRESULT get_Position
([out] long *plPosition);

HRESULT put_Position
([in] long lPosition);

PagesPrinted
Gets the number of pages complete.
Position
Gets and sets the numeric position of the job in the queue.
Status
Integer value indicating current status of service. The following values are defined:
STATUS | Hex Value
ADS_JOB_PAUSED | 0x00000001
ADS_JOB_ERROR | 0x00000002
ADS_JOB_DELETING | 0x00000004
ADS_JOB_PRINTING | 0x00000010
ADS_JOB_OFFLINE | 0x00000020
ADS_JOB_PAPEROUT | 0x00000040
ADS_JOB_PRINTED | 0x00000080
ADS_JOB_DELETED | 0x00000100

TimeElapsed
Gets the time elapsed, in seconds, since the job started printing.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsCollection, IADsPrintJob, IADsPrintJobOperations, IADsPrintQueue, IADsPrintQueueOperations, ADSI Collection Object, ADSI PrintQueue Object


ADSI PrintQueue Object

ADSI PrintQueue Object represents a print queue service, receiving and managing print requests from clients across a network, and sending the requests to available print devices for the actual printing. A print queue service typically allows clients to view and sometimes modify their print requests. An administrator may also need to change priorities of print requests by changing their order in the queue or modify the queue in other ways to improve the efficiency of the print service.

Interfaces typically supported on ADSI PrintQueue Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsPrintQueue | Management methods for a print queue object and its persistent properties.
IADsPrintQueueOperations | Management methods for a print queue's non-persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsPrintJob, IADsPrintJobOperations, IADsPrintQueue, IADsPrintQueueOperations, ADSI Collection Object, ADSI PrintJob Object


ADSI Property Object

ADSI Property Object represents a single property in the Active Directory schema. Properties are items of information that describe, identify, or qualify aspects of an Active Directory object. Property objects are enumerated from the ADSI Schema Container Object.

A property is described by its name (IADs::Name), pathname to the syntax definition (IADsProperty::get/put_Syntax), and constraints.

The name given to a property and used for IADs::Name must also be valid for use in name-bound operations from IDispatch on that property.

When to Implement

Implement ADSI Property Objects when you are providing an Active Directory Service implementation.

Providers for directory services that require properties be globally unique must check that a new property does not collide with an existing property at creation time. When a new property name matches an existing property name, the create operation is only allowed if the new property definition exactly matches the existing property definition.

Interfaces on ADSI Property Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsProperty | Set and retrieve property object persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

ADSI Schema Container Object, ADSI Schema Class Object, ADSI Syntax Object


ADSI PropertyEntry Object

An ADSI PropertyEntry Object represents a property entry in the ADSI property cache and supports an IADsPropertyEntry interface. IADsPropertyList supports the methods to manage property entries, including enumeration.

When to Implement

Implement ADSI PropertyEntry Objects when you are providing an Active Directory Service implementation.

The ADSI SDK comes with a system implementation of this object for every Microsoft-supplied ADSI provider.

Interfaces on ADSI PropertyEntry Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADsPropertyEntry | Methods and property methods to access a specific attribute in the ADSI property cache.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsPropertyList , IADsPropertyValue, ADSI PropertyValue Object


ADSI PropertyValue Object

An ADSI PropertyValue Object represents a property value for a property named in the ADSI property cache. The property method IADsPropertyEntry::get/put_Values manages access to the VARIANT array of pointers to IADsPropertyValue interfaces supported by this type of object.

When to Implement

Implement ADSI PropertyValue Objects when you are providing an Active Directory Service implementation.

The ADSI SDK comes with a system implementation of this object for every Microsoft-supplied ADSI provider.

Interfaces on ADSI PropertyValue Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADsPropertyValue | Methods and property methods to access a specific ADSI value object for a named property in the cache.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsPropertyList , IADsPropertyValue, ADSI PropertyValue Object


ADSI Resource Object

The ADSI Resource Object represents a information describing an open resource on a specific file service. A file service uses various resources to complete a client's requests (files, printers, schedulers, faxes, etc.).

Because ADSI Resource Objects are managed through the IADsCollection interface on a collection object, they do not have a parent container.

When to Implement

Providers dynamically create ADSI Resource Objects as needed during the processing of file service requests. Although these objects have an ADsPath property supported on their IADs interface, the contents of the property may not be used to instantiate the resource object.

Interfaces typically supported on ADSI Resource Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsResource | Management methods for a resource object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsResource


ADSI Schema Container Object

The Active Directory schema container object is the top of the hierarchical organization of on-line, run-time definitions of Active Directory object relationships in a directory service implementation of Active Directory. The schema container object contains all the ADSI Schema Class Objects, one for every type of object that can be created in a given provider's implementation for a specific instance of that directory service. This object also contains the ADSI Property Objects and the ADSI Syntax Objects necessary to represent this schema.

Schema containers are not limited to this level of the hierarchy. A complex directory service instance might allow multiple schema containers to exist in its implementation and then the schema containers might be found in other parts of the tree. However, there can only be one schema container in any given Active Directory container.

The Active Directory schema management objects include:

Object type | Contains
ADSI Schema Container Object | Container object for the current collection of schema class objects and syntax objects that represent the schema for this entire or partial directory instance.
ADSI Schema Class Object | Definitions for a specific schema class.
ADSI Property Object | Identifies a single property.
ADSI Syntax Object | Identifies a single syntax.

Interfaces on ADSI Schema Container Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADsContainer | Object management and enumeration methods.

QuickInfo

Windows NT: Use version 4.0 and later.


ADSI Schema Class Object

ADSI Schema Class Object represents a specific type of Active Directory object that represents an element in a directory service. Users, computers and services are typical classes necessary to represent a directory service.

Classes may be uniquely identified in the schema by GUID. The CLSID property indicates which COM object implements the class.

Every Active Directory object has one primary interface identifying the schema class among all the interfaces the object supports.

When to Implement

You must always implement a ADSI Schema Class Object when you are providing a new schema class for a directory service. Classes and their properties and methods need to be defined in the corresponding schema object accessed through the IADs::get_Schema method. The IADs::get_Name property for a schema class object must be valid for use in filter and create operations in the containers that appear in the IADsClass::get_Containment and put_Containment array. MandatoryProperties lists the property names that must be initialized before an object of this type can be created.

Interfaces on ADSI Schema Class Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsClass | Set and retrieve class properties

Notes to Implementers For Active Directory providers implementing the PrimaryInterface property, note that for objects that directly support properties, this interface must be the interface that supports the property VTABLE, if one is provided. When you do not know what interface should be returned as the primary interface, use IID_IADs. Objects that do not support a specific dual interface for property get and put must also return IID_IADs in this property. In both cases, this allows access to all properties through the IADs::Get, IADs::GetEx, IADs::Put, and IADs::PutEx methods.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

ADSI Property Object, ADSI Schema Container Object, ADSI Syntax Object


ADSI SecurityDescriptor Object

An ADSI SecurityDescriptor Object represents the set of properties and methods needed to support ACLs and other security information for a directory service object. This includes discretionary and system ACLs in addition to object ownership and group memberships. Because security descriptor objects are included in the ADSTYPE enumeration, objects can add a property using the IADs::Put feature to add security rules at run time.

When to Implement

Implement ADSI SecurityDescriptor Objects when you are providing an Active Directory Service implementation that supports ACLs.

The ADSI SDK comes with a system implementation of this object in the Microsoft-supplied WinNT provider.

Interfaces typically supported on ADSI Directory Object |  | Description
IUnknown |  | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADsSecurityDescriptor |  | Security property management for directory service objects.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

ADSI AccessControlList Object, Using Credentials and Security


ADSI Service Object

The ADSI Service Object represents any software service running on a networked machine. Examples of directory services include file servers, print servers, fax servers, database servers, and SNA servers. Service objects support the normal Active Directory interfaces and IADsService and IADsServiceOperations. Service objects that represent file services additionally support IADsContainer, IADsFileService and IADsFileServiceOperations. An object representing a file service contains ADSI FileShare Objects.

Notes to Implementers If this object does not represent a file service object, return E_NOTIMPL for QueryInterface calls on IID_IADsContainer, IID_IADsFileService, and IID_IADsFileServiceOperations.

Interfaces typically supported on ADSI Service Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsService | Management methods for a service object and its persistent properties.
IADsServiceOperations | Management methods for a service object and its non-persistent properties.
IADsContainer | Standard Active Directory container object management and property methods.
IADsFileService | Management methods for a service object that is a file service and its persistent properties.
IADsFileServiceOperations | Management methods for a service object that is a file service and its non-persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsContainer, IADsFileService, IADsFileServiceOperations, IADsService, IADsServiceOperations, ADSI Container Object, ADSI FileShare Object, ADSI Resource Object, ADSI Session Object


ADSI Session Object

The ADSI Session Object represents a information describing an active communication connection between a client and a file . A file service uses various resources to complete a client's requests (files, printers, schedulers, faxes, etc.).

Because ADSI Session Objects are managed through the IADsCollection interface on a collection object, they do not have a parent container.

When to Implement

Providers dynamically create ADSI Session Objects as needed during the processing of file service requests. Although these objects have an ADsPath property supported on their IADs interface, the contents of the property may not be used to instantiate the resource object.

Interfaces typically supported on ADSI Session Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsSession | Management methods for a session object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsFileService, ADSI Service Object


ADSI Syntax Object

ADSI Syntax Object is a COM object that represents the syntax of a property as it is defined in the ADSI Schema Container Object, which can be enumerated to list all valid syntaxes. ADSI Property Object refers to the syntax needed to interpret its property value through IADsProperty::get_Syntax property method.

Syntax objects differ from other Active Directory schema objects in that there are no interfaces or properties specific to the syntax object. Syntax objects exist solely as named entities of class "syntax" in the schema container.

Active Directory defines a set of standard syntax objects that can be used uniformly across diverse directory services.

Interfaces on ADSI Syntax Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsSyntax | Management methods for a syntax object and its persistent properties.

Standard Syntax Objects

Object | IDL type | Description
Boolean | boolean | TRUE (1) / FALSE (0)
Counter | long | Differs from Integer in that any value added is added to the total, and any value deleted is deleted from the total.
ADsPath | BSTR | Values uniquely identify objects
EmailAddress | BSTR | Fully qualified email address.
FaxNumber | BSTR | Should comply with the international E.123, with an optional bit string formatted according to T.30.
Integer | long |
Interval | long | Value represents interval of time, in seconds. -1 = Unlimited.
List | VARIANT | Value is an ordered sequence of strings. The VARIANT contains a SAFEARRAY of BSTRs.
Method |  | Identifies a function available on this COM object.
NetAddress | BSTR | A network address, represented as a string using the following syntax: <NetAddress>::=<AddrType>":"<AddrValue>
OctetString | VARIANT | Values are uninterpreted byte strings. The VARIANT contains a SAFEARRAY of unsigned chars.
Path | BSTR | Value is a file system path.
PhoneNumber | BSTR |
PostalAddress | BSTR | Value is a postal address, typically 6 lines of 30 chars each. Carriage return characters are allowed. The following format is recommended: Line 1: Name Line 2: Street Address or Post Office Box Number Line 3: State or Province Name Line 4: Postal Code Line 5: Country Name
SmallInterval | long | Value represents interval of time in milliseconds.
String | BSTR |
Time | DATE |

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsProperty, IADsSyntax, ADSI Property Object


ADSI User Object

The ADSI User Object represents an individual end-user account on a network. The user object makes it possible to administer individual user accounts and their associated information across various network environments using a single set of interfaces.

Interfaces typically supported on ADSI User Object | Description
IUnknown | Universal COM object management and interface query methods.
IDispatch | Automation methods for late-bound access to an object's methods and properties.
IADs | Standard Active Directory object management methods.
IADsUser | Management methods for a user object and its persistent properties.

QuickInfo

Windows NT: Use version 4.0 and later.

See Also

IADsUser


ADSI Structure Definitions

Active Directory Service Interfaces methods use the structure definitions defined in the following section.


ADSI Simple Types

typedef HANDLE ADS_SEARCH_HANDLE, *PADS_SEARCH_HANDLE;

typedef LPWSTR ADS_DN_STRING;

typedef LPWSTR ADS_CASE_EXACT_STRING;

typedef LPWSTR ADS_CASE_IGNORE_STRING;

typedef LPWSTR ADS_PRINTABLE_STRING;

typedef LPWSTR ADS_NUMERIC_STRING;

typedef DWORD ADS_BOOLEAN;

typedef DWORD ADS_INTEGER;

typedef SYSTEMTIME ADS_UTC_TIME, *PADS_UTC_TIME;

typedef LARGE_INTEGER ADS_LARGE_INTEGER, *PADS_LARGE_INTEGER;

typedef LPWSTR ADS_OBJECT_CLASS, *PADS_OBJECT_CLASS;

See Also

ADS_OCTET_STRING , ADS_PROV_SPECIFIC


ADS_ATTR_DEF

The ADS_ATTR_DEF structure specifies information about an attribute definition.

typedef struct  _ads_attr_def
    {
    LPWSTR pszAttrName;
    ADSTYPE dwADsType;
    DWORD dwMinRange;
    DWORD dwMaxRange;
    BOOL fMultiValued;
    }    ADS_ATTR_DEF, *PADS_ATTR_DEF;

Members

pszAttrName
Pointer to a stream containing the name of the attribute.
dwADsType
Data type of the attribute as defined by ADSTYPE.
dwMinRange
Minimum legal range for this attribute.
dwMaxRange
Maximum legal range for this attribute.
fMultiValued
Whether or not this attribute takes more than one value.


ADS_ATTR_INFO

The ADS_ATTR_INFO structure specifies the information about operations on the named attribute in the property cache.

typedef struct  _ads_attr_info
    {
    LPWSTR pszAttrName;
    DWORD dwControlCode;
    ADSTYPE dwADsType;
    PADSVALUE pADsValues;
    DWORD dwNumValues;
    }    ADS_ATTR_INFO, *PADS_ATTR_INFO;

Members

pszAttrName
Pointer to a stream containing the name of the attribute.
dwControlCode
One of the ADS_ATTR_* constants that control what operation to perform on the attribute.
dwADsType
Data type of the attribute as defined by ADSTYPE.
pADsValues
Pointer to an array of ADSVALUE structures containing values for the attribute.
dwNumValues
Size of the pADsValues array.

Remarks

Memory for the array of ADSVALUE structures is not allocated with this structure.


ADS_OBJECT_INFO

The ADS_OBJECT_INFO structure specifies the information about a directory service object.

typedef struct _ads_object_info {
    LPWSTR pszRDN;
    LPWSTR pszObjectDN;
    LPWSTR pszParentDN;
    LPWSTR pszSchemaDN;
    LPWSTR pszClassName;
} ADS_OBJECT_INFO, *PADS_OBJECT_INFO;

Members

pszRDN
Relative distinguished name (relative path) of the directory services object.
pszObjectDN
Distinguished name (path) of the directory services object.
pszParentDN
Distinguished name of the parent object.
pszSchemaDN
Distinguished name of the class factory used to create this object.
pszClassName
Name of the class of which this object is an instance.


ADS_OCTET_STRING

The ADS_OCTET_STRING structure contains a string of one-byte characters.

typedef {
    DWORD dwLength;
    LPBYTE lpValue;
    }    ADS_OCTET_STRING, *PADS_OCTET_STRING;

Members

dwLength
The size of the character array.
lpValue
Pointer to array of one-byte characters.

Remarks

The ADS_OCTET_STRING structure contains only a pointer to the character string itself. Memory for the string must be allocated separately.


ADS_PROV_SPECIFIC

The ADS_PROV_SPECIFIC structure contains a provider-specific character string.

typedef {
    DWORD dwLength;
    LPBYTE lpValue;
    }    ADS_PROV_SPECIFIC, *PADS_PROV_SPECIFIC;

Members

dwLength
The size of the character array.
lpValue
Pointer to array of one-byte characters.

Remarks

The ADS_PROV_SPECIFIC structure contains only a pointer to the character string itself. Memory for the string must be allocated separately.


ADS_SEARCH_COLUMN

Specifies the contents of a search column in the query returned from the directory service database.

typedef struct ads_search_column
    {
    LPWSTR pszAttrName;
    ADSTYPE dwADsType;
    PADSVALUE pADsValues;
    DWORD dwNumValues;
    HANDLE hReserved;
    }    ADS_SEARCH_COLUMN;

typedef struct ads_search_column __RPC_FAR *PADS_SEARCH_COLUMN;

Members

pszAttrName
Pointer to a string containing the name of the attribute whose values are contained in the current search column.
dwADsType
Value from the ADSTYPE enumeration indicating how the attribute values are to be interpreted.
pADsValues
Array of ADSVALUE structures containing values of the attribute in the current search column for the current row.
dwNumValues
Size of the pADsValues array.
hReserved
Reserved for future use. Must be NULL.

Remarks

The ADS_SEARCH_COLUMN structure contains only a pointer to the array of ADSVALUE structures. Memory for the structure must be allocated separately.


ADS_SEARCHPREF_INFO

The ADS_SEARCHPREF_INFO structure specifies the query preferences.

typedef struct ads_searchpref_info{
    ADS_SEARCHPREF dwSearchPref;
    ADSVALUE vValue;
    ADS_STATUS dwStatus;
} ADS_SEARCHPREF_INFO, *PADS_SEARCHPREF_INFO, *LPADS_SEARCHPREF_INFO;

Members

dwSearchPref
One of the ADS_SEARCHPREF enumeration values.
vValue
Value of the search preference using the ADSVALUE structure.
dwStatus
One of the ADS_STATUS enumeration values.


ADS_SORTKEY

The ADS_SORTKEY structure specifies information about sorting a query.

typedef struct  _ads_sortkey
    {
    LPWSTR pszAttrName;
    LPWSTR pszReserved;
    BOOLEAN fReverseOrder;
    }    ADS_SORTKEY, *PADS_SORTKEY;

Members

pszAttrName
Pointer to a stream containing the name of the attribute.
pszReserved
Reserved for future use.
fReverseOrder
Reverse the order of the sorted results.


ADSVALUE

The ADSVALUE structure contains a value specified as an ADSI data type. These types are defined in the preceding ADSI Simple Types.

typedef struct _adsvalue {
    ADSTYPE dwType;
    union {
        ADS_DN_STRING             DNString;
        ADS_CASE_EXACT_STRING     caseExactStrVal;
        ADS_CASE_IGNORE_STRING    caseIgnoreStrVal;
        ADS_PRINTABLE_STRING      printableStrVal;
        ADS_NUMERIC_STRING        numericStrVal;
        ADS_BOOLEAN               boolVal;
        ADS_INTEGER               intVal;
        ADS_OCTET_STRING          octetStrVal;
        ADS_UTC_TIME              utcTimeVal;
        ADS_LARGE_INTEGER         largeIntVal;
        ADS_OBJECT_CLASS          ClassName;
        ADS_PROV_SPECIFIC         provSpecificVal;
    };
} ADSVALUE, *PADSVALUE, *LPADSVALUE;

Members

dwType
Data type to be used to interpret the union member of the structure. Values of this member are taken from the ADSTYPE enumeration.
dnStrVal
String identifying the distinguished name (path) of a directory service object defined by type ADS_DN_STRING.
caseExactStrVal
String to be interpreted case-sensitively defined by type ADS_CASE_EXACT_STRING.
caseIgnoreStrVal
String to be intepreted without regard to case defined by type ADS_CASE_IGNORE_STRING.
printableStrVal
Displayable or printable string defined by type ADS_PRINTABLE_STRING.
numericStrVal
Numerals to be interpreted as text defined by type ADS_NUMERIC_STRING.
boolVal
Boolean value defined by type ADS_BOOLEAN.
intVal
Integer value defined by type ADS_INTEGER.
octetStrVal
An octet string defined by type ADS_OCTET_STRING.
utcTimeVal
Time specified as Coordinated Universal Time (UTC) defined by type ADS_UTC_TIME.
largeIntVal
Long integer value defined by type ADS_LARGE_INTEGER.
ClassName
Class name string defined by type ADS_OBJECT_CLASS.
provSpecificVal
Provider-specific structure defined by type ADS_PROV_SPECIFIC.


ADSI System Providers

The Active Directory Service Interfaces SDK includes several system implementations. The features and capabilities of each underlying directory service influence the implementation of the Active Directory Service Interfaces. Accompanying an ADSI provider implementation is a list of notes about directory service objects and their interface and method implementations.

LDAP
An LDAP-compatible (where LDAP is Lightweight Directory Access Protocol) namespace implementation. See ADSI LDAP Provider.
NDS
An NDS-compatible (where NDS is Netware Directory Service) namespace implementation.
NWCOMPAT
A NetWare 3.x-compatible namespace implementation.
WinNT
A Windows NT-compatible namespace implementation. See ADSI WinNT Provider.


ADSI LDAP Provider

The Active Service Directory Interfaces SDK supplies a system implementation of the Lightweight Directory Access Protocol (LDAP) that provides access to LDAP directory services from different vendors. The ProgID for this provider is "LDAP:". When you use this ProgID as the first component in any ADsPath string, you are using the adsldp.dll.


LDAP ADsPath

An ADsPath string for Microsoft's LDAP provider starts either with "LDAP: <>" or "LDAP://<>" where "<>" is an LDAP provider path.

An LDAP provider path is an ldap server name followed by zero or more component names separated with forward slashes in the ADsPath format. After the second component that identifies an ldap server, the remaining components can be listed in either a top-down or bottom-up hierarchy. Whichever way you first specify is carried through by ADSI ADsPath names. More information about the distinguished name notation used by LDAP-compliant directory services can be found at ftp://ds.internic.net/rfc/rfc1779.txt.

For example, the following list of ADsPath names are valid:

LDAP://ldapsvr/O=Internet/DC=COM/DC=MSFT/DC=DEV/CN=TopHat
LDAP://ldapsvr/CN=TopHat,DC=DEV,DC=MSFT,DC=COM,O=Internet
LDAP://MyDomain.microsoft.com/CN=TopHat,DC=DEV,DC=MSFT,DC=COM,O=Internet
LDAP://CN=TopHat,DC=DEV,DC=MSFT,DC=COM,O=Internet

Reserved characters for an ADsPath string in the LDAP provider include:

Special Characters |  |
Double quote | " | Delimiter of ADsPath.
Backward slash | \ | Escape character, used to precede special characters to signify they should be used as literals.
Comma, Forward slash Semicolon | , / ; | Separates component from class specifier in last component.
Equal | = | Joins a naming class specifier with a component, for example, "OU=Finance".


Browsing an LDAP Directory Service

Browsing an LDAP directory service requires that you know the root path of the server to browse. Unlike other directory services, LDAP does not have a standard mechanism to publish which servers are available on a net that can be used by ADSI to enumerate the list as a container object.

Once you have supplied the root server path, you can browse as with any other ADSI provider.


Supplying Credentials

Microsoft's LDAP implementation uses the lnFlags parameter in IADsOpenDSObject::OpenDSObject and the function ADsOpenObject to allow clients to request specific binding options when opening an object. These flags are described below:

lnFlags
[in] Flags that define the binding options.

In the following table, SSPI is the Microsoft® Security Support Provider Interface, an API set designed to support security services across a network. SSL is the Secure Sockets Layer, an public domain protocol for authenticating private communications over the Internet.

There are two flags defined for lnFlags:
FLAG | Value
ADSI_USE_SECURE_AUTHENTICATION | 0x00000001
ADSI_USE_ENCRYPTION | 0x00000010

Case Flags Action
UserName and Password Specified. SECURE_

AUTHENTICATION = 1

ENCRYPTION = 1

 Simple bind over SSL (secure authentication over a secure channel).
UserName and Password Specified. SECURE_

AUTHENTICATION = 1

ENCRYPTION = 0

 As above, except that if the ldap_open call to the SSL port fails, it calls SSPI with the user name and password.
UserName and Password Specified. SECURE_

AUTHENTICATION = 0

ENCRYPTION = 1

 Simple bind over SSL.
UserName and Password Specified. SECURE_

AUTHENTICATION = 0

ENCRYPTION = 0

 Simple bind.
Default Credentials (UserName and Password NULL). SECURE_

AUTHENTICATION =

0 or 1

ENCRYPTION = 1

 Fail.
Default Credentials (UserName and Password NULL). SECURE_

AUTHENTICATION = 1

ENCRYPTION = 0

 Use SSPI. If that fails, fail.
Default Credentials (UserName and Password NULL). SECURE_

AUTHENTICATION = 0

ENCRYPTION = 0

 Use SSPI. If that fails, do a simple bind with NULL, NULL.

If possible, ADSI uses existing connections. Therefore, ADSI client applications should always keep one object open to prevent having to do binds and rebinds on subsequent calls. Any attempt to bind following the first must, like the first, supply a new password.

Note ADSI maintains the schema cache in memory on the server until the reference count on the cache = zero. To update the schema,


LDAP Syntax Objects

The following table lists the syntax objects supported by the LDAP schema object and found when enumerating the schema objects for syntax objects.

LDAP Syntax | ADSI Syntax (Automation)
Boolean | VT_BOOL
Counter | VT_I4
ADsPath | VT_BSTR
EmailAddress | VT_BSTR
FaxNumber | VT_BSTR
Integer | VT_I4
Interval | VT_I4
List | VT_VARIANT (VT_BSTR | VT_ARRAY)
NetAddress | VT_BSTR
OctetString | VT_VARIANT
Path | VT_BSTR
PhoneNumber | VT_BSTR
PostalAddress | VT_BSTR
SmallInterval | VT_I4
String | VT_BSTR
Time | VT_DATE


LDAP Schema

As with all schema objects, ADSI architecture defines the LDAP schema container object in the root node. For example, if you use a browser that can bind to a schema object, such as adsvw.exe, you would bind to the schema container object in the following way:

Under the LDAP implementation, you must already know the name of the LDAP server to which you want to bind. You cannot browse through a list of all the LDAP servers on the network because there is no underlying network call that supports that information.

Binding to this example LDAP schema object, you can display the list of more than a hundred schema class objects, hundreds of property objects, and a dozen or so syntax objects. The following figure shows the beginning of the expanded list of schema class objects. The right pane highlights the IADsClass::OptionalProperties property selection, displaying its contents as a Property Value.


LDAP Custom Properties

The following flags are valid for the UserFlags attribute on NTDS:

ADSI Schema Class | Custom Property | ADsType
User | UserFlags | Integer 0x0001 UF_SCRIPT 0x0002 UF_ACCOUNTDISABLE 0x0008 UF_HOMEDIR_REQUIRED 0x0010 UF_LOCKOUT 0x0020 UF_PASSWD_NOTREQD 0x0040 UF_PASSWD_CANT_CHANGE 0x0100 UF_TEMP_DUPLICATE_ACCOUNT 0X0200 UF_NORMAL_ACCOUNT 0X0800 UF_INTERDOMAIN_TRUST_ACCOUNT 0X1000 UF_WORKSTATION_TRUST_ACCOUNT 0X2000 UF_SERVER_TRUST_ACCOUNT 0x10000 UF_DONT_EXPIRE_PASSWD 0X20000 UF_MNS_LOGON_ACCOUNT #define UF_SETTABLE_BITS ( UF_SCRIPT | UF_ACCOUNTDISABLE | UF_LOCKOUT | UF_HOMEDIR_REQUIRED | UF_PASSWD_NOTREQD | UF_PASSWD_CANT_CHANGE | UF_ACCOUNT_TYPE_MASK | UF_DONT_EXPIRE_PASSWD | UF_MNS_LOGON_ACCOUNT) These are defined in LMACCESS.H.


ADSI WinNT Provider

To access the directory services of a Windows NT 4.0 node on your network using the Microsoft implementation of Active Directory Service Interfaces, you must have ADSI installed. ADSI registers the case-sensitive programmatic identifier (progID) "WinNT" so that all ADsPath names that begin with "WinNT" will be routed to this implementation.

The WinNT provider object definitions follow the ADSI Provider specifications as described in Microsoft's Platform SDK, Networking and Distributed Services, Active Directory Service Interfaces, ADSI for Providers.

Implementation notes specific to the WinNT provider include:

  • WinNT ADsPath Syntax
  • Browsing a WinNT Directory Service
  • WinNT Schema
  • WinNT Custom Properties
  • List of WinNT Schema Class Mandatory and Optional Properties


WinNT ADsPath Syntax

An ADsPath string for Microsoft's WinNT provider starts either with "WinNT:" or "WinNT://<DomainName>".

What follows that component is a distinguished name that consists of one or more components that each identify a level of the WinNT object hierarchy, described in WinNT Schema.

For example, the following list of ADsPath names are valid:

"WinNT://MyDomain/MyServer/John"
"WinNT://MyDomain/MyServer/User"
"WinNT://MyDomain/JohnSmith"
"WinNT://MyDomain/User"
"WinNT://MyDomain/Administrator"
"WinNT://MyDomain/Group"
"WinNT://MyDomain/MyComputer/MyPrintQueue/"
"WinNT://MyDomain/MyComputer/Printer"


Browsing a WinNT Directory Service

To browse through a WinNT Directory Service using a browser such as the Active Directory VB Browser that comes with the ADSI SDK as a VB sample application, you can start with the "WinNT:" namespace object and expand it. You do not have to know the name of a specific server to view it on your network.

The figure below shows an expanded version of an ADSI WinNT provider namespace object.

In this view, the WinNT namespace object contains the domain object "MYDOMAIN", which contains a computer object "MYCOMPUTER", which contains a user object "Administrator", a service object "EventLog", and a group object "Users". (The list of contents for the computer object continues beyond what is visible in this screen.) What you see when you look at your expanded WinNT namespace object is one node for every Windows NT domain, server, workstation, or computer on the net. For further information about these object types, see WinNT Schema.


WinNT Schema

The WinNT provider represents the underlying directory service by defining about a dozen ADSI object types such as Users, Computers, Domains, Groups, and Services. To find out which properties and classes are supported on each of these object types, you can bind to and enumerate the schema container object of the specific WinNT server or workstation on your network. For example, the following figure uses a browser view to show the schema container object at "WinNT://MyDomain/schema". By double-clicking on the schema object, the browser expands the view to show all the class, property, and syntax objects.

In the preceding figure, the left pane highlights the last class object "User" followed by a list of all the property objects in the schema container. The right pane's Properties list box shows "OptionalProperties" for the User class and lists its value as "Description#FullName#AccountExpirationDate#", etc. These are the properties that may, but don't have to be, defined before an IADs::SetInfo writes the property information from the property cache out to the WinNT directory service. For further information, see WinNT Schema Class Mandatory and Optional Properties.

The IADsClass methods Containment and PossibleSuperiors define the containment relationships among the object classes. The Containment property defines which objects this object can contain and the PossibleSuperiors property defines which objects can contain this object. The following table shows the WinNT object hierarchy as defined in the schema.

Object Class Hierarchy | Definition of Object
WinNT Namespace | Top-level container object.
Domains | Domain servers.
Users | User accounts.
Groups | Administrator-assigned groups that manage access rights.
Collection of Users through IADsMembers |
Other groups through IADsMembers |
Computers | Some type of server or workstation.
PrintQueues | Print queues on a print spooler.
Collections of PrintJobs | Print jobs queued on a print spooler.
Services | Any computer software that performs a service.
FileServices | Session connections and resource management.
FileShares | Directory file share points.
Collections of Resources | Resources within the directory service, such as a groups, print queues, or computer servers.
Collections of Sessions | Active connections for any file service.
Users | User accounts.
Groups | Administrator-assigned groups that manage access rights.


WinNT Custom Properties

The WinNT provider supplies the following custom properties with its ADSI implementation.

ADSI Schema Class | Custom Property | ADsType
User | UserFlags | Integer 0x0001 UF_SCRIPT 0x0002 UF_ACCOUNTDISABLE 0x0008 UF_HOMEDIR_REQUIRED 0x0010 UF_LOCKOUT 0x0020 UF_PASSWD_NOTREQD 0x0040 UF_PASSWD_CANT_CHANGE 0x0100 UF_TEMP_DUPLICATE_ACCOUNT 0X0200 UF_NORMAL_ACCOUNT 0X0800 UF_INTERDOMAIN_TRUST_ACCOUNT 0X1000 UF_WORKSTATION_TRUST_ACCOUNT 0X2000 UF_SERVER_TRUST_ACCOUNT 0x10000 UF_DONT_EXPIRE_PASSWD 0X20000 UF_MNS_LOGON_ACCOUNT #define UF_SETTABLE_BITS ( UF_SCRIPT | UF_ACCOUNTDISABLE | UF_LOCKOUT | UF_HOMEDIR_REQUIRED | UF_PASSWD_NOTREQD | UF_PASSWD_CANT_CHANGE | UF_ACCOUNT_TYPE_MASK | UF_DONT_EXPIRE_PASSWD | UF_MNS_LOGON_ACCOUNT) These are defined in LMACCESS.H.
User | AccountDisabled | Boolean
User | PasswordAge | Time
User | PasswordExpired | Time

You access custom properties through the IADs::Get and IADs::Put methods.


WinNT Schema Class Mandatory and Optional Properties

The WinNT provider specifies which properties of an object class are mandatory and which are optional in its schema class definition. You can see these divisions by using a browser such as adsvw.exe that displays the contents of the IADs properties MandatoryProperties and OptionalProperties.

Schema Class Object, Interfaces | ADSI MetaInterface and WinNT Provider Specific Properties Supported (*=MandatoryProperties, otherwise OptionalProperties) (+=Provider-Specific)
Computer Object | Division Owner OperatingSystem OperatingSystemVersion Processor ProcessorCount
Domain Object | MinPasswordLength
FPNWFileService Object IADsService IADsFileService | HostComputer DisplayName Version ServiceType StartType Path ErrorControl LoadOrderGroup Description MaxUserCount
FPNWFileShare Object IADsFileShare | CurrentUserCount HostComputer *Path *MaxUserCount
FPNWResource Object | User Path LockCount
FPNWSession Object | User Computer ConnectTime
FileService Object IADsService IADsFileService | HostComputer DisplayName Version ServiceType StartType Path ErrorControl LoadOrderGroup Description MaxUserCount ServiceAccountName Dependencies
FileShare Object | CurrentUserCount Description HostCompute *Path *MaxUserCountr
Group Object | Description
Namespace Object | IADs – all methods and properties.
PrintJob Object IADsPrintJob IADsPrintJobOperations | HostPrintQueue User TimeSubmitted TotalPages Size Description Priority StartTime UntilTime Notify TimeElapsed PagesPrinted Position
PrintQueue Object | HostComputer *Description Location StartTime UntilTime DefaultJobPriority Priority BannerPage PublishPoint CommonName Action *PrinterPath *Model *Datatype *PrintProcessor *PrintDevices
Resource Object | User Path LockCount
Service Object | HostComputer LoadOrderGroup ServiceAccountName Dependencies *StartType *ServiceType *DisplayName *Path *ErrorControl
Session Object | User Computer ConnectTime IdleTime
User Object | Description FullName AccountExpirationDate +UserFlags LoginWorkstations MaxLogins PasswordExpired LastLogin LastLogoff HomeDirectory Profile LoginScript


Glossary

You should be familiar with the following terms before reading the rest of this guide:

Automation
A way to manipulate objects within a scripting environment. Methods within an Automation environment are typically accessed through the IDispatch interface.
Active Directory Service Interfaces (ADSI)
A set of specifications of COM objects and interfaces. Administrators and ISVs can use the ADSI objects to perform common administrative operations, such as adding new users or managing a print queue.
attribute
A generic object property defined in a directory service schema. Attributes and classes (see class) are defined independently, and a single attribute may be characteristic of multiple classes. In the context of this document "property" and "attribute" can be used interchangeably.
attribute instance
A specific occurrence of an attribute defined in a directory service schema. For example, "John Smith" or "Jane Doe" would be instances of the Name attribute..
class
In ADSI, a formal description of a discrete, identifiable type of object that can be stored in a directory service. For example, User, Print-Queue, and Group are all classes. These classes, which act as templates, are stored within a directory service's schema.
class instance
A specific occurrence of a class defined in a directory service schema. For example, User objects with the attributes "John Smith" or "Jane Doe" would represent instances of the User class.
collection
A group of objects that can be indexed, either numerically like an array or by name. ADSI containers support interface methods for manipulating collections.
Component Object Model (COM)
A programming model that defines the way in which software components communicate with and provide services to one another, regardless of where the components reside. ADSI defines a set of COM interfaces (and related APIs) for working with directory service objects.
component
An object that conforms to the component object model (COM). In ADSI, a component is a top-level objects that can be instantiated and then used to access dependent objects.
container
Any ADSI object that supports one or more of the methods of the IADsContainer interface. An ADSI container can hold one or more other directory service objects.
content rules
Criteria defining valid content for class instances for directory service objects.
directory information tree (DIT)
A hierarchical representation of a directory service in which the nodes represent class instances and lines connecting the nodes indicate parent-child relationships.
DIT
See Directory Information Tree.
directory service (DS)
Persistently stored tables containing the attributes and locations of objects within a namespace (see Namespace). A directory service also provides services to manage the data in the tables.
enumerator
An object that supports the IEnumVARIANT interface, which provides a Next method to enumerate objects in a collection.
Interface
In ADSI, a COM interface. Each COM interface defines a set of related member functions that provide access to COM objects. ADSI defines and implements a set of COM interfaces and related APIs for providing access to directory service objects.
LDAP
The Lightweight Directory Access Protocol. The standard Internet communications protocol used to communicate with the Windows NT Directory Service. Both Version 2 and Version 3 of LDAP are supported.
namespace
A directory service that uses a particular syntax for naming conventions. Examples are:
Windows NT
"//MyWorkstation/MyName"
LDAP
"//MyServer/C=US/O=MS/CN=MyName"
NDS
"//Planets/O=Mars/OU=DEV"
NetWare 3.x
"//Docs/MyNw3xPrinter"
NDS
NetWare Directory Services.
object
In ADSI, a COM object that implements one or more interfaces. See ADSI Object Definitions. For more information on COM, see the Microsoft Platform SDK.

The basic named unit of storage in a directory service. A directory service object is defined in the directory service's schema by a class object and a group of attribute objects referenced by the class object. See Attribute, Class and Schema.

property
A value that can be read or written. Properties are associated with specific interfaces on an object.
provider
A vendor who supplies an implementation of the ADSI objects for a particular namespace.
query
A request to a directory service to return the location of one or more specified directory service objects.
schema
The rules and definitions that specify the content and relationships among a set of objects in a directory service. In ADSI, the schema management interfaces supply a means of defining types of COM objects known as schema classes, their properties, and the syntaxes those properties use.
trustee
A user with access rights to an object.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.