The Source Control Integration API optional functions

The Source Control Integration API has required and optional functions. The functions in this section are optional.

bool SCS_GetConnectionInfo()

Description

This function displays a dialog box to let the user change or set the connection information for this site. It does not make the connection. This function is called when the user clicks the Settings button in the Remote Info section of the Edit Sites dialog box.

Arguments

 void **connectionData, const char siteName[64] 

• The connectionData argument is a handle to data that the agent wants Dreamweaver to pass it when calling other API functions.

• The siteName argument is a string that points to the name of the site. The name cannot exceed 64 characters.

Returns

A Boolean value: true if successful; false otherwise.

bool SCS_SiteDeleted()

Description

This function notifies the DLL that the site has been deleted or that the site is no longer tied to this source control system. It indicates that the source control system can delete its persistent information for this site.

Arguments

 const char siteName[64] 

• The siteName argument is a string that points to the name of the site. The name cannot exceed 64 characters.

Returns

A Boolean value: true if successful; false otherwise.

bool SCS_SiteRenamed()

Description

This function notifies the DLL when the user has renamed the site so that it can update its persistent information about the site.

Arguments

 const char oldSiteName[64], const char newSiteName[64] 

• The oldSiteName argument is a string that points to the original name of the site before it was renamed. The name cannot exceed 64 characters.

• The newSiteName argument is a string that points to the new name of the site after it was renamed. The name cannot exceed 64 characters.

Returns

A Boolean value: TRue if successful; false otherwise.

int SCS_GetNumNewFeatures()

Description

This function returns the number of new features to add to Dreamweaver (for example, File History, Differences, and so on).

Arguments

None.

Returns

An integer that indicates the number of new features to add to Dreamweaver. If the function returns < 0, Dreamweaver considers it an error and tries to retrieve the error message from the DLL, if supported.

bool SCS_GetNewFeatures()

Description

This function returns a list of menu items to add to the Dreamweaver main and context menus. For example, the Sourcesafe DLL can add History and File Differences to the main menu.

Arguments

 char menuItemList[][32], scFunction functionList[], scFunction enablerList[], const int  numNewFeatures 

• The menuItemList argument is a string list that is populated by the DLL; it specifies the menu items to add to the main and context menus. Each string can contain a maximum of 32 characters.

• The functionList argument is populated by the DLL; it specifies the routines in the DLL to call when the user selects the corresponding menu item.

• The enablerList argument is populated by the DLL; it specifies the routines in the DLL to call when Dreamweaver needs to determine whether the corresponding menu item is enabled.

• The numNewFeatures argument is the number of items being added by the DLL; this value is retrieved from the GetNumNewFeatures() call.

The following function signature defines the functions and enablers that passed to the SCS_GetNewFeatures() call in the functionlist and enablerList arguments.

 bool (*scFunction)(void *connectionData, const char *remotePathList[],   const char *localPathList[], const int numItems) 

Returns

A Boolean value: true if successful; false otherwise.

bool SCS_GetCheckoutName()

Description

This function returns the check-out name of the current user. If it is unsupported by the source control system and this feature is enabled by the user, this function uses the Dreamweaver internal Check In/Check Out functionality, which transports LCK files to and from the source control system.

Arguments

 void *connectionData, char checkOutName[64], char emailAddress[64] 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The checkOutName argument is the name of the current user.

• The emailAddress argument is the e-mail address of the current user.

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_Checkin()

Description

This function checks a list of local files or folders into the source control system. The DLL is responsible for making the file read-only. If it is unsupported by the source control system and this feature is enabled by the user, this function uses the Dreamweaver internal Check In/Check Out functionality, which transports LCK files to and from the source control system.

Arguments

 void *connectionData, const char *localPathList[], const char *remotePathList[], bool  successList[], const int numItems 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The localPathList argument is a list of local filenames or folder paths to check in.

• The remotePathList argument is a mirrored list of remote filenames or folder paths.

