Directory Services

IADsOpenDSObject::OpenDSObject

The IADsOpenDSObject::OpenDSObject method binds to an ADSI object, using the given credentials, and retrieves an IDispatch pointer on the specified object.

HRESULT OpenDSObject( 
  BSTR lpszDNName,
  BSTR lpszUserName,
  BSTR lpszPassword,
  LONG lnReserved,
  IDispatch** ppOleDsObj
);

Parameters

lpszDNName
[in] The null-terminated Unicode string that specifies the ADsPath of the ADSI object. For more information and examples of binding strings for this parameter, see LDAP ADsPath and WinNT ADsPath. When using the LDAP provider with an ADsPath that includes a specific server name, the lnReserved parameter should include the ADS_SERVER_BIND flag.
lpszUserName
[in] The null-terminated Unicode string that specifies the user name to be used for securing permission from the namespace server. For more information, see the following Remarks section.
lpszPassword
[in] The null-terminated Unicode string that specifies the password to be used to obtain permission from the namespace server.
lnReserved
[in] Authentication flags used to define the binding options. For more information, see ADS_AUTHENTICATION_ENUM.
ppOleDsObj
[out] Pointer to a pointer to an IDispatch interface on the requested object.

Return Values

This method supports the standard return values, including S_OK when the IDispatch interface has been successfully retrieved using these credentials.

For more information and other return values, see ADSI Error Codes.

Remarks

When lnReserved is set, the behavior of OpenDSObject depends on the provider it connects to. High security namespaces may ignore these flags and always require authentication. Binding to any NDS object will ignore the lnReserved flag.

The IADsOpenDSObject::OpenDSObject method maintains the authenticated and encrypted user credentials in the cache. Cached credentials may be used in subsequent operations for binding to any other directory objects. The ADSI client applications should not cache the credentials supplied by the user. Instead, they should rely on ADSI infrastructure to perform caching. To use the cached credentials, lpszPassword and lpszUserName must remain unchanged in any subsequent calls of OpenDSObject. The following code example shows this operation.

Dim dso As IADsOpenDSObject
Dim obj1, obj2 As IADs
Dim szUsername As String
Dim szPassword As String

Set dso = GetObject("LDAP:")

' Insert code securely.

' Supply full credentials to initiate a server connection.
Set obj1 = dso.OpenDSObject( _
	"LDAP://server1/CN=Dept1,DC=Fabrikam,DC=com", _
	szUsername, _
	szPassword, _
	ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)

' Perform an operation with the bound object, obj1
MsgBox obj1.Class

' Bind to another object with the cached user credential.
Set obj2 = dso.OpenDSObject( _
	"LDAP://server1/CN=Dept2,DC=Fabrikam,DC=com", _
	szUsername, _
	szPassword, _
	ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)

MsgBox obj2.Class

The credentials passed to the IADsOpenDSObject::OpenDSObject function are used only with the particular object bound to and do not affect the security context of the calling thread. This means that, in the following code example, the call to IADsOpenDSObject::OpenDSObject will use different credentials than the call to GetObject.

Dim dso As IADsOpenDSObject
Dim obj1, obj2 As IADs
Dim szUsername As String
Dim szPassword As String

Set dso = GetObject("LDAP:")

' Insert code securely.

' Bind using full credentials.
Set obj1 = dso.OpenDSObject( _
	"LDAP://server1/CN=Dept1,DC=Fabrikam,DC=com", _
	szUsername, _
	szPassword, _
	ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)

' Bind to another object with the default credentials.
Set obj2 = GetObject("LDAP://server1/CN=Dept2,DC=Fabrikam,DC=com")

With a serverless binding, the server name, server1, is not stated explicitly. The default server is used instead. Only the LDAP provider supports the serverless binding. To use this feature, the client computer must be on an Active Directory domain. To attempt a serverless binding from a computer, you must bind as a domain user.

For credential caching to work properly, it is important to keep an object reference outstanding to maintain the cache handle. In the example given above, an attempt to open obj2 after releasing obj1 will result in an authentication failure.

The IADsOpenDSObject method uses the default credentials when lpszUserName and lpszPassword are set to NULL.

If Kerberos authentication is required for the successful completion of a specific directory request using the LDAP provider, the lpszDNName binding string must use either a serverless ADsPath, such as "LDAP://CN=Jeff Smith, CN=admin, DC=Fabrikam, DC=com", or it must use an ADsPath with a fully-qualified DNS server name, such as "LDAP://central3.corp.Fabrikam.com/CN=Jeff Smith, CN=admin, DC=Fabrikam, DC=com". Binding to the server using a flat NETBIOS name or a short DNS name, for example, using the short name "central3" instead of "central3.corp.Fabrikam.com", may or may not yield Kerberos authentication.

The ADsOpenObject helper function offers the same features as the IADsOpenDSObject::OpenDSObject method.

With the WinNT provider, you may pass in lpszUserName as one of the following strings:

With the LDAP provider for Active Directory, you may pass in lpszUserName as one of the following strings:

The NWCOMPAT provider does not support this interface. NWCOMPAT users can call WNetAddConnetion2 prior to binding to the object with GetObject when security credentials are required for the bind to succeed.

Example Code [Visual Basic]

The following code example shows how to use IADsOpenDSObject to open the "Administrator" user object on "Fabrikam" with Secure Authentication through the WinNT provider.

Dim dso As IADsOpenDSObject
Dim domain As IADsDomain
Dim szUsername As String
Dim szPassword As String

On Error GoTo Cleanup

' Insert code to securely retrieve the username and password.
 
Set dso = GetObject("WinNT:")
Set domain = dso.OpenDSObject("WinNT://Fabrikam", szUsername, szPassword,_
							ADS_SECURE_AUTHENTICATION)

Cleanup:
	If (Err.Number <> 0 ) Then
		MsgBox("An error has occurred. " & Err.Number)
	End If
	Set dso = Nothing
	Set domain = Nothing

Example Code [C++]

The following code example uses IADsOpenDSObject to open an Active Directory object through the LDAP provider.

IADsOpenDSObject *pDSO = NULL;
HRESULT hr = S_OK;
 
hr = ADsGetObject(L"LDAP:", IID_IADsOpenDSObject, (void**) &pDSO);
if (SUCCEEDED(hr))
{
	IDispatch *pDisp;
	hr = pDSO->OpenDSObject(CComBSTR("LDAP://DC=Fabrikam, DC=com"), 
					 CComBSTR("jeffsmith@Fabrikam.com"),
					 CComBSTR("passwordhere"),
					 ADS_SECURE_AUTHENTICATION, 
					 &pDisp);
	pDSO->Release();
	if (SUCCEEDED(hr))
	{
		IADs *pADs;
		hr = pDisp->QueryInterface(IID_IADs, (void**) &pADs);
		pDisp->Release();
		if (SUCCEEDED(hr))
		{
		// Perform an object manipulation here.
			pADs->Release();
	}
}
}

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Iads.h.

See Also

ADSI Error Codes, ADS_AUTHENTICATION_ENUM, ADsOpenObject, Binding, GetObject, IADsOpenDSObject, IDispatch, LDAP ADsPath, WinNT ADsPath, WNetAddConnetion2