Partager via

MSPL Script Syntax

  • Article

MSPL Script Syntax

This topic describes the basic syntax of the Microsoft SIP Processing Language (MSPL). The first section summarizes both the supported and unsupported features of MSPL. The remaining sections describe specific syntactical constructs and outline their behavior.

Syntax Summary

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

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 "." (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

Unsupported Features

  • Explicit (declarative) data types

  • Type casting

  • Pointers

  • Arithmetic operations

  • Function composition

  • Iteration statements

  • Preprocessor statements

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

  • Declarations (other than basic function declarations, as detailed below)

    Note

    Although MSPL does not support explicit declaration, assignment expressions and foreach statements 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 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.

Functions

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:

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.

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 (elementinexpression) 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 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.

Flat File Access

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.

<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".

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