The Design Notes C API

In addition to the JavaScript API, the MMNotes shared library also exposes a C API that lets other applications create Design Notes files. It is not necessary to call these C functions directly if you use the MMNotes shared library in Dreamweaver because the JavaScript versions of the functions call them.

This section contains descriptions of the functions, their arguments, and their return values. You can find definitions for the functions and data types in the MMInfo.h file in the Extending/c_files folder inside the Dreamweaver application folder.

void CloseNotesFile()

Description

This function closes the specified Design Notes file and saves any changes. If all key/value pairs are removed from the Design Note file, Dreamweaver deletes it. Dreamweaver deletes the _notes folder when the last Design Notes file is deleted.

Arguments

 FileHandle noteHandle 

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

Returns

Nothing.

BOOL FilePathToLocalURL()

Description

This function converts the specified local drive path to a file:// URL.

Arguments

 const char* drivePath, char* localURLBuf, int localURLMaxLen 

• The drivePath argument is a string that contains the full drive path.

• The localURLBuf argument is the buffer where the file:// URL is stored.

• The localURLMaxLen argument is the maximum size of localURLBuf.

Returns

A Boolean value: TRue indicates the operation is successful; false otherwise. The localURLBuf argument receives the file:// URL value.

BOOL GetNote()

Description

This function gets the value of the specified key in the specified Design Notes file.

Arguments

 FileHandle noteHandle, const char keyName[64], char* valueBuf, int valueBufLength 

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

• The keyName[64] argument is a string that contains the name of the key.

• The valueBuf argument is the buffer where the value is stored.

• The valueBufLength argument is the integer that GetNoteLength(noteHandle, keyName) returns, which indicates the maximum length of the value buffer.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The valueBuf argument receives the value of the key.

Example

