Welcome Sign in
Visual Studio Developer Center
Printer Friendly Version      Send     
Click to Rate and Give Feedback
MSDN
MSDN Library
Visual Studio 6.0
Technical Articles
 Visual SourceSafe 6.0 Automation
Visual SourceSafe Technical Articles
Visual SourceSafe 6.0 Automation
 

Tim Winter
Microsoft Corporation

September 1998

Download 5269.exe.

Summary: Discusses the Automation interface exposed by Microsoft® Visual SourceSafe™ version 6.0. Written from the perspective of the Microsoft Visual Basic® programmer and includes code snippets written in Visual Basic version 5.0. (67 printed pages)

Contents

Introduction
     Terms and Expressions
Trapping SourceSafe Events
     IVSSEventHandler Interface
     VSSApp Object
     Trapping SourceSafe Events—An Overview
Putting It All Together—Trapping Visual SourceSafe Events
     Setting Up the Visual Basic Development Environment
     Writing the Code
Driving a SourceSafe Database
     VSSCheckOut Object
     VSSDatabase Object
     VSSFileStatus
     VSSFlags (Flags Used within Automation)
     VSSItem Object
     VSSItemType Constants
     VSSRights Constants
     VSSUser Object
     VSSVersion Object
Error Messages
Putting It All Together—Driving a SourceSafe Database
     Setting Up the Visual Basic Development Environment
     Writing the Code

Introduction

This article discusses the Automation interface exposed by Visual SourceSafe version 6.0. It is written from the perspective of the Microsoft Visual Basic® programmer and includes code snippets written in Visual Basic version 5.0. In addition, there are several Automation code samples available with this article. Future versions of Visual SourceSafe will attempt to make as few changes as possible to this interface. Earlier (pre-5.0) versions of Visual SourceSafe do not support this interface in any way.

This article is divided into two parts: "Trapping SourceSafe Events" and "Driving a SourceSafe Database". SourceSafe's Automation interface allows the user to hook into and control certain events as they occur within a SourceSafe session. For example, you may want to create an application that would notify specific users via e-mail whenever certain files have been checked in or checked out from the database. Trapping SourceSafe events allows you to do this. The second part of this article describes the objects, methods, and properties required to create your own interface in the SourceSafe database.

Terms and Expressions

The following terms and expressions are used throughout this article:

  • <…>: Refers to a section of code not included in the code sample. This could represent a section of code required for the sample to execute properly (declarations, definitions, and so on).
  • boolVar: Refers to a Boolean variable.
  • objVSSDatabase: Refers to a SourceSafe database object created with the Open method of the VSSDatabase object. (See the "Open Method" topic in the "VSSDatabase Object" section for more information).
  • objVSSItem: Refers to a created file or project object.
  • strVar: Refers to a string variable.

Trapping SourceSafe Events

IVSSEventHandler Interface

The VSSApp object allows the user to hook into and control certain events as they occur within a SourceSafe session. For example, you may want to create an application that would notify specific users via e-mail whenever certain files have been checked in or checked out from the database. Trapping SourceSafe events allows you to do this.

From Visual Basic, this may be accomplished through the creation of a Visual SourceSafe add-in (which is typically a Microsoft ActiveX® DLL). When SourceSafe is launched, it will create an instance of your add-in and call its Init method. This method is exposed through the IVSSEventHandler interface.

To trap SourceSafe events, your ActiveX DLL must support the IVSSEventHandler interface. In Visual Basic, this is best accomplished using the IMPLEMENTS statement. Once you have set a reference to the SourceSafe 6.0 Type Library, you can implement the IVSSEventHandler interface with the code:

Implements IVSSEventHandler

When Visual Basic implements the interface, it provides its own version of every procedure exposed by the interface. Your add-in must include code for each of these procedures, regardless of whether or not you use them. For more information on these procedures, see the "VSSApp Object" section of this article.

Methods

Init(pIVSS As VSSApp)

The IVSSEventHandler interface exposes the Init method, which is called by SourceSafe when it creates an instance of your add-in (this takes place immediately after login). Because SourceSafe calls this method, any add-in you create must support it. The Init method accepts a single parameter: pIVSS. This required parameter represents the IVSS interface of the VSSApp object. To the Visual Basic programmer, this interface will appear as the VSSApp object itself.

When SourceSafe calls the Init method of your add-in, it will pass the VSSApp object to the add-in automatically. This object allows your add-in to control SourceSafe.

The following Visual Basic code could be placed in the Init method of your add-in to display login information on the current SourceSafe session:

Sub IVSSEventHandler_Init(ByVal pIVSS As VSSApp)
    
   Set VSSHandler = pIVSS
   MsgBox ("User " + pIVSS.VSSDatabase.Username + _
   " has just logged into the database located at " + _
   pIVSS.VSSDatabase.SrcSafeIni)
    
End Sub

For more information on creating a SourceSafe add-in and hooking into SourceSafe events, see the "VSSApp Object" and the "Putting It All Together" sections of this article.

VSSApp Object

The VSSApp object allows the user to hook into and control certain events as they occur within a SourceSafe session. The VSSApp object exposes two interfaces: IVSS and IVSSEvents. The IVSS interface provides a VSSDatabase property while the IVSSEvents interface provides the events listed here.

BeforeAdd AfterAdd
BeforeBranch AfterBranch
BeforeCheckIn AfterCheckIn
BeforeCheckOut AfterCheckOut
BeforeEvent AfterEvent
BeforeRename AfterRename
BeforeUndoCheckOut AfterUndoCheckOut
BeginCommand EndCommand

To the Visual Basic programmer, these interfaces appear to come directly off the VSSApp object. For example, if you wanted to know the UserName of a person logging into SourceSafe, the following Visual Basic code would provide that information:

Implements IVSSEventHandler
' The next statement creates an instance of a VSSApp Object
Dim WithEvents VSSHandler As VSSApp
Sub IVSSEventHandler_Init(ByVal pIVSS As VSSApp)    
   Set VSSHandler = pIVSS
   MsgBox ("User " + pIVSS.VSSDatabase.Username + _
   " has just logged into SourceSafe.")
End Sub

The preceding example uses a third interface called IVSSEventHandler that exposes an Init method. (For more information, see the "IVSSEventHandler Interface" section earlier in this article.) The Init method is called by SourceSafe when it creates an instance of your add-in, so your add-in must support it.

We recommend you make the VSSApp object global. This allows you to gain additional information on the database object from within each event.

Trapping SourceSafe Events—An Overview

When the SourceSafe Explorer or Admin utility is opened, it looks for a file called ssaddin.ini. This file contains information on the SourceSafe add-ins that you want to launch for that SourceSafe session. If this file exists, SourceSafe attempts to create an instance of any add-ins referenced within the file.

The following steps describe how to set up your SourceSafe add-in from Visual Basic:

  1. Create and compile an ActiveX DLL in Visual Basic that implements the IVSSEventHandler interface (this is described in detail later).
  2. Open the Windows registry, and locate the ProgID of your DLL.
  3. Create (or open) the text file ssaddin.ini, and add a reference to the ProgID of your DLL. This reference must use the syntax:

    <ProgID>=1

The file ssaddin.ini must reside in the same folder as ssapi.dll. By default, this is the …\VSS\WIN32 folder.

