Learn about the Microsoft SIP Processing Language (MSPL) script syntax. This topic discusses supported and unsupported MSPL features and describes specific syntactical constructs.

MSPL script syntax

Supported features

  • Signed numeric constants

  • Unicode string literals

  • Array [] type (read-only for flat-file access)

  • Function invocation, with and without parameters

  • The structure member reference operator "." (for example: Structure.Member)

  • The following logical operators: "!", "==", "!=", "<", "<=", ">", ">="

  • Compound expressions

  • Compound statements

  • The "=" assignment operator

  • if/elsestatements

  • switch/casestatements

  • break, continue, and returnstatements

  • null keyword

  • true/false keywords

  • Expression statements

  • End-of-line and multiline comments

Unsupported features

  • Explicit (declarative) data types.

  • Type casting.

  • Pointers.

  • Arithmetic operations.

  • Function composition.

  • Preprocessor statements.

  • Attributes Static or global variables (state is not maintained across script invocations).

  • Declarations (other than basic function declarations, as detailed later in this topic).

    Note Note

    Although MSPL does not support explicit declaration, assignment expressions and foreachstatements implicitly declare variables and set their values. Such variables are statically (lexically) scoped. In other words, the scope of these variables is limited to the local block (for example, a function) in which they are declared.

String literals

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

Represent Unicode literals by using the \ucharacter 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 in a script by using the following syntax:

function identifier ( optional_parameter_list ) statement

For example:

  Copy codeCopy 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 so that it calls Function 1, nor can Function 1 be defined so that it calls Function 2 if Function 2 is defined so 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 filter function example, if the content that is passed in to the function contains the word "confidential", the function returns true . Otherwise, it returns false .

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

foreach statement

The foreachstatement lets script authors handle collections that ordinarily occur while processing SIP messages, such as contact header and endpoint collections. A foreachloop is invoked by using the following syntax:

foreach( elementin expression ) statement

For example:

  Copy codeCopy code
foreach (dbEndpoint in QueryEndpoints("someone@example.com")) { ...

The expression evaluates to a collection. Strings and other unary types are treated as single-item collections. 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 foreachloop, the continuestatement is used to jump to the next iteration of the loop, ignoring any processing statements subsequent to the continuestatement before the end of the loop.

while statement

With the whilestatement, you can iterate the occurrences of certain patterns or states predicated on the specified Boolean statement. A whileloop includes the following syntax.

  Copy codeCopy code
while (booleanExpression) { …;}
Note Note

A single whileloop cannot exceed 500 iterations.

break statement

The breakstatement allows for the early termination of a switch/case branch or a foreachloop. The syntax is the same as in C#.

A breakstatement must be present at the end of each casebranch in a switchstatement. "Fall-through" caused by case branches without a terminating breakstatement is not allowed.

null keyword

Script applications can use the null keyword to differentiate between an empty string ("") and values that are not found. Applications written for Live Communications Server 2003 return the empty string. Passing null to any function that expects a string parameter generates a script error and causes the script to be terminated. The following functions return null to indicate a value not found or an error:

  • GetDisplayName

  • GetHostName

  • GetParameterValue

  • GetScheme

  • GetUri

  • GetUriParameter

  • GetUserName

  • GetUserAtHost

  • QueryHomeServer

In addition, Message.Stampand Message.StampPoolcan both return null.

Flat file access

MSPL supports the access of data in flat files by using the following array syntax, where placeholder values are shown in italic:

flatFileName[ index]. columnName

Placeholder value



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


Specifies a zero-based integer or key string. Key strings are valid only if the keyColumnNameattribute for the < file> element is specified. In this 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 together with no in-memory hash table generate a script error and cause script execution to be aborted.


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.

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

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

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 that contains two columns named "keyHostName" and "valueTargetName." By assigning the value "keyHostName" to the keyColumnNameattribute, the example indicates that the values that are contained in the "keyHostName" column serves as key string indexers for the in-memory hash table.

For more information about the content of the < file> element, see file element .

In the following example script, the GetHostNamefunction gets the host name piece of a URI. The MSPL expression on the right 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 that is created for "exampleFile", and assigns this value to "targetHost."

  Copy codeCopy code
targetHost =

See also