File Access and Multiuser Configuration API

Macromedia recommends that you always use the File Access and Multiuser Configuration API to access the file system through C-level extensions. For files other than configuration files, the functions access the specified file or folder.

Dreamweaver supports multiple-user configurations for the Windows XP, Windows 2000, and Mac OS X operating systems.

Typically, you install Dreamweaver in a restricted folder such as C:/Program Folders in Windows. As a result, only users with Administrator privileges can make changes in the Dreamweaver Configuration folder. To enable users on multiuser operating systems to create and maintain individual configurations, Dreamweaver creates a separate Configuration folder for each user. Whenever Dreamweaver or a JavaScript extension writes to the Dreamweaver Configuration folder, Dreamweaver automatically writes to the user Configuration folder instead. This process lets each user customize Dreamweaver configuration settings without disturbing the customized configurations of other users.

Dreamweaver creates the user Configuration folder in a location where the user has full read and write access. The location of the user's Configuration folder depends on the user's platform.

For Windows 2000 and Windows XP platforms:

 <drive>:\Documents and Settings\<username>\ Application Data\Macromedia\Dreamweaver 8 \Configuration 

NOTE

In Windows XP, this folder may be inside a hidden folder.

For Mac OS X platforms:

 <drive>:Users:<username>:Library:Application Support: Macromedia:Dreamweaver 8:Configuration 

There are many cases where JavaScript extensions open files and write to the Configuration folder. JavaScript extensions can access the file system by using DWFile, MMNotes, or passing a URL to the dreamweaver.getDocumentDOM() function. When an extension accesses the file system in a Configuration folder, it generally uses the dw.getConfigurationPath() function and adds the filename, or it gets the path by accessing the dom.URL property of an open document and adding the filename. An extension can also get the path by accessing the dom.URL and stripping the filename. The dw.getConfigurationPath() function and the dom.URL property always return a URL in the Dreamweaver Configuration folder, even if the document is located in the user Configuration folder.

Any time a JavaScript extension opens a file in the Dreamweaver Configuration folder, Dreamweaver intercepts the access and checks the user Configuration folder first. If a JavaScript extension saves data to disk in the Dreamweaver Configuration folder through DWFile or MMNotes, Dreamweaver intercepts the call and redirects it to the user Configuration folder.

For example, in Windows 2000 or Windows XP, if the user asks for "file:///C|/Program Files/Macromedia/Dreamweaver/Configuration/Objects/Common/Table.htm", Dreamweaver searches for a Table.htm file in the C:/Documents and Settings/username/Macromedia/Dreamweaver/Configuration/Objects/Common folder and, if it exists, uses it instead.

C-level extensions, or shared libraries, must use the File Access and Multiuser Configuration API to read and write to the Dreamweaver Configuration folder. Using the File Access and Multiuser Configuration API lets Dreamweaver read and write to the user Configuration folder and ensures that the file operations do not fail due to insufficient access privileges. If your C-level extension accesses files in the Dreamweaver Configuration folder that were created through JavaScript with DWFile, MMNotes, or DOM manipulations, it is essential that you use the File Access and Multiuser Configuration API because these files might be located in the user Configuration folder.

NOTE

Most JavaScript extensions do not need to be changed to write to the user Configuration folder. Only C shared libraries that write to the Configuration folder need to be updated to use the File Access and Multiuser Configuration API functions.

When you delete a file from the Dreamweaver Configuration folder, Dreamweaver adds an entry to a mask file to indicate which files in the Configuration folder should not appear in the user interface. A masked file or folder does not appear to exist to Dreamweaver although it might physically exist in the folder.

For example, if you use the trash can icon in the Snippets panel to delete a Snippets folder called javascript and a file called onepixelborder.csn, Dreamweaver writes a file in the user Configuration folder called mm_deleted_files.xml, which looks like the following example:

 <?xml version = "1.0" encoding="utf-8" ?>   <deleteditems>   <item name="snippets/javascript/" />   <item name="snippets/html/onepixelborder.csn" />   </deleteditems> 

As Dreamweaver populates the Snippets panel, it reads all the files in the user's Configuration/Snippets folder and all the files in the Dreamweaver Configuration/Snippets folder, except the Configuration/Snippets/javascript folder and the Configuration/Snippets/html/onepixelborder.csn file, and it adds the resulting list of files to the Snippets panel list.

If a C-level extension calls the MM_ConfigFileExists() function for the file:///c|Program Files/Macromedia/Dreamweaver/Configuration/Snippets/javascript/onepixelborder.csn URL, it returns a value of false. Likewise, if a JavaScript extension tries to call dw.getDocumentDom("file:///c|Program Files/Macromedia/Dreamweaver/Configuration/Snippets/javascript/onepixelborder.csn"), it returns a null value.