Note   To trap events in SourceSafe, each SourceSafe installation must have its own copy of ssaddin.ini and the ActiveX DLL (or add-in). For example, suppose you have SourceSafe installed on Server A and a client installation of SourceSafe on workstations B and C. The file ssaddin.ini must appear in the …\VSS\WIN32 folder of A, B, and C, and you must install and register the add-in on each system (A, B, and C).

If you were to add a third SourceSafe installation to the preceding example (workstation D) and not add both of these files, SourceSafe events that occur on workstation D will not be trapped (although events on A, B, and C will continue to be trapped).

Launch SourceSafe. SourceSafe will create an instance of your add-in and call its Init method. The Init method of your add-in is passed a VSSApp object, which establishes the communication link between it and SourceSafe.

To trap SourceSafe events, your ActiveX DLL must support the IVSSEventHandler interface. In Visual Basic, this is best accomplished using the IMPLEMENTS statement. Once you have set a reference to the SourceSafe 6.0 Type Library, you can implement the IVSSEventHandler interface with the code:

Implements IVSSEventHandler
' The next statement creates an instance of a VSSApp Object
Dim WithEvents VSSHandler As VSSApp

When Visual Basic implements the interface, it provides its own version of every procedure exposed by the interface. Your add-in must include code for each of these procedures regardless of whether or not you use them. For example, if your add-in only deals with the CheckOut and CheckIn events, you must still add empty procedures (procedures that don't do anything) for every other event that the interface exposes. These procedures (or events) are documented in the next section.

Events

All of the following SourceSafe events may be trapped from your add-in. The sample code used in this section assumes your add-in was created using an ActiveX DLL.

Each of these events is passed a VSSItem parameter that exposes many properties and methods accessible from your add-in. For more information on the VSSItem object, see the "VSSItem Object" section later in this article.

Each of the Before<event> functions (BeforeAdd, BeforeCheckIn, and so on) allows you to prevent the event from occurring. This is accomplished by setting the function's return value to false.

Note   Each of these events is only fired on the client machine where the SourceSafe action is taking place. In other words, if a user is adding a file on machine A, the BeforeAdd event is fired only on machine A.

AfterAdd(pIItem As VSSItem, Local As String, Comment As String)

The AfterAdd event is fired immediately after an item is added to the SourceSafe database. This event accepts three parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file added to SourceSafe.
  • Local: This string parameter accepts the complete path of the file added to SourceSafe.
  • Comment: This string parameter accepts the comment (if any) applied by the user when the file was added.

The following Visual Basic code displays a message box with the name of the file that was just added, the project path it was added to, and the comment applied (if any):

Sub VSSHandler_AfterAdd(ByVal Item As IVSSItem, ByVal LocalSpec _
As String, ByVal Comment As String)
MsgBox ("The file " + LocalSpec + " was just added to " + _
Item.Parent.Spec _
   + " with a comment of " + Comment)
End Sub

This event is fired after adding file objects only; it is not fired when a new project object is created.

AfterBranch(pIItem As VSSItem, Comment As String)

The AfterBranch event is fired immediately after an item is branched in the SourceSafe database. This event accepts two parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file branched in SourceSafe.
  • Comment: This string parameter accepts the comment applied by the user when the file was branched.

The following Visual Basic code displays the name of the branched file, the name of the project from which it was branched, and the comment applied to the branch by the user (if any):

Sub VSSHandler_AfterBranch(ByVal Item As IVSSItem, ByVal Comment _
As String)
   MsgBox ("The file " + Item.Name + " in the project " + _
   Item.Parent.Name + " was just branched with a comment of " + _
   Comment)
End Sub

The AfterBranch event is only fired when file objects are branched. SourceSafe does not support branching project objects at this time.

AfterCheckIn(pIItem As VSSItem, Local As String, Comment As String)

The AfterCheckIn event is fired immediately after an item is checked into the SourceSafe database. This event accepts three parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file checked in to SourceSafe.
  • Local: This string parameter accepts the complete path of the file checked in to SourceSafe.
  • Comment: This string parameter accepts the comment applied by the user when the file was checked in.

This event is fired after checking in a file or project object. The following Visual Basic code displays a message box with the name of the file that was just checked in, the local path it was checked in from, and the comment applied (if any):

Sub VSSHandler_AfterCheckIn(ByVal Item As IVSSItem, ByVal LocalSpec _
As String, ByVal Comment As String)
   MsgBox ("The file " + LocalSpec + " was just checked in to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
End Sub

When you check in a project object, each file that is checked in to the project will fire this event.

Note   A shared file may be checked in from any one of several locations. The links property of the IVSSItem can be used to retrieve a list of these locations.

AfterCheckOut(pIItem As VSSItem, Local As String, Comment As String)

The AfterCheckOut event is fired immediately after an item is checked out from the SourceSafe database. This event accepts three parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file checked out from SourceSafe.
  • Local: This string parameter accepts the complete path of the file checked out to SourceSafe.
  • Comment: This string parameter accepts the comment applied by the user when the file was checked out.

This event is fired after checking out a file or project object. The following Visual Basic code displays a message box with the name of the file that was just checked out, the local path it was checked out to, and the comment applied (if any):

Sub VSSHandler_AfterCheckOut(ByVal Item As IVSSItem, ByVal _
LocalSpec As String, ByVal Comment As String)
   MsgBox ("The file " + LocalSpec + " was just checked out to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
End Sub

When you check out a project object, each file that is checked out from the project will fire this event.

AfterEvent(iEvent As Long, pIItem As VSSItem, Str As String, var)

Currently this event serves no purpose. It may be used in future versions of SourceSafe.

AfterRename(pIItem As VSSItem, OldName As String)

The AfterRename event is fired immediately after a file or project item is renamed in the SourceSafe database. This event accepts two parameters that are passed to your add-in from Visual SourceSafe:

pIItem: This VSSItem parameter accepts a VSSItem object representing the file or project that was renamed in the SourceSafe database.

OldName: This string parameter accepts the original name of the file or project that was renamed in the SourceSafe database.

The following Visual Basic code displays a message box that displays the old and new name of the renamed file or project object:

Sub VSSHandler_AfterRename(ByVal Item As IVSSItem, ByVal OldName _
As String)    
   Dim strItemType As String    
   If Item.Type = VSSITEM_FILE Then
      strItemType = "file"
   Else
      strItemType = "project"
   End If
   MsgBox ("The " + strItemType + " " + OldName +  _
   " was just renamed to " + Item.Name)    
End Sub

AfterUndoCheckOut(pIItem As VSSItem, Local As String)

The AfterUndoCheckOut event is fired immediately after an item is unchecked out from the SourceSafe database. This event accepts two parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file that was unchecked out from SourceSafe.
  • Local: This string parameter accepts the complete path of the file that was unchecked out from SourceSafe.

The following Visual Basic code displays a message box describing the SourceSafe file path that was unchecked out and the local folder from which it was unchecked out.

Sub VSSHandler_AfterUndoCheckOut(ByVal Item As IVSSItem, _
ByVal LocalSpec As String)
   MsgBox ("The file " + Item.Spec + " was just unchecked out from " + _
   "the folder " + LocalSpec)
End Sub

When you uncheck out a project object, each file that is unchecked out to the project will fire this event.

BeforeAdd(pIPrj As VSSItem, Local As String, Comment As String)

The BeforeAdd event is fired immediately before an item is added to the SourceSafe database. This event accepts three parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file being added to SourceSafe.
  • Local: This string parameter accepts the complete path of the file being added to SourceSafe.
  • Comment: This string parameter accepts the comment applied by the user to the file being added.

This event is fired prior to adding a file only (adding a project will not fire this event). The following Visual Basic code displays a message box with the name of the file that will be added, the project path it will be added to, and the comment being applied. If there is no comment, the add is canceled:

Function VSSHandler_BeforeAdd(ByVal Prj As IVSSItem, _
ByVal LocalSpec As String, ByVal Comment As String) As Boolean   
   MsgBox ("The file " + LocalSpec + " is about to be added to 
              " +  Prj.Spec _+ " with a comment of " + Comment)
   If Comment = "" Then
      VSSHandler_BeforeAdd = False
      Else
      VSSHandler_BeforeAdd = True
      EndIf
End Function

If you set the function VSSHandler_BeforeAdd to false, the addition of the file object will not occur.

This event does not support adding files from the folder level. For example, if the user attempts to add the contents of the folder "C:\MyFolder," the error "Cannot use wildcards with this command" will be generated, and no items will be added.

When you add multiple files from a common folder, each file being added will fire this event.

BeforeBranch(pIItem As VSSItem, Comment As String)

The BeforeBranch event is fired prior to branching a file item in the SourceSafe database. This event accepts two parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file branched in SourceSafe.
  • Comment: This string parameter accepts the comment applied by the user when the file was branched.

The following Visual Basic code displays the name of the file to be branched, the name of the project from which it will be branched, and the comment being applied to the branch by the user. If no comment has been added, the branch is canceled:

Function VSSHandler_BeforeBranch(ByVal Item As IVSSItem, _
ByVal Comment As String) As Boolean
   MsgBox ("The file " + Item.Name + " in the project " + _
       Item.Spec + " is about to be branched with a comment of " + _
       Comment)
   If Comment = "" Then
      VSSHandler_ BeforeBranch = False
      Else
      VSSHandler_ BeforeBranch = True
   EndIf
End Function

If you set the function VSSHandler_BeforeBranch to false, the branching of the file object will not occur.

The BeforeBranch event is only fired when file objects are branched. SourceSafe does not support branching project objects at this time.

BeforeCheckIn(pIItem As VSSItem, Local As String, Comment As String)

The BeforeCheckIn event is fired immediately prior to the check in of a file object to the SourceSafe database. This event accepts three parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file to be checked in to SourceSafe.
  • Local: This string parameter accepts the complete path of the file to be checked in to SourceSafe.
  • Comment: This string parameter accepts the comment applied by the user of the file to be checked in to SourceSafe

The following Visual Basic code displays a message box with the name of the file that is to be checked in, the local path it will checked in from, and the comment applied. If no comment has been added, the check-in is canceled:

Function VSSHandler_BeforeCheckIn(ByVal Item As IVSSItem, _
ByVal LocalSpec As String, ByVal Comment As String) As Boolean
   MsgBox ("The file " + LocalSpec + " is about to be checked in to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
   If Comment = "" Then
      VSSHandler_ BeforeCheckIn = False
      Else
      VSSHandler_ BeforeCheckIn = True
   EndIf
End Function

If you set the function VSSHandler_BeforeCheckIin to false, the checking in of the file object will not occur.

When you check in a project object, each file that is checked in to the project will fire this event.

BeforeCheckOut(pIItem As VSSItem, Local As String, Comment As String)

The BeforeCheckOut event is fired immediately prior to the check out of a file item from the SourceSafe database. This event accepts three parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file being checked out from SourceSafe.
  • Local: This string parameter accepts the complete path of the file being checked out to SourceSafe.
  • Comment: This string parameter accepts the comment applied by the user to file check out.

The following Visual Basic code displays a message box with the name of the file that is being checked out, the local path it will be checked out to, and the check out comment applied. If no comment has been added, the checkout is canceled:

Function VSSHandler_BeforeCheckOut(ByVal Item As IVSSItem, _
ByVal LocalSpec As String, ByVal Comment As String) As Boolean
   MsgBox ("The file " + LocalSpec + " is about to be checked out to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
   If Comment = "" Then
      VSSHandler_ BeforeCheckOut = False
      Else
      VSSHandler_ BeforeCheckOut = True
   EndIf
End Function

If you set the function VSSHandler_BeforeCheckOut to false, the checking out of the file object will not occur.

When you check out a project object, each file to be checked out from the project will fire this event.

BeforeEvent(iEvent As Long, pIItem As VSSItem, Str As String, var)

Currently this event serves no purpose. It may be used in future versions of SourceSafe.

BeforeRename(pIItem As VSSItem, NewName As String)

The BeforeRename event is fired immediately prior to the renaming of a file or project in the SourceSafe database. This event accepts two parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file or project that will be renamed in the SourceSafe database.
  • NewName: This string parameter accepts the new name to be applied to the file or project item.

The following Visual Basic code displays a message box that contains the current and proposed name of the file or project object. If the proposed name exceeds 10 characters in length, the rename is canceled:

Function VSSHandler_BeforeRename(ByVal Item As IVSSItem, _
ByVal NewName As String) As Boolean
   Dim strItemType As String    
   If Item.Type = VSSITEM_FILE Then
      strItemType = "file"
   Else
      strItemType = "project"
   End If
   MsgBox ("The " + strItemType + " " + Item.Name +  _
   " is about to be renamed to " + NewName)   
   If Len(NewName) > 10 Then
      VSSHandler_ BeforeRename = False
      Else
      VSSHandler_ BeforeRename = True
   EndIf
   End Function

If you set the function VSSHandler_BeforeRename to false, the rename of the file or project object will not occur.

BeforeUndoCheckOut(pIItem As VSSItem, Local As String)

The BeforeUndoCheckOut event is fired immediately prior to unchecking out a file item from the SourceSafe database. This event accepts two parameters that are passed to your add-in from Visual SourceSafe:

  • pIItem: This VSSItem parameter accepts a VSSItem object representing the file being unchecked out from SourceSafe.
  • Local: This string parameter accepts the complete path of the file being unchecked from SourceSafe.

The following Visual Basic code displays a message box describing the SourceSafe file path that is being unchecked out and the local folder from which it will be unchecked out. If the user is attempting to uncheck out the file from the root of their C drive, the undo checkout is canceled:

Function VSSHandler_BeforeUndoCheckOut(ByVal Item As IVSSItem, _
ByVal LocalSpec As String) As Boolean
   MsgBox ("The file " + Item.Spec + " is about to be " + _
       "unchecked out from " + LocalSpec)   
   If Left(LocalSpec, 2) = "C:" Then
      VSSHandler_ BeforeUndoCheckOut = False
      Else
      VSSHandler_ BeforeUndoCheckOut = True
   EndIf
End Function

When you undo checkout of a project object, each file that is unchecked out will fire this event.

If you set the function VSSHandler_BeforeUndoCheckOut to false, the undo checkout of the file will not occur.

BeginCommand(unused As Long)

The BeginCommand event is fired when the user initiates any SourceSafe command. The following Visual Basic code displays a message box whenever a command is initiated:

Function VSSHandler_BeginCommand(ByVal unused As Long) As Boolean
   MsgBox ("BeginCommand")
   VSSHandler_BeginCommand = True
End Function

If you set the function VSSHandler_BeginCommand to false, the command will be canceled.

Unfortunately there is currently no way to distinguish one command from another. Therefore, this event can only be used as an "all or nothing" way of allowing users to access the database. For example, if you wanted to prevent a specific user (or all users for that matter) from modifying the database, you could set VSSHandler_BeginCommand to false.

EndCommand(unused As Long)

The EndCommand event is fired after any SourceSafe command has been completed. The following Visual Basic code displays a message box whenever a command is done:

Sub VSSHandler_EndCommand(ByVal unused As Long)
   MsgBox ("EndCommand")
End Sub

Properties

VSSDatabase As VSSDatabase (Read-only)

The VSSDatabase property represents an instance of a Visual SourceSafe database. This object exposes the following properties and methods:

Properties:

  • CurrentProject as String
  • DatabaseName as String (Read-only)
  • DefaultProjectRights as Long
  • ProjectRightsEnabled as Boolean
  • SrcSafeIni as String (Read-only)
  • User (Name As String) as VSSUser (Read-only)
  • UserName as String (Read-only)
  • Users as IVSSUsers (Read-only)
  • VSSItem (Spec as String, [Deleted as Boolean = False]) as VSSItem (Read-only)
  • Methods:
  • AddUser (User as String, Password as String, Read-only as Boolean) as VSSUser
  • Open ([SrcSafeIni as String], [Username as String], [Password as String])

The following Visual Basic code displays login information obtained from the database object:

Implements IVSSEventHandler
' The next statement creates an instance of a VSSApp Object
Dim WithEvents VSSHandler As VSSApp
Sub IVSSEventHandler_Init(ByVal pIVSS As VSSApp)    
   Set VSSHandler = pIVSS
   MsgBox ("User " + pIVSS.VSSDatabase.Username + _
   " has just logged into SourceSafe.")
End Sub

For a complete description of these properties and methods, see the "VSSDatabase Object" section later in this article.

Putting It All Together—Trapping Visual SourceSafe Events

Setting Up the Visual Basic Development Environment

If you want to create an application that uses the SourceSafe Automation interface, you need to set a reference to the SourceSafe 6.0 Type Library. If this option doesn't appear in your Visual Basic Reference list, use the Browse command from the References dialog box to locate the file ssapi.dll. By default, this file will reside in the WIN32 folder of your Visual SourceSafe 6.0 installation.

Writing the Code

This section takes you through a step-by-step process of writing a Visual Basic ActiveX DLL that traps events in a SourceSafe database. You may copy this code sample and paste it into a Visual Basic 5.0 ActiveX DLL project to view the sample in action.

Begin by opening a new ActiveX DLL project and setting a reference to the SourceSafe 6.0 Type Library. To trap SourceSafe events, your ActiveX DLL must support the IVSSEventHandler interface. In Visual Basic, this is best accomplished using the IMPLEMENTS statement. You can implement the IVSSEventHandler interface by adding the following code to your Class module:

Implements IVSSEventHandler

Next we add code that creates an instance of the VSSApp object:

Dim WithEvents VSSHandler As VSSApp

When SourceSafe is opened, it will create an instance of your add-in and call its Init method. This method is exposed through the IVSSEventHandler interface. Add the following procedure to your Class module to create the Init method:

Sub IVSSEventHandler_Init(ByVal pIVSS As VSSApp)
   Set VSSHandler = pIVSS
   ' This optional line displays login information when SourceSafe is opened
   MsgBox ("User " + pIVSS.VSSDatabase.Username + _
   " has just logged into the database located at " + _
   pIVSS.VSSDatabase.SrcSafeIni)
End Sub

When Visual Basic implements the IVSSEventHandler interface, it provides its own version of every procedure exposed by the interface. Consequently, our ActiveX DLL must include code for each of these procedures. The following Visual Basic code contains all of the procedures exposed by the interface. It includes the sample procedures used in the "Events" section earlier in this article. Copy this code, and paste it into your Class module:

Function VSSHandler_BeforeAdd(ByVal Prj As IVSSItem, ByVal LocalSpec _
As String, ByVal Comment As String) As Boolean
   MsgBox ("The file " + LocalSpec + " is about to be added to " + Prj.Spec _
   + " with a comment of " + Comment)
   VSSHandler_BeforeAdd = True
End Function
Sub VSSHandler_AfterAdd(ByVal Item As IVSSItem, ByVal LocalSpec As _
String, ByVal Comment As String)
   MsgBox ("The file " + LocalSpec + " was just added to " + Item.Parent.Spec _
   + " with a comment of " + Comment)
End Sub
Function VSSHandler_BeforeBranch(ByVal Item As IVSSItem, ByVal _
Comment As String) As Boolean
   MsgBox ("The file " + Item.Name + " in the project " + _
   Item.Spec + " is about to be branched with a comment of " + _
   Comment)
   VSSHandler_BeforeBranch = True
End Function
Sub VSSHandler_AfterBranch(ByVal Item As IVSSItem, ByVal Comment _
As String)
   MsgBox ("The file " + Item.Name + " in the project " + _
   Item.Parent.Name + " was just branched with a comment of " + _
   Comment)
End Sub
Function VSSHandler_BeforeCheckIn(ByVal Item As IVSSItem, ByVal _
LocalSpec As String, ByVal Comment As String) As Boolean
   MsgBox ("The file " + LocalSpec + " is about to be checked in to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
   VSSHandler_BeforeCheckIn = True
End Function
Sub VSSHandler_AfterCheckIn(ByVal Item As IVSSItem, ByVal LocalSpec _
As String, ByVal Comment As String)
   MsgBox ("The file " + LocalSpec + " was just checked in to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
End Sub
Function VSSHandler_BeforeCheckOut(ByVal Item As IVSSItem, ByVal _
LocalSpec As String, ByVal Comment As String) As Boolean
   MsgBox ("The file " + LocalSpec + " is about to be checked out to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
   VSSHandler_BeforeCheckOut = True
End Function
Sub VSSHandler_AfterCheckOut(ByVal Item As IVSSItem, ByVal LocalSpec _
As String, ByVal Comment As String)
   MsgBox ("The file " + LocalSpec + " was just checked out to " + _
   Item.Parent.Spec + " with a comment of " + Comment)
End Sub
Function VSSHandler_BeforeRename(ByVal Item As IVSSItem, ByVal _
NewName As String) As Boolean
   Dim strItemType As String
   If Item.Type = VSSITEM_FILE Then
      strItemType = "file"
   Else
      strItemType = "project"
    End If
    MsgBox ("The " + strItemType + " " + Item.Name + _
    " is about to be renamed to " + NewName)
    VSSHandler_BeforeRename = True
End Function
Sub VSSHandler_AfterRename(ByVal Item As IVSSItem, ByVal OldName _
As String)
   Dim strItemType As String
   If Item.Type = VSSITEM_FILE Then
      strItemType = "file"
   Else
      strItemType = "project"
   End If
   MsgBox ("The " + strItemType + " " + OldName + _
   " was just renamed to " + Item.Name)
End Sub
Function VSSHandler_BeforeUndoCheckOut(ByVal Item As IVSSItem, _
ByVal LocalSpec As String) As Boolean
   MsgBox ("The file " + Item.Spec + " is about to be " + _
   "unchecked out from " + LocalSpec)
   VSSHandler_BeforeUndoCheckOut = True
End Function
Sub VSSHandler_AfterUndoCheckOut(ByVal Item As IVSSItem, ByVal _
LocalSpec As String)
   MsgBox ("The file " + Item.Spec + " was just unchecked out from " + _
   "the folder " + LocalSpec)
End Sub
Function VSSHandler_BeginCommand(ByVal unused As Long) As Boolean
   MsgBox ("BeginCommand")
   VSSHandler_BeginCommand = True
End Function
Sub VSSHandler_EndCommand(ByVal unused As Long)
   MsgBox ("EndCommand")
End Sub
Function VSSHandler_BeforeEvent(ByVal iEvent As Long, ByVal Item _
As IVSSItem, ByVal Str As String, ByVal Var As Variant) As Boolean
   MsgBox ("BeforeEvent")
   VSSHandler_BeforeEvent = True
End Function

Sub VSSHandler_AfterEvent(ByVal iEvent As Long, ByVal Item As _
IVSSItem, ByVal Str As String, ByVal Var As Variant)
   MsgBox ("AfterEvent")
End Sub

Now that we have coded each procedure exposed by the interface, we can compile our DLL. Once this is accomplished, use RegEdit to located the ProgID of the DLL. This can be done by searching the registry for the string <ProjectName>.<ClassName> and then opening the ProgID key for the entry. If you used the name Project1 for your DLL and the name Class1 for your Class module, by default the ProgID will be Project1.Class1.

Now we need to let SourceSafe know about our add-in. We accomplish this by modifying or creating the text file ssaddin.ini. This file must reside in the same folder as ssapi.dll. By default, this is the …\VSS\WIN32 folder. After opening or creating the file, add a reference to our add-in using the syntax:

<ProgID>=1

For example, if our ProgID is Project1.Class1, we would need to add the line:

Project1.Class1=1

After adding the reference and closing the file, we are ready to test our add-in. Launch SourceSafe, log on to a database, and add, check out, check in, rename, and undo checkout of some files. You should now be seeing message boxes describing each of these events.

To turn off the add-in, simply remove its reference in the file ssaddin.ini, or set the reference equal to 0 instead of 1.

Note   To trap events in SourceSafe, each SourceSafe installation must have its own copy of ssaddin.ini and the ActiveX DLL (or add-in). For example, suppose you have SourceSafe installed on Server A and a client installation of SourceSafe on workstations B and C. The file ssaddin.ini must appear in the …\VSS\WIN32 folder of A, B, and C, and you must install and register the add-in on each system (A, B, and C).

If you were to add a third SourceSafe installation to the preceding example (workstation D) and not add both of these files, SourceSafe events that occur on workstation D will not be trapped (although events on A, B, and C will continue to be trapped).

Driving a SourceSafe Database

VSSCheckOut Object

The VSSCheckOut object represents a CheckOut of a file from a Visual SourceSafe database. Each Visual SourceSafe file maintains a record of all of its CheckOuts. This record is referred to as its CheckOuts collection. You may access this collection through Automation. This section describes the properties and methods of the VSSCheckOut object.

Properties

Comment As String (Read-only)

The Comment property of the VSSCheckOut object is used to return the comment applied at the time the CheckOut was made.

The following Visual Basic code demonstrates how to iterate through the CheckOuts collection of a file and print each comment (if any) that was applied to the CheckOut:

Dim objVSSCheckOut as VSSCheckOut
Dim objVSSFile as VSSItem
<…>
For Each objVSSCheckOut In objVSSFile.CheckOuts
   Debug.Print objVSSCheckOut.Comment
Next

The Comment property of a CheckOut object may be set when the file or project's CheckOut method is called.

Date As Date (Read-only)

The Date property of the VSSCheckOut object is used to return the date that the CheckOut occurred.

The following Visual Basic code demonstrates how to iterate through the CheckOuts collection of a file and print the date of each CheckOut of the file:

Dim objVSSCheckOut as VSSCheckOut
Dim objVSSFile as VSSItem
<…>
For Each objVSSCheckOut In objVSSFile.CheckOuts
   Debug.Print Str(objVSSCheckOut.Date)
Next

The format of the Date property is determined by the regional settings of the operating system and includes both the date and the time. The Date property of a CheckOut object is set when the file or project's CheckOut method is called.

LocalSpec As String (Read-only)

The LocalSpec property of the VSSCheckOut object is used to return the path to which the CheckOut occurred. This may or may not be the Working Folder of the file's parent project. The CheckOut's LocalSpec is set when the file or project's CheckOut method is called.

The following Visual Basic code demonstrates how to iterate through the CheckOuts collection of a file and print the LocalSpec for each CheckOut of the file:

Dim objVSSCheckOut as VSSCheckOut
Dim objVSSFile as VSSItem
<…>
For Each objVSSCheckOut In objVSSFile.CheckOuts
   Debug.Print objVSSCheckOut.LocalSpec
Next

The LocalSpec property of a CheckOut object returns the complete path of the checked-out folder but does not include the file name. For example, if the file $/MyFile.txt was checked out to C:\WorkingFolder, the LocalSpec property of the CheckOut will return C:\WorkingFolder, not C:\WorkingFolder\MyFile.txt. The LocalSpec property of a CheckOut object is set when the file or project's CheckOut method is called.

Machine As String (Read-only)

The Machine property of the VSSCheckOut object is used to return the machine name from which the CheckOut occurred. Occasionally, a SourceSafe user may check out a file from several different machines. For example, they may check out a file on their main system and then check the same file out on their laptop. This scenario becomes more complex when the user has checked the file out to identical working folders (the user may have checked the file out to C:\Working on both machines). The Machine property of the VSSCheckOut allows you to distinguish these CheckOuts by tagging the VSSCheckOut with the unique machine name.

The following Visual Basic code demonstrates how to iterate through the CheckOuts collection of a file and print the Machine property and CheckOut folder of each CheckOut of the file:

Dim objVSSCheckOut as VSSCheckOut
Dim objVSSFile as VSSItem
<…>
For Each objVSSCheckOut In objVSSFile.CheckOuts
   Debug.Print objVSSCheckOut.Machine
   Debug.Print objVSSCheckOut.LocalSpec
Next

The Machine property of a CheckOut object is set when the file or project's CheckOut method is called.

Project As String (Read-only)

The Project property of the VSSCheckOut object is used to return the project path from which the CheckOut occurred. In the case of shared files, a SourceSafe user may check out a file from one project and then check it in from another. Automation allows you to identify this situation through use of the Project property.

The following Visual Basic code demonstrates how to iterate through the CheckOuts collection of a file and print the Project property for each CheckOut of the file:

Dim objVSSCheckOut as VSSCheckOut
Dim objVSSFile as VSSItem
<…>
For Each objVSSCheckOut In objVSSFile.CheckOuts
   Debug.Print objVSSCheckOut.Project
Next

The Project property of a CheckOut object is set when the file or project's CheckOut method is called.

UserName As String (Read-only)

The UserName property of the VSSCheckOut object is used to return the name of the SourceSafe user that created the CheckOut.

The following Visual Basic code demonstrates how to iterate through the CheckOuts collection of a file and print the UserName property of each CheckOut of the file:

Dim objVSSCheckOut as VSSCheckOut
Dim objVSSFile as VSSItem
<…>
For Each objVSSCheckOut In objVSSFile.CheckOuts
   Debug.Print objVSSCheckOut.UserName
Next

The UserName property of a CheckOut object is set when the file or project's CheckOut method is called.

VersionNumber As Long (Read-only)

The VersionNumber property of the VSSCheckOut object is used to return the version number of the file when the CheckOut occurred. SourceSafe tracks the version number of every file and project within its database. The VersionNumber property is incremented each time the file is updated within the database.

The following Visual Basic code demonstrates how to iterate through the CheckOuts collection of a file and print the VersionNumber property of each CheckOut of the file:

Dim objVSSCheckOut as VSSCheckOut
Dim objVSSFile as VSSItem
<…>
For Each objVSSCheckOut In objVSSFile.CheckOuts
   Debug.Print Str(objVSSCheckOut.VersionNumber)
Next

The VersionNumber property of a CheckOut object is set when the file or project's CheckOut method is called.

VSSDatabase Object

The VSSDatabase object represents a Visual SourceSafe database. This section describes the properties and methods of the VSSDatabase object.

Properties

CurrentProject As String

The CurrentProject property of the database object is used to set or return the currently selected project in the Visual SourceSafe database as reflected in the current user's ss.ini file. This property does not change any pointers or references to the VSSItem. Use the VSSItem property of the database object to set the current file or project.

Each SourceSafe user has their own unique ss.ini file that contains their individual preferences for the SourceSafe Explorer. This file includes a reference to the most recently selected project in the database. The SourceSafe Explorer uses this setting to go to the last project visited by a user when they reopen SourceSafe.

The CurrentProject property may be used to set or return this value through Automation. For example, if a user opens Visual SourceSafe for the first time and visits a project called $/MyProject, the Visual Basic call:

objVSSDatabase.CurrentProject = "$/MyProject"

would set the CurrentProject setting of the user's ss.ini file to "$/MyProject" once the database object is released. You may retrieve this setting in code and set the current project object as appropriate.

DatabaseName As String (Read-only)

Using the SourceSafe Explorer, the SourceSafe Administrator can assign a default name to a database. The DatabaseName property returns this default database name (if any) assigned by the SourceSafe Administrator. In Visual Basic, this value may be retrieved using the following call:

strVar = objVSSDatabase.DatabaseName

This property does not assign or return the name of the database assigned by an individual user. If the administrator has not assigned a default database name, this property returns an empty string.

DefaultProjectRights As Long

The SourceSafe Administrator has the ability to add new users to the SourceSafe database Users collection. In Automation, this is accomplished through the AddUser method of the database object. The DefaultProjectRights property is used to set or return the default rights for a new user added to the SourceSafe database.

Note   The ProjectRightsEnabled property of the database must be set to true for this property to be effective. Only user Admin can change this property.

The only valid values for DefaultProjectRights are as follows.

Value Rights
0 No rights
1 Read rights
3 Read /check out/check in rights
7 Read /check out/check in/add/rename rights
15 Read /check out/check in/add/rename/destroy rights

Each of these values may be created through a combination of predefined constants exposed in the Automation interface. These constants are as follows.

Constant Value
VSSRIGHTS_READ 1
VSSRIGHTS_CHKUPD 2
VSSRIGHTS_ADDRENREM 4
VSSRIGHTS_DESTROY 8
VSSRIGHTS_ALL 15

You can programmatically create invalid values for DefaultProjectRights (values other than those just listed). An example is:

objVSSDatabase.DefaultProjectRights = _
VSSRIGHTS_DESTROY + VSSRIGHTS_READ

This combination (a value of 9) attempts to tell SourceSafe to give a new user destroy rights without the user having add/rename/check out/check in rights. These invalid combinations are not supported.

Note   Invalid DefaultProjectRights combinations do not generate run-time errors but will produce unexpected results.

ProjectRightsEnabled As Boolean

The ProjectRightsEnabled property of the database object is used to set or return if project rights are enabled for all SourceSafe users. This Boolean value may be set with the following Visual Basic command:

objVSSDatabase.ProjectRightsEnabled = True

or retrieved with this command:

boolVar = objVSSDatabase.ProjectRightsEnabled

Only user Admin can access this property. In Visual Basic, if any other user attempts to access this property, the run-time error -2147166522 is generated. If you change this setting through the Automation interface and close the database object, the SourceSafe Explorer and the Admin utility will use the new setting the next time they are launched.

SrcSafeIni As String (Read-only)

The SrcSafeIni property of the database object is used to return the complete path to the current SourceSafe database's srcsafe.ini file. If an instance of the database object has been created in Visual Basic, you may use the call:

strVar = objVSSDatabase. SrcSafeIni

to return the current srcsafe.ini path at any time. To change the current SrcSafeIni property, you must use the Open method of the VSSDatabase object and create an instance of a new database object.

The Automation interface allows you to open multiple databases simultaneously; however, a specific database object may reference only one database at one time. The following Visual Basic code demonstrates how to close a database object:

Set objVSSDatabase = Nothing

The SrcSafeIni property includes the file name srcsafe.ini. Using the Open method of the database object with a SrcSafeIni variable of "C:\VSS" will fail while the value "C:\VSS\SRCSAFE.INI" will succeed.

See the "Open Method" topic of the "VSSDatabase Object" section for more information.

User (Name As String) As VSSUser (Read-only)

Every SourceSafe database has one or more users (such as Admin and Guest). In Automation, each user may be created as an object type known as a VSSUser. The VSSUser object has several properties and methods, such as Name, Password, Delete, and RemoveProjectRights. (For a complete description of these and other properties and methods see the "VSSUser Object" section in this article.) The User property of the database object may be used to reference any VSSUser in the database object.

The User property accepts a single parameter:

Name. This required string variable contains the name of the user you want to reference.

For example, the following Visual Basic code demonstrates how to create an instance of a VSSUser object and print the user's name:

Dim objVSSUser As VSSUser
Dim strUserName As String
strUserName = "Guest"
<…>
Set objVSSUser = objVSSDatabase.User(strUserName)
Debug.Print objVSSUser.Name

Here, another example demonstrates how to set the password for a SourceSafe user:

Dim objVSSUser As VSSUser
Dim strUserName As String
strUserName = "Guest"
<…>
Set objVSSUser = objVSSDatabase.User(strUserName)
objVSSUser.Password = strVar

To change the password for any given user you must be logged on as user Admin or logged on as the specific user for whom you wish to change the password.

You may add or remove users from the Users collection using the objVSSDatabase.AddUser or the VSSUser.Delete methods, respectively.

UserName As String (Read-only)

The UserName property of the database object is used to return the name of the Visual SourceSafe user currently logged into the SourceSafe database. In Visual Basic, you may use the call:

strVar = objVSSDatabase. UserName

to return the current user's logon name at any time. To change the currently logged-on user, you must use the Open method of the VSSDatabase object and create an instance of a new database object.

The Automation interface allows you to open multiple databases simultaneously; however, a specific database object may reference only one database at one time. The following Visual Basic code demonstrates how to close a database object:

Set objVSSDatabase = Nothing

See the "Open Method" topic of the "VSSDatabase Object" section for more information.

Users As IVSSUsers (Read-only)

The Users property of the database object is used to reference all users within the SourceSafe database (also known as the Users Collection object). The following Visual Basic code demonstrates how to list all users in the current Visual SourceSafe database:

Dim objVSSUser As VSSUser
<…>
For Each objVSSUser In objVSSDatabase.Users
   Debug.Print objVSSUser.Name
Next User

You may add or remove users from the Users collection using the objVSSDatabase.AddUser or the VSSUser.Delete methods, respectively.

VSSItem (Spec As String, [Deleted As Boolean = False]) As VSSItem (Read-only)

The VSSItem property of the database object is used to return information on a created instance of a VSSItem object. A VSSItem object represents either a SourceSafe project or a SourceSafe file (either of which may be deleted or non-deleted). You can use the Type property of the VSSItem to determine what type of object (project or file) the VSSItem represents.

The VSSItem object has many properties and methods, such as Deleted and Binary or CheckIn and CheckOut. For a complete listing of these properties and methods, please see the "VSSItem Object" section in this article.

The database object's VSSItem property accepts two parameters:

  • Spec: This required string variable is used to retrieve the complete SourceSafe path of the VSSItem. Examples are "$/" and $/MyProject/MyFile.txt."
  • Deleted: This optional Boolean variable is used to tell Automation whether to look for deleted or non-deleted items in the current call. If this parameter is set to false, only non-deleted items are included. When it is set to true, only deleted items are included. The default for this parameter is false.

The following Visual Basic sample iterates each item in a SourceSafe project and prints the object's name, ignoring both deleted items and subprojects:

Dim objVSSProject As VSSItem
Dim objVSSObject As VSSItem
<…>
For Each objVSSObject In objVSSProject.Items(False)
   If objVSSObject.Type = VSSITEM_FILE Then
      Debug.Print ("I am a non-deleted file named: " + _
      objVSSObject.Name)
   End If
Next

Conversely, to list all deleted subprojects in a given project the following code may be used:

Dim objVSSProject As VSSItem
Dim objVSSObject As VSSItem
<…>
For Each objVSSObject In objVSSProject.Items(True)
   If objVSSObject.Type = VSSITEM_PROJECT Then
      Debug.Print ("I am a deleted subproject named: " + _ 
      objVSSObject.Name)
   End If
Next

The following Visual Basic code demonstrates how to create an instance of a new VSSItem object:

Dim objVSSFile As VSSItem
Dim strItemPath As String
<…>
Set objVSSFile = objVSSDatabase.VSSItem(strItemPath)

Note that the string variable ItemPath may be used to represent either a SourceSafe project or a file item. For example, both 

strItemPath = "$/"
strItemPath = "$/MyProject/MyFile.txt"

are equally valid in the preceding example.

Methods

AddUser (User As String, Password As String, ReadOnly As Boolean) As VSSUser

The SourceSafe Administrator has the ability to add new users to the current SourceSafe database. In Automation, this is accomplished through the AddUser method of the database object. This method adds a new user to the current database object's Users collection. This method has the following parameters:

  • User: This required string parameter contains the unique name of a new user to add to the database. If you attempt to add a user that already exists, the Visual Basic run-time error -2147166525 will be generated.
  • Password: This required string is used to specify the password for the new user. If you attempt to give the user an invalid password the Visual Basic run-time error -2147352566 will be generated. An empty string will set the password to nothing.
  • ReadOnly: This required Boolean variable is used to specify if the new user has read-only rights to the database. If this property is set to true, it overrides the DefaultProjectRights settings of the database. For example, if DefaultProjectRights is set to VSSRIGHTS_ALL, and a new user is added to the database with the ReadOnly parameter set to true, the new user will have read-only rights to the database, not VSSRIGHTS_ALL. If the ReadOnly parameter is set to false, the new user is given whatever rights are assigned to the value DefaultProjectRights.

The following Visual Basic code demonstrates how to add a new user to a SourceSafe database:

Dim objUserToAdd As VSSUser
Dim strName as String
Dim strPassword As String
Dim Rights As Boolean 
<…>
Set objUserToAdd = objVSSDatabase.AddUser(strName, strPassword,  _
Rights)

The AddUser method may be called only by user Admin. In Visual Basic, if any other user attempts to call the AddUser method, the run-time error -2147166522 will be generated.

Open ([SrcSafeIni As String], [Username As String], [Password As String])

The Open method of the database object is used to create an instance of a database object. The Automation interface allows you to open multiple databases simultaneously, however a specific database object may reference only one database at one time. The Open method accepts the following three parameters:

  • SrcSafeIni: This optional string parameter is used to specify the complete path to the current SourceSafe database's srcsafe.ini file. The SrcSafeIni parameter includes the file name srcsafe.ini. Using the Open method of the database object with a SrcSafeIni variable of "C:\VSS" will fail, while the value "C:\VSS\SRCSAFE.INI" will succeed. In Visual Basic, if an invalid path is passed, the run-time error -2147167977 will be generated. When this parameter is not passed, SourceSafe looks for the srcsafe.ini in the following order:
    • Search for srcsafe.ini in the directory where ssapi.dll is located.
    • Search for srcsafe.ini in each directory of the path to ssapi.dll. In other words, if ssapi.dll is located in C:\Folder1\Folder2\Folder3\SSAPI.DLL, Folder3, Folder2, Folder1 and C:\ are searched (in that order).
    • Search for srcsafe.ini in the location indicated by the named value "API Current Database" in the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\SourceSafe.
    • Search for srcsafe.ini in the location indicated by the named value "SCCProviderPath" in the registry key HKEY_LOCAL_MACHINE\Software\Microsoft\SourceSafe.
  • UserName: This optional string parameter is used to specify the name of the Visual SourceSafe user currently logging into the SourceSafe database. In Visual Basic, if an invalid UserName is passed, the run-time error -2147166526 will be generated. The default value of this parameter is the name of the user logged into the Windows session.
  • Password: This optional string parameter is used to specify the password of the Visual SourceSafe user attempting to log into the SourceSafe database. If the user has no password, you must pass an empty string. The default value of this parameter is an empty string. In Visual Basic, if an invalid password is passed, the run-time error -2147166519 will be generated.

The following Visual Basic code demonstrates using the Open method to create an instance of a database object:

Dim strSrcSafeIni As String
Dim strUserName As String
Dim strPassword As String
strSrcSafeIni = "C:\VSS\SRCSAFE.INI"
strUserName = "Guest"
strPassword = ""
<…>
' Attempt to log into SourceSafe
objVSSDatabase.Open strSrcSafeIni, strUserName, strPassword

The following Visual Basic code demonstrates how to close a created instance of a database object:

Set objVSSDatabase = Nothing
Note   Any user may call the Open method.

VSSFileStatus

The predefined VSSFileStatus constants may be used to determine the CheckOut status of a file object. These are used with the IsCheckedOut property of the file object and are defined as follows.

Constant Value
VSSFILE_NOTCHECKEDOUT 0
VSSFILE_CHECKEDOUT 1
VSSFILE_CHECKEDOUT_ME 2

The following Visual Basic code demonstrates how to determine the CheckOut status of a file. The sample uses the Select Case function against the IsCheckedOut property of the file object to determine whether it is checked out, checked out by multiple users, or not checked out:

Dim objVSSFile As VSSItem
Dim objVSSCheckOut As VSSCheckOut
Dim strUserName As String
Dim strOtherUser As String
Dim CheckOutMulti As Boolean
<…>
' Set UserName to the current VSS User
strUserName = objVSSDatabase.Username
Select Case objVSSFile.IsCheckedOut
                    
   ' File is checked out by current user
   Case VSSFILE_CHECKEDOUT_ME
   
      ' Check to see if the file is checked out by 
      ' current user only, or if the file is 
      ' checked out by multiple users 
      For Each objVSSCheckOut In objVSSFile.CheckOuts
         If objVSSCheckOut.UserName <> strUserName Then
            MsgBox ("File is checked out by current user and others.")
            CheckOutMulti = True
            Exit For
         EndIf   
      Next
      If Not CheckOutMulti Then 
         MsgBox ("File is checked out by current user only.")
      EndIf
   ' File is checked out by another user
   Case VSSFILE_CHECKEDOUT
                        
      ' Find the username. Since this will be the first item in the CheckOuts 
      ' Collection, get the name on the first pass and then exit for loop
      For Each objVSSCheckout In objVSSFile.Checkouts
         strOtherUser = objVSSCheckout.UserName
         Exit For
      Next
      ' Check for multiple CheckOuts
      For Each objVSSCheckOutOther In objVSSFile.CheckOuts
         If objVSSCheckoutOther.UserName <> strOtherUser Then
            MsgBox("File is checked out by more than one user and none _
            of  them is the current user.")
            CheckOutMulti = True
            Exit For
         End If
      Next
      If Not CheckOutMulti Then 
         MsgBox ("File is checked out by one other user only.")
      EndIf
                    
   ' File is not checked out
   Case Else
      MsgBox ("File is not checked out.")
                        
End Select
Note   The VSSFileStatus constants are not cumulative. In other words, if a file is checked out by the current user and checked out by another user, the IsCheckedOut property of the file object returns:
VSSFILE_CHECKEDOUT_ME

not

VSSFILE_CHECKEDOUT + VSSFILE_CHECKEDOUT_ME

VSSFlags (Flags Used within Automation)

The following predefined VSSFlags may be used to set or return a variety of Visual SourceSafe settings. Flags marked as default are used when no flag is specified. Flags that are used for a common setting are grouped together.

By default, SourceSafe automatically detects whether an added file is text or binary. It accomplishes this by checking the file for embedded null characters. Use these flags with the Add method of a project object to customize this behavior.

  • Const VSSFLAG_BINBINARY
  • When this flag is set, SourceSafe sets the added file type to binary.
  • Const VSSFLAG_BINTEST (default)
  • When this flag is set, SourceSafe auto-detects the added file's file type.
  • Const VSSFLAG_BINTEXT
  • When this flag is set, SourceSafe sets the added file type to text.

SourceSafe allows text files to be checked out by more than one user. Use these flags with the CheckOut method of a project or file object to customize this behavior. The Allow Multiple CheckOuts option (in the SourceSafe Admin utility) must be set for this flag to be effective. Currently, the Allow Multiple CheckOuts option is not exposed in Automation.

  • Const VSSFLAG_CHKEXCLUSIVENO (default if Allow Multiple CheckOuts is enabled)
  • When this flag is set, SourceSafe allows the item to be checked out by multiple users. If the Allow Multiple CheckOuts option in ssadmin.exe is not set, this flag is ignored, and all files are checked out exclusively.
  • Const VSSFLAG_ CHKEXCLUSIVEYES (default if Allow Multiple CheckOuts is disabled)
  • When this flag is set, SourceSafe prevents the item from being checked out by multiple users. If the Allow Multiple CheckOuts option in ssadmin.exe is not set, this flag is ignored, and all files are checked out exclusively.

SourceSafe allows the user to specify how it determines if the local copy of a file is up to date. Use these flags with the CheckIn and UnCheckOut methods of a project or file object to customize this behavior.

  • Const VSSFLAG_CMPCHKSUM (default)
  • This flag is used to tell SourceSafe to compare files through use of a checksum that it stores internally (this is the recommended method).
  • Const VSSFLAG_CMPFAIL
  • This flag is used to tell SourceSafe to always assume the local file is out of date.
  • Const VSSFLAG_CMPFULL
  • This flag is used to tell SourceSafe to compare the full contents of the local file to the SourceSafe copy.
  • Const VSSFLAG_CMPTIME
  • This flag is used to tell SourceSafe to compare files through use of the file's TimeStamp.

When calling the Add, UndoCheckOut, or CheckIn methods of an object, SourceSafe allows the user to customize whether the local file(s) are deleted. Use these flags to customize this behavior.

  • Const VSSFLAG_DELNO (default)

    When this flag is set, the local file(s) will not be deleted.

  • Const VSSFLAG_ DELYES

    When this flag is set, the local file(s) are deleted.

    • Const VSSFLAG_DELNOREPLACE

    When the checkout of a file is undone, SourceSafe allows the user to customize how the local file is handled. When this flag is set, the local file is left in its current condition with the read-only flag set to true. This flag should only be used with the UndoCheckOut method.

SourceSafe allows the user to determine whether a specific file retains its historical versions. Use these flags with the Add method to customize this behavior.

  • Const VSSFLAG_DELTANO

    When this flag is set, the file will not retain its historical versions.

  • Const VSSFLAG_DELTAYES (default)

    When this flag is set, the file will retain its historical versions.

SourceSafe can be told to append an end-of-line character whenever it retrieves a text file that does not already end with one. These flags are used to customize what type of end-of-line character is added. If no flags are used, the end-of-line character is not modified. Use these flags with the CheckOut, Get, and Branch methods.

Note   SourceSafe will change the default end-of-line character based on the operating system it is running on. The values described here apply to the Intel family of computers.
  • Const VSSFLAG_EOLCR

    When this flag is set, SourceSafe will append a carriage return to the end of all text files that do not already end in one.

  • Const VSSFLAG_EOLCRLF

    When this flag is set, SourceSafe will append a carriage return and line feed to the end of all text files that do not already end in one.

  • Const VSSFLAG_EOLLF

    When this flag is set, SourceSafe will append a line feed to the end of all text files that do not already end in one.

SourceSafe allows the user to determine whether a specific SourceSafe command acts on a project based on its working folder or its current folder. Use these flags with the Get, CheckOut, CheckIn, UndoCheckOut, and Branch methods to customize this behavior.

  • Const VSSFLAG_FORCEDIRNO

    When this flag is set, SourceSafe commands act on the current folder.

  • Const VSSFLAG_FORCEDIRYES(default)

    When this flag is set, SourceSafe commands act on the working folder.

When a file is checked out, SourceSafe allows the user to prevent the local copy from being copied to the CheckOut folder. Use these flags to customize this behavior.

  • Const VSSFLAG_GETNO

    When this flag is set, the CheckOut occurs, but the local file(s) in the working folder or VSSItem.LocalSpec are not replaced.

  • Const VSSFLAG_GETYES (default)

    When this flag is set, the CheckOut(s) occur and the local file(s) in the working folder or VSSItem.LocalSpec are replaced.

When creating an instance of a project object's Versions collection, you may choose to exclude its file histories. Use this flag to customize this setting.

  • Const VSSFLAG_HISTIGNOREFILES

    This flag may be used when creating an instance of the Versions collection of a project object. If this flag is set, file CheckIns are excluded from the current collection. The following Visual Basic code demonstrates use of this flag: 

    Set objVersionsCollection = _
objVSSObject.Versions(VSSFLAG_HISTIGNOREFILES)

When a file is checked in, SourceSafe allows the user keep the file(s) checked out. Use these flags to customize this setting.

  • Const VSSFLAG_KEEPNO (default)

    When this flag is set, the CheckIn occurs. (The local file is checked in and set to read-only.)

  • Const VSSFLAG_KEEPYES

    When this flag is set, the CheckIn occurs, and the file(s) remain checked out. (The local file(s) are checked in and remain read/write.)

Many methods exposed in the Automation interface may be called recursively. Use these flags with the CheckIn, CheckOut, Get, or Share methods of a project object to customize this behavior. These flags may also be used when creating an instance of the Versions collection of a project.

  • Const VSSFL