The following code gets the value of the comments key in the Design Notes file that is associated with the welcome.html file:

 FileHandle noteHandle = OpenNotesFile("file:///c|/sites/avocado8/ iwjs/welcome.html"); if(noteHandle > 0){   int valueLength = GetNoteLength( noteHandle, "comments");   char* valueBuffer = new char[valueLength + 1   GetNote(noteHandle, "comments", valueBuffer, valueLength + 1);   printf("Comments: %s",valueBuffer);   CloseNotesFile(noteHandle); } 

int GetNoteLength()

Description

This function gets the length of the value that is associated with the specified key.

Arguments

 FileHandle noteHandle, const char keyName[64] 

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

• The keyName[64] argument is a string that contains the name of the key.

Returns

An integer that represents the length of the value.

Example

See "BOOL GetNote()" on page 550.

int GetNotesKeyCount()

Description

This function gets the number of key/value pairs in the specified Design Notes file.

Arguments

 FileHandle noteHandle 

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

Returns

An integer that represents the number of key/value pairs in the Design Notes file.

BOOL GetNotesKeys()

Description

This function gets a list of all the keys in a Design Notes file.

Arguments

 FileHandle noteHandle, char* keyBufArray[64], int keyArrayMaxLen 

• The noteHandle argument is the file handle that OpenNotesFile() returns.

• The keyBufArray[64] argument is the buffer array where the keys are stored.

• The keyArrayMaxLen argument is the integer that GetNotesKeyCount(noteHandle) returns, indicating the maximum number of items in the key buffer array.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The keyBufArray argument receives the key names.

Example

The following code prints the key names and values of all the keys in the Design Notes file that are associated with the welcome.html file:

 typedef char[64] InfoKey; FileHandle noteHandle = OpenNotesFile("file:///c|/sites/avocado8/ iwjs/welcome.html"); if (noteHandle > 0){   int keyCount = GetNotesKeyCount(noteHandle);   if (keyCount <= 0)     return;   InfoKey* keys = new InfoKey[keyCount];   BOOL succeeded = GetNotesKeys(noteHandle, keys, keyCount);   if (succeeded){     for (int i=0; i < keyCount; i++){       printf("Key is: %s\n", keys[i]);       printf("Value is: %s\n\n", GetNote(noteHandle, keys[i]);     }   }   delete []keys; } CloseNotesFile(noteHandle); 

BOOL GetSiteRootForFile()

Description

This function determines the site root for the specified Design Notes file.

Arguments

 const char* filePath, char* siteRootBuf, int siteRootBufMaxLen, {InfoPrefs* infoPrefs} 

• The filePath argument is the file://URL of the file for which you want the site root.

• The siteRootBuf argument is the buffer where the site root is stored.

• The siteRootBufMaxLen argument is the maximum size of the buffer that siteRootBuf references.

• The infoPrefs argument, which is optional, is a reference to a struct in which the preferences for the site are stored.

Returns

A Boolean value: TRue indicates the operation is successful; false otherwise. The siteRootBuf argument receives the address of the buffer that stores the site root. If you specify the infoPrefs argument, the function also returns the Design Notes preferences for the site. The InfoPrefs struct has two variables: bUseDesignNotes and bUploadDesignNotes, both of type BOOL.

BOOL GetVersionName()

Description

This function gets the version name of the MMNotes shared library, which indicates the application that implemented it.

Arguments

 char* versionNameBuf, int versionNameBufMaxLen 

• The versionNameBuf argument is the buffer where the version name is stored.

• The versionNameBufMaxLen argument is the maximum size of the buffer that the versionNameBuf argument references.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. Dreamweaver stores "Dreamweaver" in versionNameBuf argument.

BOOL GetVersionNum()

Description

This function gets the version number of the MMNotes shared library, which lets you determine whether certain functions are available.

Arguments

 char* versionNumBuf, int versionNumBufMaxLen 

• The versionNumBuf argument is the buffer where the version number is stored.

• The versionNumBufMaxLen argument is the maximum size of the buffer that versionNumBuf references.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The versionNumBuf argument stores the version number.

BOOL LocalURLToFilePath()

Description

This function converts the specified file:// URL to a local drive path.

Arguments

 const char* localURL, char* drivePathBuf, int drivePathMaxLen 

• The localURL argument, which is expressed as a file:// URL, is the path to a local file.

• The drivePathBuf argument is the buffer where the local drive path is stored.

• The drivePathMaxLen argument is the maximum size of the buffer that the drivePathBuf argument references.

Returns

A Boolean value: true indicates the operation is successful; false otherwise. The drivePathBuf argument receives the local drive path.

FileHandle OpenNotesFile()

Description

This function opens the Design Notes file that is associated with the specified file or creates one if none exists.

Arguments

 const char* localFileURL, {BOOL bForceCreate} 

• The localFileURL argument, which is expressed as a file:// URL, is a string that contains the path to the main file with which the Design Notes file is associated.

• The bForceCreate argument is a Boolean value that indicates whether to create the Design Notes file even if Design Notes is turned off for the site or if the path specified by the localFileURL argument is not associated with any site.

FileHandle OpenNotesFilewithOpenFlags()

Description

This function opens the Design Notes file that is associated with the specified file or creates one if none exists. You can open the file in read-only mode.

Arguments

 const char* localFileURL, {BOOL bForceCreate}, {BOOL bReadOnly} 

• The localFileURL argument, which is expressed as a file://URL, is a string that contains the path to the main file with which the Design Notes file is associated.

• The bForceCreate argument is a Boolean value that indicates whether to create the Design Notes file even if Design Notes are turned off for the site or the path is not associated with any site. The default value is false. This argument is optional, but you need to specify it if you specify the third argument.

• The bReadOnly argument, which is optional, is a Boolean value that indicates whether to open the file in read-only mode. The default value is false. You can specify the bReadOnly argument starting in version 2 of the MMNotes.dll file.

BOOL RemoveNote()

Description

This function removes the specified key (and its value) from the specified Design Notes file.

Arguments

 FileHandle noteHandle, const char keyName[64] 

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

• The keyName[64] argument is a string that contains the name of the key to remove.

Returns

A Boolean value: true indicates the operation is successful; false otherwise.

BOOL SetNote()

Description

This function creates or updates one key/value pair in a Design Notes file.

Arguments

 FileHandle noteHandle, const char keyName[64], const char* value 

• The noteHandle argument is the file handle that the OpenNotesFile() function returns.

• The keyName[64] argument is a string that contains the name of the key.

• The value argument is a string that contains the value.

Returns

A Boolean value: true indicates the operation is successful; false otherwise.