Directory Services

IADsGroup::Add

The IADsGroup::Add method adds an ADSI object to an existing group.

HRESULT Add( 
  BSTR bstrNewItem
);

Parameters

bstrNewItem: [in] Contains a BSTR that specifies the ADsPath of the object to add to the group. For more information about this parameter, see the Remarks section.

Return Values

The following are the most common return values. For more information about return values, see ADSI Error Codes.

Return Code/Value	Description
S_OK 0	The object was successfully added.
HRESULT_FROM_WIN32(ERROR_DS_NO_SUCH_OBJECT) 2147950640 0x80072030	The object specified by the bstrNewItem parameter cannot be found.
HRESULT_FROM_WIN32(ERROR_OBJECT_ALREADY_EXISTS) 2147947410 0x80071392	The specified object is already a member of the group.

Remarks

If the LDAP provider is used to bind to the IADsGroup object, the same form of ADsPath must be specified in the bstrNewItem parameter. For example, if the ADsPath used to bind to the IADsGroup object includes a server, the ADsPath in the bstrNewItem parameter must contain the same server prefix. Likewise, if a serverless path is used to bind to the IADsGroup object, the bstrNewItem parameter must also contain a serverless path. The exception is when adding or removing a member using a GUID or SID ADsPath. In this case, a serverless path should always be used in bstrNewItem.

You can use a SID in the bstrNewItem parameter to add a security principal to a group through the WinNT provider. For example, the SID of a user, "Fabrikam\jeff", is S-1-5-21-35135249072896, the following statement:

Dim group As IADsGroup
group.Add("WinNT://S-1-5-21-35135249072896")

is equivalent to

Dim group As IADsGroup
group.Add("WinNT://Fabrikam/jeff")

Adding a member using its SID through the WinNT provider is a new feature in Windows 2000 and the DSCLIENT package.

Example Code [Visual Basic]

The following code example shows how to add a user object ("jeff") to the group ("Administrators") on the "Fabrikam" domain, using the WinNT provider.

Dim grp As IADsGroup
Set grp = GetObject("WinNT://Fabrikam/Administrators")
grp.Add ("WinNT://Fabrikam/jeff")

The following code example shows how to add a user object to a group using the LDAP provider.

Dim grp As IADsGroup
On Error GoTo Cleanup

Set grp = GetObject("LDAP://CN=Administrators, CN=Users, DC=Fabrikam, DC=com")
grp.Add("LDAP://CN=Jeff Smith, OU=Sales,DC=Fabrikam,DC=com")

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

Example Code [C++]

The following code example adds an existing user account to the Administrators group.

IADsGroup *pGroup = NULL;
HRESULT hr = S_OK;
LPWSTR adsPath = L"WinNT://Fabrikam/Administrators";
hr = ADsGetObject(adsPath,IID_IADsGroup,(void**)&pGroup);
if(FAILED(hr)) {goto Cleanup;}

// This assumes that the "WinNT://Fabrikam/jeff" user account exists 
// and does not already belong to the Administrators group.

hr = pGroup->Add(_bstr_t("WinNT://Fabrikam/jeff"));
if(FAILED(hr)){goto Cleanup;}

Cleanup:
	if(pGroup)
		pGroup->Release();

	return hr;

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.