MSPL Script Syntax

Following are lists that summarize the features that MSPL does and does not support.

Supported Features

Unsupported Features

Because string values are delimited by double quotes, you must use the backslash (\) to escape double quotes contained within a string. For example, represent the string preamble "message" postamble as follows: "preamble \"message\" postamble".

Represent Unicode literals using the \u character sequence followed by the specific 4-digit code. For example, represent the Cyrillic capital "psi" character as follows: \u0470.

Prefixing a string with the "@" (at) symbol to disable backslash escape sequences is not supported.

A function is the only declarative element in MSPL. Declare a function within a script using the following syntax:

functionidentifier (optional_parameter_list) statement

For example:

	Copy Code
function ParseDisplayName (displayName) { ... }

All function definitions must occur at the beginning of the message filter script, before the body of the message filter script. A function can have zero or more parameters.

Function definitions cannot contain recursion of any type. For example, Function 1 cannot be defined such that it calls Function 1, nor can Function 1 be defined such that it calls Function 2 if Function 2 is defined such that it calls Function 1.

Functions pass parameters by value, and the type of the value that is passed as a parameter implicitly defines the parameter type.

Return value types are also implicitly defined. In other words, the return type is determined by the type of the value that is passed to the return statement. However, the only supported implicit return types are string, bool, int, and float. Functions cannot return collections.

In the following example filter function, if the content that is passed in to the function contains the word "confidential", the function returns true, otherwise it returns false.

	Copy Code
function FilterString (content) { filterWord ="confidential"; return ContainsString(content, filterWord, true); }

The foreach statement allows script authors to handle collections that commonly occur while processing SIP messages, such as contact header and endpoint collections. A foreach loop is invoked with the following syntax:

foreach (elementinexpression) statement

For example:

	Copy Code
foreach (dbEndpoint in QueryEndpoints("someone@example.com")) { ... }

The expression will evaluate to a collection. Strings and other unary types are treated as single-item collections. Note that collections cannot be created except by calling a built-in function that returns a collection (such as QueryEndpoints), or by referencing a built-in variable that contains a collection.

Inside a foreach loop, the continue statement is used to jump to the next iteration of the loop, ignoring any processing statements subsequent to the continue statement before the end of the loop.

The break statement allows for the early termination of a switch/case branch or a foreach loop. The syntax is the same as in C#.

A break statement must be present at the end of each case branch in a switch statement. "Fall-through" caused by case branches without a terminating break statement is not allowed.

Adding the null keyword enables script applications to distinguish between an empty string ("") and values that are not found. Applications written for Live Communications Server 2003 will continue to return the empty string. Passing null to any function that expects a string parameter will generate a script error and cause the script to be terminated. The following functions will return null to indicate a value not found or an error:

• GetDisplayName

• GetHostName

• GetParameterValue

• GetScheme

• GetUri

• GetUriParameter

• GetUserName

• GetUserAtHost

• QueryHomeServer

In addition, Message.Stamp and Message.StampPool can both return null.

MSPL supports the access of data in flat files through the use of the following array syntax, where placeholder values are shown in italics:

flatFileName[index].columnName

Following are explanations of the placeholder values.

flatFileName

Specifies the value of the name attribute for the <file> element that identifies the file from which you want to read data.

Index

Specifies a zero-based integer or key string. Key strings are valid only if the keyColumnName attribute for the <file> element is specified, in which case the record index is looked up in an in-memory hash table. Integer indexes greater than or equal to the number of records, or a key string value that is not found in the in-memory hash table, cause the reference to return null. Key string references to a flat file with no in-memory hash table generate a script error and cause script execution to be aborted.

columnName

Specifies the value of the name attribute for the <column> element from which you want to read data. The specified <column> must be contained within the <file> element specified by the value of flatFileName.

Following is an example <file> element as it might appear in an application manifest file. The <file> element identifies information about the location and structure of a particular flat file that the application uses.

	Copy Code
<file name="exampleFile" path=".\hostname.csv" keyColumnName="keyHostName" ignoreCase="true" static="true" delimitedBy="comma"> <column name="keyHostName"/> <column name="valueTargetHost"/> </file>

The handle name for the file in this example is "exampleFile", and it is a csv file. When the application loads this file in memory, it creates a hash table containing two columns named "keyHostName" and "valueTargetName". By assigning the value "keyHostName" to the keyColumnName attribute, the example indicates that the values contained in the "keyHostName" column will serve as key string indexers for the in-memory hash table.

For more information on the content of the <file> element, see the topic file Element.

In the following example script, the GetHostName function gets the host name portion of a URI. The MSPL expression on the right-hand side uses the host name as the key string index to look up the corresponding value string in the "valueTargetHost" column of the hash table created for "exampleFile", and assigns this value to "targetHost".

	Copy Code
targetHost = exampleFile[GetHostName(sipRequest.RequestUri)].valueTargetHost;