IADsOpenDSObject::OpenDSObject

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

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

Parameters

lpszDNName

[in] ADsPath of the ADSI object.

lpszUserName

[in] The user name to be used for securing permission from the namespace server. See the following Remarks section for the name formats supported by the LDAP and WinNT providers.

lpszPassword

[in] The password to be used for securing permission from the namespace server.

lnReserved

[in] Authentication flags used to define the binding options. For more information, see ADS_AUTHENTICATION_ENUM.

ppOleDsObj

[out] Indirect 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 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 or NWCOMPAT object will ignore the lnReserved flag.

The IADsOpenDSObject::OpenDSObject method maintains the authenticated and encrypted user credentials in the cache. Such 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 do the caching.

To use the cached credentials, set the lpszPassword parameter to null and leave the lpszUserName unchanged in any subsequent calls of OpenDSObject. The following code segment illustrates this point.

Dim dso As IADsOpenDSObject
Dim obj1, obj2 As IADs

Set dso = GetObject("LDAP:")

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

' Do something with the bound object, obj1
MsgBox obj1.Class

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

MsgBox obj2.Class

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 machine must be on an Active Directory domain. To attempt a serverless binding from a workstation, you must bind as a domain user.

In order 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.

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

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

• The name of a user account, such as jsmith.
• The Windows NT® 4.0 style user name, such as Fabrikam\jsmith.

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

• The name of a user account, such as jsmith. To use a user name by itself, you must set only the ADS_SECURE_AUTHENTICATION flag in the lnReserved parameter.
• The user path from a previous version of Windows NT, such as Fabrikam\jsmith.
• Distinguished Name, such as CN=Jeff Smith, OU=Sales, DC=Fabrikam, DC=Com. To use a DN, the lnReserved parameter must be zero or it must include the ADS_USE_SSL flag
• User Principal Name (UPN), such as jsmith@Fabrikam.com. To use a UPN, you must assign the appropriate UPN value for the userPrincipalName attribute of the targeted user object

Example Code [Visual Basic]

The following Visual Basic code snippet illustrates 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
 
Set dso = GetObject("WinNT:")
Set domain = dso.OpenDSObject("WinNT://Fabrikam", "Administrator", "secret", ADS_SECURE_AUTHENTICATION)

Example Code [C++]

The following is a C++ code snippet that uses IADsOpenDSObject to open an Active Directory object through the LDAP provider.

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

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with DSClient).
  Windows 95/98: Requires Windows 95 or later (with DSClient).
  Header: Declared in Iads.h.

See Also

ADS_AUTHENTICATION_ENUM, ADsOpenObject, IADsOpenDSObject, IADsOpenDSObject, IDispatch