You can modify the mm_deleted_files.xml file to prevent Dreamweaver from showing files in the user interface, such as objects, canned content in the new dialog box, and so on. You can call the MM_DeleteConfigfile() function to add file paths to the mm_deleted_files.xml file.

JS_Object MM_GetConfigFolderList()

Availability

Dreamweaver MX.

Description

This function gets a list of files, folders, or both for the specified folder. If you specify a configuration folder, the function gets a list of the folders that exists in both the user Configuration folder and the Dreamweaver Configuration folder, subject to filtering by the mm_deleted_files.xml file.

Arguments

 char *fileURL, char *constraints 

• The char *fileUrl argument is a pointer to a string that names the folder for which you want a list of the contents. The string must have the format of a file:// URL. The function accepts valid wildcard characters of asterisks (*) and question marks (?) in the file:// URL string. Use asterisks (*) to represent one or more unspecified characters, and question marks (?) to represent a single unspecified character.

• The char *contstraints argument can be "files" or "directories" or a null value. If you specify null, the MM_GetConfigFolderList() function returns files and folders.

Returns

JSObject is an array that contains the list of files or folders in either the user Configuration folder or the Dreamweaver Configuration folder, subject to filtering by the mm_deleted_files.xml file.

Examples

 JSObject *jsobj_array; jsobj_array = MM_GetConfigFolderList("file:/// c|/Program Files/Macromedia/Dreamweaver /Configuration", "directories" ); 

JSBool MM_ConfigFileExists()

Availability

Dreamweaver MX.

Description

This function checks whether the specified file exists. If it is a file in a configuration folder, the function searches for the file in the user Configuration folder or the Dreamweaver Configuration folder. The function also checks whether the filename is listed in the mm_deleted_files.xml file. If the name is listed in this file, the function returns a false value.

Arguments

 char *fileUrl 

• The char *fileUrl argument is a pointer to a string that names the desired file, which is provided in the format of a file:// URL.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

Example

 char *dwConfig = "file:///c|/Program Files/Macromedia/Dreamweaver/Configuration/Extensions .txt"; int fileno = 0; if(MM_ConfigFileExists(dwConfig)) {   fileno = MM_OpenConfigFile(dwConfig, "read"); } 

int MM_OpenConfigFile()

Availability

Dreamweaver MX.

Description

This function opens the file and returns an operating system file handle. You can use the operating system file handle in calls to system file functions. You must close the file handle with a call to the system _close function.

If the file is a configuration file, it finds the file in either the user Configuration folder or the Dreamweaver Configuration folder. If you open the Configuration file for writing, the function creates the file in the user Configuration folder, even if it exists in the Dreamweaver Configuration folder.

NOTE

If you want to read the file before writing to it, open the file in "read" mode. When you want to write to the file, close the read handle and open the file again in "write" or "append" mode.

Arguments

 char *fileURL, char *mode 

• The char *fileURL argument is a pointer to a string that names the file that you are opening, which is provided as a file:// URL. If it specifies a path in the Dreamweaver Configuration folder, the MM_OpenConfigFile() function resolves the path before opening the file.

• The char *mode argument points to a string that specifies how you want to open the file. You can specify null, "read", "write", or "append" mode. If you specify "write" and the file does not exist, the MM_OpenconfigFile() function creates it. If you specify "write", the MM_OpenConfigFile() function opens the file with an exclusive share. If you specify "read", the MM_OpenConfigFile() function opens the file with a nonexclusive share.

  If you open the file in "write" mode, any existing data in the file is truncated before writing new data. If you open the file in "append" mode, any data you write is appended to the end of the file.

Returns

An integer that is the operating system file handle for this file. Returns -1 if the file cannot be found or does not exist.

Example

 char *dwConfig = "file:///c|/Program Files/Macromedia/Dreamweaver/Configuration/Extensions .txt"; int = fileno; if(MM_ConfigFileExists(dwConfig)) {   fileno = MM_OpenConfigFile(dwConfig, "read"); } 

JSBool MM_GetConfigFileAttributes()

Availability

Dreamweaver MX.

Description

This function finds the file and returns the attributes of the file. You can set any of the arguments except fileURL to null if you do not need the value.

Arguments

 char *fileURL, unsigned long *attrs, unsigned long *filesize, unsigned long *modtime,  unsigned long *createtime 

