The Outlook Permissions Control | Programming Microsoft Outlook and Microsoft Exchange, Second Edition (DV-MPS Programming)

[Previous] [Next]

The Outlook Team Folders Wizard ships with another control, the Outlook Permissions control, which you can either use as part of the wizard itself or use in the Outlook applications you create. The Team Folders Wizard uses this control in its template administration pages to allow application owners to modify which users have permissions for the Team Folders application.

Since the Outlook Permissions control has an object model, you can reuse the control in your own applications. The Permissions control is best used in Public Folder applications when you're providing a folder home page to a public folder and want users to have the ability to easily change permissions on the application.

The Permissions control requires a user interface. Therefore, you should not use the Permissions control in scenarios that do not require a user interface, such as working with server-side Active Server Pages.

Programming the Outlook Permissions Control

Programming the Outlook Permissions control is quite straightforward. The control properties are usually set at instantiation time in the folder home page in which you're using the control. Since the Outlook team created this control to be localized in multiple languages, a number of the properties allow you to set the labels for the control's user interfaces. Besides these localizable properties, the only properties that we'll look at are InitSucceeded, TargetAdminFolder, and TargetFolder.

NOTE
A key requirement of the Permissions control is that CDO must be installed on the local machine.

Permissions Control Properties

The InitSucceeded property returns a Boolean that specifies whether the control successfully initialized on the Web page. If the user is working offline or doesn't have the correct permissions on the folder, the control will return False for this property. You should check this property in your Web applications that use the Permissions control.

The TargetAdminFolder property specifies the fully qualified path to the administration folder. If you don't set this property, the control will default to the TargetFolder property value with \administration appended.

The TargetFolder property specifies the fully qualified path to the root folder of your application. When you use the Permissions control's Update method, which we'll discuss momentarily, the control starts at the folder you specify in the TargetFolder property and sets permissions for all subfolders under that folder.

Permissions Control Methods

There are four Permissions control methods that you'll want to use in your applications: Add, List, Remove, and Update. When combined, these four methods provide the functionality needed to set, retrieve, and display permissions for your folder.

The Add method invokes an Outlook address book so that the user can select the person for which he wants to add permissions. Once a user is selected, he receives the default permissions selected in the control.

The List method returns the list of users who have permissions on the folder specified in the TargetFolder property. You can specify one of two list types you want returned to you. The first type is a list of the users' display names, separated by semicolons. To receive a list of this type, specify Users or a constant of 1. The second type is a list of the e-mail aliases for the users who have permissions on the folder. To receive a list of this type, specify UserEmail or a constant of 2.

The Remove method will remove the user who is currently selected in the control. After calling this method, you must call the Update method to make your changes permanent.

The Update method, to which you always must pass a constant of 1, will make permanent your changes in the control to the folder contained in the TargetFolder property and all that folder's subfolders. The only exception is the Administration folder, for which all users (except those with Owner or OwnerContact rights) receive Reviewer permissions so that they can read (but not modify) messages in the folder. This is because the Administration folder contains welcome messages, links, and other information in the Welcome page of a Team Folders application.

Example: Permissions Control Web Application

The following Web application shows how you can take advantage of the Outlook Permissions control in your own applications. Note that if you leave the TargetAdminFolder property blank, the Permissions control applies your permissions to all the subfolders of the folder specified in the TargetFolder property. However, if you set the TargetAdminFolder property to some path, the Permissions control will give all the users in the control Reviewer permissions for the administration folder you specify, even if they already have different permissions for that folder. Figure 9-12 shows how you can use this control to update permissions in Public Folders.

click to view at full size.

Figure 9-12. A folder home page hosting the Outlook Permissions control. Using this control, you can easily update permissions in public folders.

