Поделиться через


Setting Folder-Level Permissions (Exchange Web Services)

Topic Last Modified: 2009-07-16

Starting with Microsoft Exchange Server 2007 Service Pack 1 (SP1), you can use folder-level permissions to enable a delegator to control a delegate's access to specific folders. A delegator, also known as a principal, can assign folder-level permissions to delegates to allow delegates to perform actions on the principal's behalf. For information about delegate access, see Exchange Web Services and Delegate Access.

Folder-level permissions are supported in the following operations:

  • CreateFolder
  • GetFolder
  • UpdateFolder
  • SyncFolderHierarchy

Note

Setting folder-level permissions with Exchange Web Services is not supported in the initial release version of Microsoft Exchange Server 2007.

A principal can configure folder-level permissions to do the following:

  • Grant, deny, and edit the permissions of a user or security group to a specified folder through role-based permission levels and a combination of individual member permissions.
  • Remove a user or security group from the permission set of a folder.
  • Configure default and anonymous sharing permissions on a specified folder.

Note

Individual permissions can only be set on non-Calendar folders. If a client uses an individual permission to call CreateFolder or UpdateFolder against a Calendar folder, the ErrorCannotSetNonCalendarPermissionOnCalendarFolder error code will be returned in the response.

You can set individual permissions on a folder, or you can set a permission level on a folder. The following are the individual permissions that you can set:

  • Can Create
  • Can Read
  • Can Create Subfolders
  • Is Folder Owner
  • Is Folder Contact
  • Is Folder Visible
  • Edit Items
  • Delete Items

The following table lists the permission levels that you can set on mailbox folders and Calendar folders. If you try to set a Calendar-only permission level on a non-Calendar folder, an ErrorCannotSetCalendarPermissionOnNonCalendarFolder error will be returned in the response.

Mailbox folder and Calendar folder permission levels

Permission Level Mailbox Folder Calendar Folder

None

Yes

Yes

Owner

Yes

Yes

PublishingEditor

Yes

Yes

Editor

Yes

Yes

PublishingAuthor

Yes

Yes

Author

Yes

Yes

NoneditingAuthor

Yes

Yes

Reviewer

Yes

Yes

Contributor

Yes

Yes

Custom

Yes

Yes

FreeBusyTimeOnly

No

Yes

FreeBusyTimeAndSubjectAndLocation

No

Yes

The following table shows which individual permissions apply to each permission level.

Permissions by permission level

Permission Level Can Create Can Read Can Create Sub Folders Is Folder Owner Is Folder Contact Is Folder Visible Edit Items Delete Items

None

Not Set

Not Set

Not Set

Not Set

?

?

None

None

Owner

true

true

true

true

true

true

All

All

PublishingEditor

true

true

true

Not Set

Not Set

true

All

All

Editor

true

true

Not Set

Not Set

Not Set

Not Set

All

All

PublishingAuthor

true

true

true

Not Set

Not Set

true

Own

Own

Author

true

true

Not Set

Not Set

Not Set

true

Own

Own

NoneditingAuthor

true

true

Not Set

Not Set

Not Set

true

None

Own

Reviewer

Not Set

true

Not Set

Not Set

Not Set

true

None

None

Contributor

true

Not Set

Not Set

Not Set

Not Set

true

None

None

Custom

?

?

?

?

?

?

?

?

Question marks indicate that the flag can be either true or false for that permission level. In Microsoft Office Outlook, when the permission level is set to None, IsFolderContact and IsFolderVisible can be either true or false and the permission level remains unchanged. If changes are made to other individual permission settings, the permission level property also changes.

If a non-Custom permission level is specified in the folder-level permissions request, the individual permission settings should not be specified. If you specify an individual permission when a permission level has been specified, an ErrorInvalidPermissionSettings error will be returned in the response.

If the client has to specify individual settings, you must use the Custom permission level; otherwise, an ErrorInvalidPermissionSettings error will be returned in the response.

Important

Attempts to use CreateFolder and UpdateFolder to set permissions will not succeed unless all the permission settings succeed. The request will fail and will not continue to edit other properties if a set permission attempt fails.

Folder-level permissions work with other Exchange Web Services operations in the following ways:

  • The GetFolder operation will return the permissions that are set on the folder when the AllProperties shape is specified.
  • The SyncFolderHierarchy operation synchronizes PermissionSets.
  • The UpdateFolder operation will fail if multiple Permission entries are provided for the same user. The UpdateFolder response will return the ErrorDuplicateUserIdsSpecified response code.
  • The SetFolderField option of the UpdateFolder operation will overwrite all the permission settings on the folder. The client cannot change the permissions for each user.
  • The DeleteFolderField option of the UpdateFolder operation will delete all the permission settings on the folder.

Note

A delegate who has been given Author-level permissions to the Calendar folder through EWS will receive an error if the principal forwards a meeting request to the delegate. Outlook does not allow the forwarding flag to be set unless the delegate has Editor permissions.

Example

The following code example shows how to set folder-level permissions when a folder is created. The authenticated user grants user3 the Editor permission level on a new folder named NewFolderWithPermissionsSet that is created in the Inbox default folder.

static void CreateFolderLevelPermissions()
{
    // Set the version, credentials, and the Client Access server on ExchangeServiceBinding.
    ExchangeServiceBinding esb = new ExchangeServiceBinding();
    esb.RequestServerVersionValue = new RequestServerVersion();
    esb.RequestServerVersionValue.Version = ExchangeVersionType.Exchange2007_SP1;
    esb.Credentials = new NetworkCredential("username", "password", "domain");
    esb.Url = "https://CAS.example.com/ews/exchange.asmx";

    // Create user identifier.
    UserIdType user = new UserIdType();
    user.PrimarySmtpAddress = "user3@example.com.com";

    // Set the folder permission level to Editor.
    PermissionSetType permissionSet = new PermissionSetType();
    permissionSet.Permissions = new PermissionType[] { new PermissionType() };
    permissionSet.Permissions[0].PermissionLevel = PermissionLevelType.Editor;
    permissionSet.Permissions[0].UserId = user;

    FolderType folder = new FolderType();
    folder.DisplayName = "NewFolderWithPermissionsSet";
    folder.PermissionSet = permissionSet;

    // Specify the target folder.
    DistinguishedFolderIdType inbox = new DistinguishedFolderIdType();
    inbox.Id = DistinguishedFolderIdNameType.inbox;
    TargetFolderIdType targetFolder = new TargetFolderIdType();
    targetFolder.Item = inbox;

    CreateFolderType request = new CreateFolderType();
    request.Folders = new FolderType[] { folder };
    request.ParentFolderId = targetFolder;

    try
    {
        // Send the request and get the response.
        CreateFolderResponseType response = esb.CreateFolder(request);

        // Get the response messages.
        ResponseMessageType[] rmta = response.ResponseMessages.Items;

        // Cast to appropriate response message type.
        if (((FolderInfoResponseMessageType)rmta[0]).ResponseClass == ResponseClassType.Success)
        { 
            // Continue.
        }
        
    }

    catch 
    {
        // Handle errors.
    }
}

This code example was created by using proxy objects that were created by using Microsoft Visual Studio 2005 and Exchange Web Services in Exchange 2007 SP1.

See Also

Other Resources

Delegate Access Tasks