• The successList argument is a list of Boolean values that are populated by the DLL to let Dreamweaver know which of the corresponding files are checked in successfully.

• The numItems argument is the number of items in each list.

Returns

A Boolean value: true if successful; false otherwise.

bool SCS_Checkout()

Description

This function checks out a list of local files or folders from the source control system. The DLL is responsible for granting the privileges that let the file be writable. If it is unsupported by the source control system and this feature is enabled by the user, this function uses the Dreamweaver internal Check In/Check Out functionality, which transports LCK files to and from the source control system.

Arguments

 void *connectionData, const char *remotePathList[], const char *localPathList[], bool  successList[], const int numItems 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePathList argument is a list of remote filenames or folder paths to check out.

• The localPathList argument is a mirrored list of local filenames or folder paths.

• The successList argument is a list of Boolean values that are populated by the DLL to let Dreamweaver know which of the corresponding files are checked out successfully.

• The numItems argument is the number of items in each list.

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_UndoCheckout()

Description

This function undoes the check-out status of a list of files or folders. The DLL is responsible for making the file read-only. If it is unsupported by the source control system and this feature is enabled by the user, this function uses the Dreamweaver internal Check In/Check Out functionality, which transports LCK files to and from the source control system.

Arguments

 void *connectionData, const char *remotePathList[], const char *localPathList[], bool  successList[], const int numItems 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePathList argument is a list of remote filenames or folder paths on which to undo the check out.

• The localPathList argument is a mirrored list of local filenames or folder paths.

• The successList argument is a list of Boolean values that are populated by the DLL to let Dreamweaver know which corresponding files' check outs are undone successfully.

• The numItems argument is the number of items in each list.

Returns

A Boolean value: true if successful; false otherwise.

int SCS_GetNumCheckedOut()

Description

This function returns the number of users who have a file checked out.

Arguments

 void *connectionData, const char *remotePath 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePath argument is the remote file or folder path to check to see how many users have it checked out.

Returns

An integer that indicates the number of people who have the file checked out. If the function returns < 0, Dreamweaver considers it an error and tries to retrieve the error message from the DLL, if supported.

bool SCS_GetFileCheckoutList()

Description

This function returns a list of users who have a file checked out. If the list is empty, no one has the file checked out.

Arguments

 void *connectionData, const char *remotePath, char checkOutList[][64], char  emailAddressList[][64], const int numCheckedOut 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePath argument is the remote file or folder path to check how many users have it checked out.

• The checkOutList argument is a list of strings that corresponds to the users who have the file checked out. Each user string cannot exceed a maximum length of 64 characters.

• The emailAddressList argument is a list of strings that corresponds to the users' e-mail addresses. Each e-mail address string cannot exceed a maximum length of 64 characters.

• The numCheckedOut argument is the number of people who have the file checked out. This is returned from GetNumCheckedOut().

Returns

A Boolean value: true if successful; false otherwise.

int SCS_GetErrorMessageLength()

Description

This function returns the length of the DLL's current internal error message. This allocates the buffer that passes into the GetErrorMessage() function. This function should be called only if an API function returns false or <0, which indicates a failure of that API function.

Arguments

 void *connectionData 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

Returns

An integer that represents the length of the error message.

bool SCS_GetErrorMessage()

Description

This function returns the last error message. If you implement getErrorMessage(), Dreamweaver calls it each time one of your API functions returns the value false.

If a routine returns -1 or false, it indicates an error message should be available.

Arguments

 void *connectionData, char errorMsg[], const int *msgLength 

The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The errorMsg argument is a preallocated string for the DLL to fill in with the error message.

• The msgLength argument is the length of the buffer represented by the errorMsg[] argument.

Returns

A Boolean value: TRue if successful; false otherwise.

int SCS_GetNoteCount()

Description

This function returns the number of Design Note keys for the specified remote file or folder path. If unsupported by the source control system, Dreamweaver gets this information from the companion MNO file.

