Understanding the Active Directory RPC APIs

Before SDS.AD, Active Directory programmers were forced into different camps based on the programming language they used. The original design of the directory services APIs had some features of Active Directory available via LDAP, and others were available only by RPC calls. The LDAP features were (for the most part) available to the higher-level languages because they could use ADSI with the LDAP provider. However, the RPC calls were designed for C++ users only. While some of these APIs got explicit ADSI wrappers (for example, DsCrackNames and IADsNameTranslate), many did not.

As such, the high-level languages were second-class citizens. This tradition continued with .NET Framework version 1.x, as SDS really just wrapped ADSI functionality. While we had the ability to access the other APIs via P/Invoke, they were not packaged neatly for us.

The key design challenge for the SDS.AD namespace was to find a way to marry the LDAP and RPC functionality together into a cohesive design. In our opinion, this design is quite successful and is leaps and bounds better than what we had before or what we would likely have cobbled together on our own with a bunch of P/Invoke statements.

The purpose of this section is to briefly overview some of the other Active Directory RPC APIs to get a better feel for what they do. Table 9.1 breaks down most of them and categorizes them by use. We also show which ones SDS.AD uses directly.

Table 9.1. Active Directory RPC API Functions

Purpose	RPC function	Wrapped in SDS.AD
These APIs are used to access the Locator services. With them, we can find the current domain, forest, global catalog servers, and all domain controllers. All of these methods allow anonymous credentials.	DsGetDcName	Yes
	DsGetDcOpen	Yes
	DsGetDcNext	Yes
	DsGetSiteName	No
	DsGetDcSiteCoverage	No
	DsGetDcClose	Yes
	NetApiBufferFree	Yes
In order to use a number of the other Ds* APIs, we must have a handle to an RPC session with a domain controller. These APIs are used to bind to the directory and obtain the handle necessary for further Ds* API calls.	DsBind	No
	DsBindWithCred	Yes
	DsBindWithSpn	No
	DsBindWithSpnEx	No
	DsMakePasswordCredentials	Yes
	DsUnBind	Yes
	DsFreePasswordCredentials	Yes
Once we have an established RPC session, we can use the handle we obtained to query for more information or to use utility functions. These methods use an authenticated session and return information that would be difficult to obtain without fairly complicated directory searches.	DsGetDomainControllerInfo	Yes
	DsListDomainsInSite	Yes
	DsListInfoForServer	No
	DsListRoles	Yes
	DsListSites	Yes
	DsListServersInSite	No
	DsListServersForDomainInSite	No
	DsCrackNames	Yes
	DsFreeDomainControllerInfo	Yes
	DsFreeNameResult	Yes

As Table 9.1 shows, SDS.AD uses quite a few of these API calls. We would need to wrap each method ourselves in order to achieve similar functionality. Since we know that this is a lot of work, we have created wrappers for a number of the methods listed in Table 9.1 for you and we included them on this book's web site for download.

Useful Shortcuts for Developers