How to: Grant and revoke control of shared resources

[This is preliminary documentation and is subject to change.]

Describes how to grant and revoke control of a locally shared resource in a Microsoft Lync 2013 Preview conversation. For an overview of resource sharing in Lync 2013 Preview, see Resource Sharing in Lync.

The topic in this section builds on the sample application introduced in How Do I in Resource Sharing and continued in How to: Get shareable resources and share them in a conversation. Figure 1 highlights the part of the sample Windows form that we discuss in this topic. The tasks in the following list are discussed in this topic and shown in the code samples.

  • Verifying that you can grant control of a locally shared resource to another user.

  • Granting control of a locally shared resource to another user.

  • Verifying that you can revoke control of a locally shared resource to another user.

  • Revoking control of a locally shared resource.

Figure 1. Grant and revoke control buttons

Grant and revoke control buttons

Before your application runs the logic in this How to, a resource sharing conversation must be active with one or more participants in addition to the local user. The local user participation state must be ParticipationState.Sharing and a local sharable resource must be shared in the conversation. For information about reaching this starting application state, see How to: Get shareable resources and share them in a conversation.

You can only grant control of a resource that is shared locally and not controlled by another conversation participant. To simplify your code, just track the availability of control actions on the Modality.ActionAvailabilityChanged event for all of the Microsoft.Lync.Model.Conversation.Sharing.ApplicationSharingModality objects in a conversation. For information about handling this event, see How to: Get shareable resources and share them in a conversation.

Note Note

The participant who is sharing a local resource has the participation state of ParticipationState.Sharing. All other participants have the participation state of ParticipationState.Viewing unless they are requesting control of the shared resource. In this case, they are ParticipationState.RequestingControl. When the sharing participant accepts a control request, the requesting participant is ParticipationState.Controlling.

There can be only one ParticipationState.Sharing participant at a time. There can be zero or one ParticipationState.Controlling participant at a time. There can be many ParticipationState.RequestingControl participants.

If there is no ParticipationState.Controlling participant, the resource is shared but not controlled.

Calling the BeginGrantControl method

Call the ApplicationSharingModality.BeginGrantControl method on the application sharing modality of the conversation participant that is being granted control of the locally shared resource.

ApplicationSharingModality events

Two events are raised on the Conversation Microsoft.Lync.Model.Conversation.Sharing.ApplicationSharingModality object when control of a resource has been granted. The Modality.ActionAvailabilityChanged event is raised twice to indicate that the Grant action is no longer available but the Revoke action is now available. The ApplicationSharingModality.ControllerChanged event is raised to indicate that there is now a resource controller and provides a Microsoft.Lync.Model.Contact object that represents the new controller.

ParticipationStateChanged events

When the control granting operation is finished, the participant who is granted control is now a ParticipationState.Controlling participant. The controlling participant is notified of this state change in the ApplicationSharingModality.ParticipationStateChanged event. The participation state of the sharing participant does not change.

If the sharing participant revokes control of the shared resource, the controlling participant becomes a viewing participant and the ApplicationSharingModality.ParticipationStateChanged event is raised on that participants application sharing modality.

Code example

The following example completes the following steps: and then.

  1. Obtains the Sip Uri of the selected conversation participant from the UI list of participants.

  2. Obtains a Microsoft.Lync.Model.Conversation.Sharing.ApplicationSharingModality object from a Dictionary<string,Microsoft.Lync.Model.Conversation.Sharing.ApplicationSharingModality>. The dictionary contains references to the application sharing modality objects of all participants. For a listing of the sample code that declares and fills this dictionary, see How to: Start resource sharing conversations.

  3. Verifies that control of the shared resource can be granted and then grants control to the selected participant.

         /// <summary>
        ///Grant another participant control of a locally owned and shared resource.
        ///The Grant button is enabled when the _sharingModality_ActionAvailabilityChanged event handler is
        ///called with the event argument that specifies the ModalityAction.GrantSharingControl action is available.
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        private void Grant_Button_Click(object sender, EventArgs e)
        {
            if (Contact_ListBox.SelectedItems.Count == 0)
            {
                return;
            }
            //Get the sharing modality of the participant which the local user has selected to control the locally owned resource.
            try
            {
                //_particpantSharingModalities is a class field of type Dictionary<string, ApplicationSharingModality>.
                //It is filled in the Conversation.ParticipantAdded event callback method of this sample.
                ApplicationSharingModality sharingModality = (ApplicationSharingModality)_participantSharingModalities[Contact_ListBox.SelectedItem.ToString()];
 
                //If the application sharing modality is available and the resource can still be granted then grant
                //control of the resource.
                if (sharingModality != null && sharingModality.CanInvoke(ModalityAction.GrantSharingControl))
                {
                    sharingModality.BeginGrantControl(SharingControlCallback, "grant");
                }
            }
            catch (NullReferenceException) { MessageBox.Show("Chosen participant does not have an application sharing modality.""Grant control error"); }
 
        }

