Preventing Document Modification in Windows SharePoint

Windows SharePoint Services 3.0 provides a versioning capability that prevents documents from being overwritten by creating a version of the file each time a change is made to either the file or the metadata. However, there may be specific situations, such as archival or records-management scenarios, in which you want to let users modify metadata but not modify the file contents; that is, there is always only one version of the file. This Microsoft Office Visual How To shows how you can enable this in specific scenarios by using event handlers and handling short-term and long-term check-outs. 

This example deals with two basic types of check-out processes in Windows SharePoint Services: short term and long term. Short-term check-outs are implicit and are done when a document is opened for editing. A lock is applied to the file while it is being edited in the client application so that no other users can modify it. After the client application is closed, the lock is released. Long-term check-outs are explicit and lock the document regardless of whether it is opened and being edited in the client application. It remains checked out until it is explicitly checked back in.
In this example, you allow modification of metadata but prevent modification of the file by handling both long- and short-term check-outs in three ways:

• Preventing the user from performing a long-term check-out process on a file
  
  
• Handling a short-term check-out process created by an application, such as Microsoft Office Word
  
  
• Preventing a check-in process if a long term check-out process has been automatically initiated, such as during the file upload process
  
  

These situations are handled with a custom EventReceiver registered on the document library, using the ItemCheckingOut and ItemUpdating event handlers. Additionally, it is important to note that the document library must have versioning enabled, but the Require Check Out setting and the Allow Major/Minor versions setting must both be set to No. Setting required check-out to No, together with the event handlers, enables you to modify the metadata without overwriting the file contents.


Figure 1. Require check out

To prevent the user from doing a long-term check-out process, such as by clicking the Check Out link in the Edit Control Block (ECB), the ItemCheckingOut event is canceled any time it is executed. To do this, override the ItemCheckingOut method, and set the properties.Status to the CancelNoError enumeration. This displays the default system message to the user and cancels the check-out process.

publicoverridevoid ItemCheckingOut(SPItemEventProperties properties)
        {
base.DisableEventFiring();
try
            {
                properties.Status = SPEventReceiverStatus.CancelNoError;
            }
catch { }
finally
            {
base.EnableEventFiring();
            }
        }

Although you prevent the user from performing a check-out process, there may be situations where a file is checked out in some other way. Examples include a short-term check-out process performed by a client application, or a long-term check-out automatically done when you upload a file that does not have all the required metadata. Both situations involve a check-out process that would occur outside the control of the ItemCheckingOut event. These check-out processes are handled in the ItemUpdating event handler.
If either of these types of check-out process occurs, it may appear at first glance that you can prevent the original file from being overwritten by preventing the checked-out file from being checked in. However, if a checked-in version does not already exist, you must allow the first checked-in version to proceed.
You can determine if a checked-in version exists by evaluating the Level property of the file. Files that have been uploaded to the system and checked in have a level equal to SPFileLevel.Published. If a file does not have a level of Published, meaning a checked-in version does not exist, you let processing continue, and the file is checked in. Note that the check of the published status is why major/minor versioning must be disabled on the library. This ensures that only files with checked-in versions have a level of Published.
If a file has a level of Published and is also checked out, you want to prevent it from being checked in and continue to evaluate the check-out status. The check-out status indicates either a short-term or long-term check-out process has been performed. If the status is a short-term check-out, you set the status and cancel properties of the SPItemEventProperties object to stop further processing. For a long-term check-out, you first undo the check-out, so that the file is checked back in and any changes undone, and then you set the Status property and the Cancel property to stop further processing. For both short-term and long-term check-out processes, this prevents the file from being checked in and overwriting the original.

publicoverridevoid ItemUpdating(SPItemEventProperties properties)
        {
base.DisableEventFiring();
try
            {
SPFile file = properties.ListItem.File;
if (file.Level == SPFileLevel.Published && file.CheckOutStatus != SPFile.SPCheckOutStatus.None)
                {
if ((file.CheckOutStatus == SPFile.SPCheckOutStatus.LongTerm) ||
                        (file.CheckOutStatus == SPFile.SPCheckOutStatus.LongTermOffline))
                    {
                        file.UndoCheckOut();
                    }
                    properties.Status = SPEventReceiverStatus.CancelWithError;
                    properties.Cancel = true;
                }
            }
catch {}
finally
            {
base.EnableEventFiring();
            }
        }