Share via

MSPL Script Syntax

  • Article

MSPL (Microsoft SIP Processing Language) supports the following elements:

  • 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 "." (example: Structure.Member)
  • The following logical operators: "!", "==", "!=", "<", "<=", ">", ">="
  • Compound expressions
  • Compound statements
  • The "=" assignment operator
  • if/else statements
  • switch/case statements
  • break, continue, and return statements
  • null keyword
  • true/false keywords
  • Expression statements
  • End-of-line and multiline comments

MSPL does not support the following features:

  • Explicit (declarative) data types
  • Type casting
  • Pointers
  • Declarations (other than basic function declarations, as detailed below)
  • Arithmetic operations
  • Iteration statements
  • Preprocessor statements
  • Attributes
  • Static or global variables (state is not maintained across script invocations)

While there is no support for declarations, the assignment expression and the foreach statement both implicitly declare a variable and set its value. Variables "declared" in this fashion are global to the function or application body they are defined in. Code inside a function cannot reference these variables when they are defined in another function or the application body.

The following sections detail specific syntactical constructs used in writing an MSPL script, outlining their behavior.

String Literals

Literal string values can be escaped with either the backslash (\) or, in the case of double quotes, a pair of double quotes (""""). For example, the string literal "literal" (with double quotes) can be represented within quotes as either "\"literal\"" or ""literal"".

Unicode literals must be represented using the \u character sequence followed by the specific 4-digit code. For example, the Cyrillic capital "psi" character is represented as \u0470.

There is no support for prefixing a string literal with the "@" (at) symbol to disable escaping.

Function Invocation

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

function identifier (optional_parameter_list) statement

For example:

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. To prevent inadvertent looping, recursive (self-referencing) function calls are not allowed. Mutually recursive calls—calls made by a function to another function that called it previously—are also not allowed. For example, if Function 1 calls Function 2, which then calls Function 3, Function 3 cannot call either Function 1 or 2.

Return value types are implicitly defined; that is, the type is determined by the value passed to the return statement. Parameter types are also implicitly defined.

Changes made to values passed as parameters to a function are not preserved after the function completes execution. Functions cannot return collections; the only supported implicit return types are strings, bools, integers, and floats.

Below is an example function to filter a specific word in a string and return true if the word is found or false if it is not.

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

The foreach Statement

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 (element in expression) statement

For example:

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

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.

The null Keyword

Adding the null keyword enables script applications to distinguish between an empty string ("") and values that are not found. Applications written for Live Communication 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
  • GetXMLAttr
  • QueryHomeServer

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

Flat File Access

MSPL includes support for the array [] type for reading data from flat files. The syntax is

flatFileName[index].columnName

where

flatFileName

Specifies the value of the name attribute on one of the <file> nodes in the application manifest.

index

Is a zero-based integer or key string. Key string is only valid if the keyColumnName attribute is specified on the corresponding <file> node, 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 execution of the script to be aborted.

columnName

Specifies a name that matches one of the name attributes on one of the <column> nodes under the corresponding <file> node.

Example

<file name="flatFile"
    path=".\hostname.csv" keyColumnName="HostName" static="true"
    delimitedBy="comma"> 
    <column name="HostName"/> 
    <column name="TargetHost"/> 
</file>

In a script, the following uses the host name portion of a URI to extract the targetHost string from the specified location in a flat file:

targetHost = flatFile[GetHostName( sipRequest.RequestUri)].TargetHost;