<HTML> <HEAD> <META NAME="GENERATOR" Content="Microsoft Visual Studio 6.0"> <TITLE>Outlook Permissions Control Test</TITLE> <Script Language=VBScript> Function CreateControl() dim L_SelectTeam_Text, L_AddMemberLabel_text, L_RoleEveryone_Text, _ L_RoleNoAccess_Text, L_RoleEditor_Text, L_RoleAuthor_Text dim L_RoleReviewer_Text, L_RoleCustom_Text, L_RoleNonEditAuthor_Text, _ L_RoleOwner_Text dim L_RoleOwnerContact_Text, L_LabelUserName_Text, _ L_LabelUserRole_Text,L_LabelAvailableRoles_Text dim L_ProgFormCaption_Text L_SelectTeam_Text = "Select Team Members" L_AddMemberLabel_text = "Add" L_RoleEveryone_Text = "Everyone" L_RoleNoAccess_Text = "No Access" L_RoleEditor_Text = "Editor" L_RoleAuthor_Text = "Author" L_RoleNonEditAuthor_Text = "Nonediting Author" L_RoleReviewer_Text = "Reviewer" L_RoleOwner_Text = "Owner" L_RoleCustom_Text = "Custom" L_RoleOwnerContact_Text = "Owner / Contact" L_LabelUserName_Text = "Member List" L_LabelUserRole_Text = "Role" L_LabelAvailableRoles_Text = "Available Roles" L_ProgFormCaption_Text = "Updating Permissions" Dim MyCont MyCont = "<OBJECT classid=clsid:1786454A-B4A0-11D2-97C7-"&_ 000000000000 codebase=" & Chr(34) & "_ "http://activex.microsoft.com/ activex/controls/office/ olTFACL.cab#version=1,3210,0,1" & Chr(34) & " id=OLTFCTRL1 style=" & _ Chr(34) & "HEIGHT:240px" & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "_ExtentX" & Chr(34) & _ " value=" & Chr(34) & "11827" & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "_ExtentY" & Chr(34) & _ " value=" & Chr(34) & "9948" & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "TargetFolder" & _ Chr(34) & " value=" & Chr(34) & _ "\\Public Folders\All Public Folders\View Control Samples" & _ Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "TargetAdminFolder" & _ Chr(34) & " value=" & Chr(34) & _ "\\Public Folders\All Public Folders\View Control Samples\ & _ "Outlook Form" & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "EveryoneLabel" & _ Chr(34) & " value=" & Chr(34) & L_RoleEveryone_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "AddressBookTitle" & _ Chr(34) & " value=" & Chr(34) & L_SelectTeam_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "AddressBookToLabel" & _ Chr(34) & " value=" & Chr(34) & L_AddMemberLabel_text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleNoAccess" & _ Chr(34) & " value=" & Chr(34) & L_RoleNoAccess_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleEditor" & _ Chr(34) & " value=" & Chr(34) & L_RoleEditor_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleAuthor" & Chr(34) & _ " value=" & Chr(34) & L_RoleAuthor_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleNoneditingAuthor" & _ Chr(34) & " value=" & Chr(34) & L_RoleNonEditAuthor_Text & _ Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleReviewer" & _ Chr(34) & " value=" & Chr(34) & L_RoleReviewer_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleOwner" & Chr(34) & _ " value=" & Chr(34) & L_RoleOwner_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleCustom" & Chr(34) & _ " value=" & Chr(34) & L_RoleCustom_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "RoleOwnerContact" & _ Chr(34) & " value=" & Chr(34) & L_RoleOwnerContact_Text & _ Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "LabelUserName" & _ Chr(34) & " value=" & Chr(34) & L_LabelUserName_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "LabelUserRole" & _ Chr(34) & " value=" & Chr(34) & L_LabelUserRole_Text & Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "LabelAvailableRoles" & _ Chr(34) & " value=" & Chr(34) & L_LabelAvailableRoles_Text & _ Chr(34) & ">" MyCont = MyCont & "<param name=" & Chr(34) & "ProgFormCaption" & _ Chr(34) & " value=" & Chr(34) & L_ProgFormCaption_Text & _ Chr(34) & "></OBJECT>" CreateControl = MyCont End function Sub AddUser() OLTFCTRL1.Add End Sub Sub RemoveUser() OLTFCTRL1.Remove End Sub Sub UpdateUsers Dim UList On Error Resume Next UList = OLTFCTRL1.Update(1) If err.number <> 0 then MsgBox "Error: " & err.number & " " & err.description End If End Sub Sub ListUser(LType) Dim UList On Error Resume Next UList = OLTFCTRL1.List(LType) If err.number <> 0 Then MsgBox "Error: " & err.number & " " & err.description End If MsgBox UList End Sub </SCRIPT> </HEAD> <BODY> This Web page shows how you can host the Permissions control in a folder home page. <Script Language="VBScript"> document.writeln(CreateControl()) </SCRIPT> <DIV> <INPUT type="button" value="Add User" onclick="AddUser" id=button1 name=button1> <INPUT type="button" value="Remove User" onclick="RemoveUser" id=button2 name=button2> <INPUT type="button" value="List Users (Name)" onclick="ListUser(1)" id=button3 name=button3> <INPUT type="button" value="List Users (Email)" onclick="ListUser(2)" id=button4 name=button4> <INPUT type="button" value="Update Permissions" onclick="UpdateUsers" id=button5 name=button5> </DIV> </BODY> </HTML>