Arguments

 void *connectionData, const char *remotePath 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePath argument is the remote file or folder path that the DLL checks for the number of attached Design Notes.

Returns

An integer that indicates the number of Design Notes that are associated with this file. If the function returns < 0, Dreamweaver considers it an error and tries to retrieve the error message from the DLL, if supported.

int SCS_GetMaxNoteLength()

Description

This function returns the length of the largest Design Note for the specified file or folder. If it is unsupported by the source control system, Dreamweaver gets this information from the companionMNO file.

Arguments

 void *connectionData, const char *remotePath 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePath argument is the remote file or folder path that the DLL checks for the maximum Design Note length.

Returns

An integer that indicates the size of the longest Design Note that is associated with this file. If the function returns < 0, Dreamweaver considers it an error and tries to retrieve the error message from the DLL, if supported.

bool SCS_GetDesignNotes()

Description

This function retrieves key-value pairs from the meta information for the specified file or folder. If it is unsupported by the source control system, Dreamweaver retrieves the information from the companionMNO file.

Arguments

 void *connectionData, const char *remotePath, char keyList[][64],   char *valueList[], bool showColumnList[], const int noteCount,   const int noteLength 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePath argument is the remote file or folder path that the DLL checks for the number of items.

• The keyList argument is a list of Design Note keys, such as "Status".

• The valueList argument is a list of Design Note values that correspond to the Design Note keys, such as "Awaiting Signoff".

• The showColumnList argument is a list of Boolean values that correspond to the Design Note keys, which indicate whether Dreamweaver can display the key as a column in the Site panel.

• The noteCount argument is the number of Design Notes that are attached to a file or folder; the GetNoteCount() call returns this value.

• The noteLength argument is the maximum length of a Design Note; this is the value that the GetMaxNoteLength() call returns.

Returns

A Boolean value: true if successful; false otherwise.

bool SCS_SetDesignNotes()

Description

This function stores the key-value pairs in the meta information for the specified file or folder. This replaces the set of meta information for the file. If it is unsupported by the source control system, Dreamweaver stores Design Notes in MNO files.

Arguments

 void *connectionData, const char *remotePath, const char keyList[][64],   const char *valueList[], bool showColumnList[], const int noteCount,   const int noteLength 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePath argument is the remote file or folder path that the DLL checks for the number of items.

• The keyList argument is a list of Design Note keys, such as "Status".

• The valueList argument is a list of Design Note values that corresponds to the Design Note keys, such as "Awaiting Signoff".

• The showColumnList argument is a list of Boolean values that correspond to the Design Note keys, which indicate whether Dreamweaver can display the key as a column in the Site panel.

• The noteCount argument is the number of Design Notes that are attached to a file or folder; this number lets the DLL know the size of the specified lists. If noteCount is 0, all the Design Notes are removed from the file.

• The noteLength argument is the length of the largest Design note for the specified file or folder.

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_IsRemoteNewer()

Description

This function checks each specified remote path to see if the remote copy is newer. If it is unsupported by the source control system, Dreamweaver uses its internal isRemoteNewer algorithm.

Arguments

 void *connectionData, const char *remotePathList[], const char *localPathList[], int  remoteIsNewerList[], const int numItems 

• The connectionData argument is a pointer to the agent's data that passed into Dreamweaver during the Connect() call.

• The remotePathList argument is a list of remote filenames or folder paths to compare for newer status.

• The localPathList argument is a mirrored list of local filenames or folder paths.

• The remoteIsNewerList argument is a list of integers that are populated by the DLL to let Dreamweaver know which of the corresponding files is newer on the remote side. The following values are valid: 1 indicates the remote version is newer; -1 indicates the local version is newer; 0 indicates the versions are the same.

• The numItems argument is the number of items in each list.

Returns

A Boolean value: true if successful; false otherwise.