The Source Control Integration API required functions

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

bool SCS_GetAgentInfo()

Description

This function asks the DLL to return its name and description, which appear in the Edit Sites dialog box. The name appears in the Server Access pop-up menu (for example, sourcesafe, webdav, perforce) and the description below the pop-up menu.

Arguments

 char name[32], char version[32], char description[256], const char *dwAppVersion 

• The name argument is the name of the source control system. The name appears in the combo box for selecting a source control system on the Source Control tab in the Edit Sites dialog box. The name can be a maximum of 32 characters.

• The version argument is a string that indicates the version of the DLL. The version appears on the Source Control tab in the Edit Sites dialog box. The version can be a maximum of 32 characters.

• The description argument is a string that indicates the description of the source control system. The description appears on the Source Control tab in the Edit Sites dialog box. The description can be a maximum of 256 characters.

• The dwAppVersion argument is a string that indicates the version of Dreamweaver that is calling the DLL. The DLL can use this string to determine the version and language of Dreamweaver.

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_Connect()

Description

This function connects the user to the source control system. If the DLL does not have log-in information, the DLL must display a dialog box to prompt the user for the information and must store the data for later use.

Arguments

 void **connectionData, const char siteName[64] 

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

• The siteName argument is a string that points to the name of the site. The site name can be a maximum of 64 characters.

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_Disconnect()

Description

This function disconnects the user from the source control system.

Arguments

 void *connectionData 

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

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_IsConnected()

Description

This function determines the state of the connection.

Arguments

 void *connectionData 

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

Returns

A Boolean value: TRue if successful; false otherwise.

int SCS_GetRootFolderLength()

Description

This function returns the length of the name of the root folder.

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 indicates the length of the name of the root folder. If the function returns < 0, Dreamweaver considers it an error and tries to retrieve the error message from the DLL, if supported.

bool SCS_GetRootFolder()

Description

This function returns the name of the root folder.

Arguments

 void *connectionData, char remotePath[], const int folderLen 

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

• The remotePath is a buffer where the full remote path of the root folder is stored.

• The folderLen argument is an integer that indicates the length of remotePath. This is the value that GeTRootFolderLength returns.

Returns

A Boolean value: TRue if successful; false otherwise.

int SCS_GetFolderListLength()

Description

This function returns the number of items in the passed-in folder.

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 full path and name of the remote folder that the DLL checks for the number of items.

Returns

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

bool SCS_GetFolderList()

Description

This function returns a list of files and folders in the passed-in folder, including pertinent information such as modified date, size, and whether the item is a folder or file.

Arguments

 void *connectionData, const char *remotePath, itemInfo itemList[ ], const int numItems 

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

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

• The itemList argument is a preallocated list of itemInfo structures:

  name	char[256]	Name of file or folder
  isFolder	bool	TRue if folder; false if file
  month	int	Month component of modification date 1-12
  day	int	Day component of modification date 1-31
  year	int	Year component of modification date 1900+
  hour	int	Hour component of modification date 0-23
  minutes	int	Minute component of modification date 0-59
  seconds	int	Second component of modification date 0-59
  type	char[256]	Type of file (if not set by DLL, Dreamweaver uses file extensions to determine type, as it does now)
  size	int	In bytes

  
  

• The numItems argument is the number of items that are allocated for the itemList (returned from GetFolderListLength).

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_Get()

Description

This function gets a list of files or folders and stores them locally.

Arguments

 void *connectionData, const char *remotePathList[], const char *localPathList[], 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 the remote files or folders to retrieve, which is specified as complete paths and names.

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

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

Returns

A Boolean value: true if successful; false otherwise.

bool SCS_Put()

Description

This function puts a list of local files or folders into the source control system.

Arguments

 void *connectionData, const char *localPathList[], const char *remotePathList[], 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 the list of local filenames or folder paths to put into the source control system.

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

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

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_NewFolder()

Description

This function creates a new folder.

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 full path of the remote folder that the DLL creates.

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_Delete()

Description

This function deletes a list of files or folders from the source control system.

Arguments

 void *connectionData, const char *remotePathList[], 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 delete.

• The numItems argument is the number of items in remotePathList.

Returns

A Boolean value: true if successful; false otherwise.

bool SCS_Rename()

Description

This function renames or moves a file or folder, depending on the values that are specified for oldRemotePath and newRemotePath. For example, if oldRemotePath equals "$/folder1/file1" and newRemotePath equals "$/folder1/renamefile1", file1 is renamed renamefile1 and is located in folder1.

If oldRemotePath equals "$/folder1/file1" and newRemotePath equals "$/folder1/subfolder1/file1", file1 is moved to the subfolder1 folder.

To find out if an invocation of this function is a move or a rename, check the parent paths of the two input values; if they are the same, the operation is a rename.

Arguments

 void *connectionData, const char *oldRemotePath, const char *newRemotePath 

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

• The oldRemotePath argument is a remote file or folder path to rename.

• The newRemotePath argument is the remote path of the new name for the file or folder.

Returns

A Boolean value: TRue if successful; false otherwise.

bool SCS_ItemExists()

Description

This function determines whether a file or folder exists on the server.

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 a remote file or folder path.

Returns

A Boolean value: true if successful; false otherwise.