IExchangeFolderACLs::HrInsert

The HrInsert method inserts a user as a new member of the ACL with a set of access rights.

HRESULT HrInsert(
  LONG lRights,           
  LPSTR lpszDisplayName,  
  ULONG cbentryid,        
  LPENTRYID lpentryid,    
  LPLONG lplRights        
);
 

Parameters

lRights

Input parameter. Points to the access rights that are requested for the new member.

frightsReadAny

The user can read any message in the folder.

frightsCreate

The user can create a message in the folder.

frightsEditOwned

The user can edit any message that they own in the folder.

frightsDeleteOwned

The user can delete any message that they own in the folder.

frightsEditAny

The user can edit any message in the folder.

frightsDeleteAny

The user can delete any message in the folder.

frightsCreateSubfolder

The user can create a subfolder in the folder.

frightsOwner

The user owns the folder.

frightsContact

The user is the contact person for the folder. Note: This is not part of rightsAll.

rightsNone

The user has no rights in the folder

rightsReadOnly

The user can only read messages in the folder. Equivalent to frightsReadAny.

rightsReadWrite

The user can read or edit any message in the folder. Equivalent to frightsReadAny | frightsEditAny.

rightsAll

The user has all rights on the folder.

lpszDisplayName

Input parameter. Points to a string containing the display name of the new member.

cbentryid

Input parameter. The size, in bytes, of the entry id where lpentryid points.

lpentryid

Input parameter. Points to a MAPI ENTRYID structure containing the address book entry identifier of the user for whom the ACL entry is being created.

lplRights

Output parameter. Points to a LONG value containing the rights granted to the new member of the ACL.

Return Values

See Return Values.

In addition, HrInsert returns E_FAIL if one of the following conditions occur:

An attempt was made to insert a new member before the default rights of the folder.

The current cursor position, as returned by the HrTell method, is ACL_POS_DEFAULT.

An attempt was made to insert a new member before the owner of the folder.

The current cursor position, as returned by the HrTell method, is ACL_POS_CREATOR.

An attempt was made to insert a new member who is already a member of the ACL.

The member identified by the lppentryid parameter is the same as a member identified by looping through the ACL, beginning at ACL_POS_CREATOR by using the HrSeek method, examining the current member using the HrGet method's lppentryid output parameter, until a matching member is found (if the member isn't in the list, the HrTell method returns ACL_PAST_END).

Remarks

If HrInsert returns NOERROR, the new user is inserted into the current position in the ACL, and the current position is advanced. Microsoft Exchange Server reserves the first two members of every ACL for the default access rights of the list and the creator of the list. You can neither insert a member before these two members nor delete either member.

Rights that are granted may not be the same as the rights that were requested because some rights may not be allowed and the Microsoft Exchange Server information store often sets extra bits.

New members have only default rights on the folder. To change that, use the HrModify method.

To obtain the entry identifier for the lpentryid parameter, use the MAPI IAdrBook::ResolveName method.

For more information, see ACLEDIT: Modifying an ACL.

See Also

IExchangeFolderACLs