• The char *fileURL argument is a pointer to a string that names the file for which you want the attributes. You must provide this argument as a file:// URL. If fileURL specifies a path in the Dreamweaver Configuration folder, the MM_GetConfigFileAttributes() function resolves the path before opening the file.

• The unsigned long *attrs argument is the address of an integer that contains the returned attribute bits (see JSBool MM_SetConfigFileAttributes() for available attributes).

• The unsigned long *filesize argument is the address of an integer in which the function returns the file size in bytes.

• The unsigned long *modtime argument is the address of an integer in which the function returns the time that the file was last modified. The time is given as the operating-system time value. For more information about the operating-system time value, see DWfile.getModificationDate() in the Dreamweaver API Reference.

• The unsigned long *createtime argument is the address of an integer in which the function returns the time that the file was created. The time is given as the operating-system time value. For more information on the operating system time value, see DWfile.getCreationDate() in the Dreamweaver API Reference.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. Returns JS_FALSE if the file does not exist or an error occurs while getting the attributes.

Example

 char dwConfig = "file:///c|/Program Files/Macromedia/Dreamweaver/Configuration/Extensions .txt"; unsigned long attrs; unsigned long filesize; unsigned long modtime; unsigned long createtime; MM_GetConfigAttributes(dwConfig, &attrs, &filesize, &modtime, &createtime); 

JSBool MM_SetConfigFileAttributes()

Availability

Dreamweaver MX.

Description

This function sets the attributes that you specify for the file, if they are different from the current attributes.

If the specified file URL is in the Dreamweaver Configuration folder, this function first copies the file to the user Configuration folder before it sets the attributes. If the attributes are the same as the current file attributes, the file is not copied.

Arguments

 char *fileURL, unsigned long attrs 

• The char *fileURL argument is a pointer to a string that names the file for which you want to set the attributes, which is provided as a file:// URL.

• The unsigned long attrs argument specifies the attribute bits to set on the file. You can use a logical OR on the following constants to set the attributes:

   MM_FILEATTR_NORMAL MM_FILEATTR_RDONLY MM_FILEATTR_HIDDEN MM_FILEATTR_SYSTEM MM_FILEATTR_SUBDIR 

  
  

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure. Returns JS_FALSE if the file does not exist or it is marked for deletion.

Example

 char *dwConfig = "file:///c|/Program Files/Macromedia/Dreamweaver/Configuration/Extensions .txt"; unsigned long attrs; attrs = (MM_FILEATTR_NORMAL | MM_FILEATTR_RDONLY); int fileno = 0; if(MM_SetConfigFileAttrs(dwConfig, attrs)) {   fileno = MM_OpenConfigFile(dwConfig); } 

JSBool MM_CreateConfigFolder()

Availability

Dreamweaver MX.

Description

This function creates a folder in the specified location.

If the fileURL argument specifies a folder within the Dreamweaver Configuration folder, the function creates the folder in the user Configuration folder. If fileURL does not specify a folder in the Dreamweaver Configuration folder, the function creates the specified folder, including all higher-level folders in the path if they do not already exist.

Arguments

 char *fileURL 

• The char *fileURL argument is a pointer to a file:// URL string that names the configuration folder that you want to create.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

Example

 char *dwConfig = "file:///c|/Program Files\Macromedia\Dreamweaver\Configuration\Extensions .txt"; MM_CreateConfigFolder(dwConfig); 

JSBool MM_RemoveConfigFolder()

Availability

Dreamweaver MX.

Description

This function removes the folder and its files and subfolders. If the folder is in the Dreamweaver Configuration folder, it marks the folder for deletion in the mm_deleted_files.xml file.

Arguments

 char *fileURL 

• The char *fileURL argument is a pointer to a string that names the folder to remove, which is provided as a file:// URL.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

Example

 char *dwConfig = "file:///c|/Program Files\Macromedia\Dreamweaver\Configuration\Objects"; MM_RemoveConfigFolder(dwConfig); 

JSBool MM_DeleteConfigFile()

Availability

Dreamweaver MX.

Description

This function deletes the file, if it exists. If the file exists below the Dreamweaver Configuration folder, the function marks the file for deletion in the mm_deleted_files.xml file.

If the fileURL argument does not specify a folder in the Dreamweaver Configuration folder, the function deletes the specified file.

Arguments

 char *fileURL 

• The char *fileURL argument is a pointer to a string that names the configuration folder to remove, which is provided as a file:// URL.

Returns

A Boolean value: JS_TRUE indicates success; JS_FALSE indicates failure.

Example

 char dwConfig = "file:///c:|Program Files\Macromedia\Dreamweaver \Configuration\Objects \insertbar.xml"; MM_DeleteConfigFile(dwConfig);