The following example is invoked by the platform thread on completion of the asynchronous ApplicationSharingModality.BeginGrantControl

        /// <summary>
        /// Callback method for all asynchronous modality control methods.
        /// </summary>
        /// <param name="ar"></param>
        private void SharingControlCallback(System.IAsyncResult ar)
        {
            //Get the application sharing modality for the conversation participant to invoke controlling action on.
            ApplicationSharingModality sharingModality = (ApplicationSharingModality)_participantSharingModalities[_ResourceControllingContact.Uri];
 
            //Complete the asynchronous controlling action according to the asynchronous state string that indicates
            //which controlling action to complete.
            switch (ar.AsyncState.ToString().ToUpper())
            {
                case "ACCEPT":
                    sharingModality.EndAcceptControlRequest(ar);
                    break;
                case "DECLINE":
                    sharingModality.EndDeclineControlRequest(ar);
                    break;
                case "GRANT":
                    sharingModality.EndGrantControl(ar);
                    break;
                case "RELEASE":
                    sharingModality.EndReleaseControl(ar);
                    break;
                case "REQUEST":
                    sharingModality.EndRequestControl(ar);
                    break;
                case "REVOKE":
                    sharingModality.EndRevokeControl(ar);
                    break;
                case "DISCONNECT":
                    sharingModality.EndDisconnect(ar);
                    break;
            }
        }

The following example handles the event raised when a conversation participant is granted control of the locally shared resource. It is important that you maintain a reference to the participant who is controlling a resource.

When revoking control of the resource, you must call the ApplicationSharingModality.BeginRevokeControl method on the ApplicationSharingModality of that participant.

        /// <summary>
        /// Handles the event raised when the participant that is controlling the shared conversation application resource
        /// changes. This event is raised locally even when the shared resource is not locally owned.
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        void _sharingModality_ControllerChanged(object sender, ControllerChangedEventArgs e)
        {
            this.Invoke(new ChangeLabelTextDelegate(ChangeLabelText), new object[] { ResourceControllerName_Label, e.ControllerName });
 
            //Store the Contact object for the conversation participant that now controls the shared conversation resource.
            _ResourceControllingContact = ((ApplicationSharingModality)sender).Controller.Contact;
 
        }

You can only revoke control of a resource that is owned and shared locally. Control of the resource must have been previously granted to another conversation participant. Call the ApplicationSharingModality.BeginRevokeControl method on the ApplicationSharingModality of the participant who is controlling the resource.

Tip Tip

When your code accepts a control request of another user, control is automatically revoked from the current controlling user. You do not need to call the ApplicationSharingModality.BeginRevokeControl method before accepting the new control request.

ApplicationSharingModality Events

When control of the locally shared resource is revoked, the Grant action is available and the Revoke action is no longer available. Two Modality.ActionAvailabilityChanged events are raised. The first event shows the ModalityActionAvailabilityChangedEventArgs.Action property value of ModalityAction.GrantSharingControl is available. The second event shows the ModalityActionAvailabilityChangedEventArgs.Action property value of ModalityAction.RevokeSharingControl is not available.

Code example

The following example revokes control of a locally owned and share resource that is controlled by a resource viewer. The _ResourceControllingContact object is a class field of type Microsoft.Lync.Model.Contact. It is filled in the previous example when the control of the resource changes as a result of a grant operation.

        /// <summary>
        ///Revoke control of a remotely controlled resource and locally owned shared resource.
        ///The Revoke button is enabled when the _sharingModality_ActionAvailabilityChanged event handler is called
        ///with the event argument that specifies the ModalityAction.RevokeSharingControl action is available.
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        private void Revoke_Button_Click(object sender, EventArgs e)
        {
            if (_ResourceControllingContact == null)
            {
                return;
            }
            ApplicationSharingModality sharingModality = (ApplicationSharingModality)_participantSharingModalities[_ResourceControllingContact.Uri];
            if (sharingModality != null && sharingModality.CanInvoke(ModalityAction.RevokeSharingControl))
            {
                sharingModality.BeginRevokeControl(SharingControlCallback, "revoke");
            }
 
        }

When your application has granted and revoked a locally shared resource, the resource is shown on the content stage of all participants with no participants in control. In addition, the ModalityAction.GrantSharingControl action is available. You can now grant sharing control of the locally shared resource to another participant. The participants who are viewing the shared resource can request control of the resource. For information about accepting or declining a request to control a resource, see How to: Accept or decline requests to control a shared resource.

Community Additions

Show:
© 2014 Microsoft