WSTP Interface 4

Changes in WSTP for Interface 4

New Link Protocol

Interface 4 introduces a new link protocol called "IntraProcess". IntraProcess is designed for fast, full-duplex connections between threads in the same process.

#include "wstp.h"

int main()
{
    WSENV env;
    WSLINK link;
    int error;

    env = WSInitialize((WSEnvironmentParameter)0);
    if(env == (WSENV)0)
    { /* Unable to initialize WSTP environment */ }

    link = WSOpenString(env, "-linkcreate -linkprotocol IntraProcess", &error);
    if(link == (WSLINK)0 || error != WSEOK)
    { /* Unable to create link object */ }

    /* ... */

    WSClose(link);
    WSDeinitialize(env);
    return 0;
}

Example code that creates a listening IntraProcess link.

Thread-Safe Links

Interface 4 introduces new API functions and internal functionality that enable thread safety for link objects. In previous versions of the Wolfram Symbolic Transfer Protocol (WSTP), you could only access a link object via the WSTP API functions safely from one thread at a time. Now, the library implements mechanisms that provide thread safety for link objects at the API level, making it safe to call WSTP API functions on the same link object simultaneously from multiple threads.

WSEnableLinkLock()activate thread safety mechanism for a link object
WSDisableLinkLock()disable thread safety for a link object

Thread safety API functions.

Introduces Logging

The Interface 4 WSTP library introduces the ability to log the expressions passing through a WSTP stream to a file in the file system.

WSLogStreamToFile()activate logging for a message and log the expression stream to a named file
WSStopLoggingStreamToFile()stop logging to the named file for the given link
WSStopLoggingStream()turn off the logging mechanism for a given link
WSDisableLoggingStream()temporarily disable logging for a given link
WSEnableLoggingStream()re-enable logging for a given link

Logging API functions.

Service Discovery and Advertisement

The Interface 4 WSTP library introduces new API functions designed to provide service discovery and advertisement operations for services that use the WSTP protocol for communication.

WSBrowseForLinkServices()initiate a network browse operation for discovering link services
WSStopBrowsingForLinkServices()stop browsing a network for available link services
WSResolveLinkService()initiate a resolve operation for a named link service
WSStopResolvingLinkService()stop resolving the connection details for a named link service
WSRegisterLinkServiceWithPortAndHostname()advertise a named link service on the machine at port and hostname
WSRegisterLinkServiceWithHostname()advertise a named link service on the machine with hostname
WSRegisterLinkService()advertise a named link service on the machine and let WSTP choose the port and hostname
WSStopRegisteringLinkService()stop advertising a named link service

Service Discovery API functions.

Link Server

The Interface 4 WSTP library introduces new API functions designed to provide client/server style one-to-many connections. This link server functionality allows a program to make a WSTP TCPIP link protocol connection available and have many clients connect to the same WSTP TCPIP endpoint.

WSNewLinkServer()create a new link server object, letting the WSTP library choose the TCPIP port and and interface.
WSNewLinkServerWithPort()create a new link server object on a named port, letting the WSTP library choose the TCPIP interface.
WSNewLinkServerWithPortAndInterface()create a new link server object on a named port and interface.
WSShutdownLinkServer()close down the link server connection.
WSRegisterCallbackFunctionWithLinkServer()register a callback function for the link server to call when a new client connects to the link server endpoint.
WSWaitForNewLinkFromLinkServer()synchronously wait for a client to connect to the link server endpoint.
WSPortFromLinkServer()get the port number used by the link server endpoint.
WSInterfaceFromLinkServer()get the interface used by the link server endpoint.
WSContextFromLinkServer()retrieve the context registered with the link server object at creation.
WSReleaseInterfaceFromLinkServer()release the memory allocated by the WSTP library in the call to WSInterfaceFromLinkServer().

Link server API functions.

Full Unicode Support for Common API Functions

The Interface 4 WSTP library introduces new API functions designed for use with Unicode encoding forms for functions previously only available with ASCII versions.

WSPutFunction()

WSPutUCS2Function()send a UCS-2 encoded function and its arguments
WSPutUTF16Function()send a UTF-16 encoded function and its arguments
WSPutUTF32Function()send a UTF-32 encoded function and its arguments
WSPutUTF8Function()send a UTF-8 encoded function and its arguments

New WSPutFunction() API functions.

WSGetFunction()

WSGetUCS2Function()get a UCS-2 encoded function and its arguments
WSGetUTF16Function()get a UTF-16 encoded function and its arguments
WSGetUTF32Function()get a UTF-32 encoded function and its arguments
WSGetUTF8Function()get a UTF-8 encoded function and its arguments

New WSGetFunction() API functions.

WSErrorMessage()

WSUCS2ErrorMessage()return an error message for a link encoded in a UCS-2 string
WSUTF16ErrorMessage()return an error message for a link encoded in a UTF-16 string
WSUTF32ErrorMessage()return an error message for a link encoded in a UTF-32 string
WSUTF8ErrorMessage()return an error message for a link encoded in a UTF-8 string

New WSErrorMessage() API functions.

WSLinkName()

WSUCS2LinkName()return the link name encoded in a UCS-2 string
WSUTF16LinkName()return the link name encoded in a UTF-16 string
WSUTF32LinkName()return the link name encoded in a UTF-32 string
WSUTF8LinkName()return the link name encoded in a UTF-8 string

New WSLinkName() API functions.

WSTestHead()

WSTestUCS2Head()test the expression on the link for a function head encoded as a UCS-2 string
WSTestUTF16Head()test the expression on the link for a function head encoded as a UTF-16 string
WSTestUTF32Head()test the expression on the link for a function head encoded as a UTF-32 string
WSTestUTF8Head()test the expression on the link for a function head encoded as a UTF-8 string

New WSTestHead() API functions.

WSTestHeadWithArgCount()

WSTestHeadWithArgCount()test the expression on the link for a function head encoded as an ASCII string and a given number of arguments
WSTestUCS2HeadWithArgCount()test the expression on the link for a function head encoded as a UCS-2 string and a given number of arguments
WSTestUTF16HeadWithArgCount()test the expression on the link for a function head encoded as a UTF-16 string and a given number of arguments
WSTestUTF32HeadWithArgCount()test the expression on the link for a function head encoded as a UTF-32 string and a given number of arguments
WSTestUTF8HeadWithArgCount()test the expression on the link for a function head encoded as a UTF-8 string and a given number of arguments

New WSTestHeadWithArgCount() API functions.

New String Test API Functions

WSTestString()test the expression on the link for a string value encoded as an ASCII string
WSTestUCS2String()test the expression on the link for a string value encoded as a UCS-2 string
WSTestUTF16String()test the expression on the link for a string value encoded as a UTF-16 string
WSTestUTF32String()test the expression on the link for a string value encoded as a UTF-32 string
WSTestUTF8String()test the expression on the link for a string value encoded as a UTF-8 string

String test API functions.

New Symbol Test API Functions

WSTestSymbol()test the expression on the link for a symbol value encoded as an ASCII string
WSTestUCS2Symbol()test the expression on the link for a symbol value encoded as a UCS-2 string
WSTestUTF16Symbol()test the expression on the link for a symbol value encoded as a UTF-16 string
WSTestUTF32Symbol()test the expression on the link for a symbol value encoded as a UTF-32 string
WSTestUTF8Symbol()test the expression on the link for a symbol value encoded as a UTF-8 string

Symbol test API functions.

Getting a Number as a String

WSGetNumberAsString()read a number from the link as an ASCII string
WSGetNumberAsUCS2String()read a number from the link as a UCS-2 string
WSGetNumberAsUTF16String()read a number from the link as a UTF-16 string
WSGetNumberAsUTF32String()read a number from the link as a UTF-32 string
WSGetNumberAsUTF8String()read a number from the link as a UTF-8 string

Get numbers as string API functions.

Putting a Real Number as a String

WSPutRealNumberAsString()send a floating-point number as an ASCII string
WSPutRealNumberAsUCS2String()send a floating-point number as a UCS-2 string
WSPutRealNumberAsUTF16String()send a floating-point number as a UTF-16 string
WSPutRealNumberAsUTF32String()send a floating-point number as a UTF-32 string
WSPutRealNumberAsUTF8String()send a floating-point number as a UTF-8 string

Send a real number as a string API function.

More Consistent WSTP API

Interface 3 introduced new patterns in the WSTP API function names. Interface 4 continues the conventions introduced in Interface 3 by removing obsolete function names, renaming old functions and old, inconsistent, or obscure names, and adding new API functions.

WSDisown Functions

WSDisown functions have been removed and/or renamed to an WSRelease equivalent. If you need to allow WSTP to free a resource that is allocated in an WSGet function, use the corresponding WSRelease API function call to release the resource.

Removed/Renamed FunctionNew Function
WSDisownUnicodeString()WSReleaseUCS2String()
WSDisownUnicodeSymbol()WSReleaseUCS2Symbol()
WSDisownBinaryNumberArray()WSReleaseBinaryNumberArray()
WSDisownBinaryNumberList()WSReleaseBinaryNumberList()
WSDisownByteArray()WSReleaseByteArray()
WSDisownByteString()WSReleaseByteString()
WSDisownByteSymbol()WSReleaseByteSymbol()
WSDisownDomainNameList()WSReleaseDomainNameList()
WSDisownDoubleArray()WSReleaseDoubleArray()
WSDisownFloatArray()WSReleaseFloatArray()
WSDisownIntegerArray()WSReleaseIntegerArray()
WSDisownIntegerList()WSReleaseIntegerList()
WSDisownLongDoubleArray()WSReleaseLongDoubleArray()
WSDisownLongIntegerArray()WSReleaseLongIntegerArray()
WSDisownNetworkAddressList()WSReleaseNetworkAddressList()
WSDisownRealArray()WSReleaseRealArray()
WSDisownRealList()WSReleaeRealList()
WSDisownShortIntegerArray()WSReleaseShortIntegerArray()
WSDisownString()WSReleaseString()
WSDisownSymbol()WSReleaseSymbol()

API Functions Ending in 0

In the Interface 4 WSTP library, all functions ending in 0 have been removed. For those functions that provided a useful service, Interface 4 provides new function names.

Removed API FunctionNew Function Name
WSCreateMessageHandler0()WSCreateMessageHandler()
WSDoNotHandleSignalParameter0()WSDoNotHandleSignalParameter()
WSFilterArgv0()WSFilterArgv()
WSGetArrayType0()WSGetArrayTypeWithDepthAndLeafType()
WSGetBinaryNumberArray0()WSGetBinaryNumberArrayWithLeafType()
WSGetBinaryNumberArrayData0()WSGetBinaryNumberArrayDataWithHeads()
WSGetString0()WSGetNumberAsString()
WSGetByteString0()WSGetNumberAsByteString()
WSHandleSignal0()WSHandleSignal()
WSNextCharacter0()WSNextCharacterFromStringWithLength()
WSNumberControl0()WSNumericsQuery()
WSPutArrayLeaves0()WSPutArrayLeaves()
WSPutArrayType0()WSPutArrayType()
WSPutRealByteString0()WSPutRealNumberAsByteString()
WSReleaseGetArrayState0()WSReleaseGetArrayState()
WSReleasePutArrayState0()WSReleasePutArrayState()
WSValid0()WSValid()
WSGetLinkedEnvIDString0()WSGetLinkedEnvIDString()
WSSetEnvIDString0()WSSetEnvIDString()

WSCheck Functions

In the Interface 4 WSTP library, the WSCheck family of functions has been deprecated in favor of the corresponding WSTest counterparts.

WSCheckFunction()WSTestHead()
WSCheckFunctionWithArgCount()WSTestHeadWithArgCount()

Unicode and 16Bit Functions

In the Interface 4 WSTP library, all function names that contain Unicode or 16Bit have been removed.

Removed API FunctionNew Function or Equivalent Function
WSConvertUnicodeString()WSConvertUCS2String()
WSConvertUnicodeStringNL()WSConvertUCS2StringNL()
WSDisownUnicodeString()WSReleaseUCS2String()
WSDisownUnicodeSymbol()WSReleaseUCS2Symbol()
WSGet16BitCharacters()WSGetUCS2Characters()
WSGetUnicodeString()WSGetUCS2String()
WSGetUnicodeString0()WSGetNumberAsUCS2String()
WSGetUnicodeSymbol()WSGetUCS2Symbol()
WSOldConvertUnicodeString()WSOldConvertUCS2String()
WSPut16BitCharacters()WSPutUCS2Characters()
WSPutRealUnicodeString0()WSPutRealNumberAsUCS2String()
WSPutUnicodeString()WSPutUCS2String()
WSPutUnicodeSymbol()WSPutUnicodeSymbol()

Integer8 Functions

Interface 3 introduced new forms for the WSPutInteger and WSGetInteger family of functions, namely WSPutInteger16(), WSPutInteger32(), and WSGetInteger16(), WSGetInteger32(), . The Interface 4 library adds support for 8-bit integers.

WSPutInteger8()send an 8-bit integer
WSPutInteger8List()send a list of 8-bit integers
WSPutInteger8Array()send a multidimensional array of 8-bit integers
WSGetInteger8()read an 8-bit integer
WSGetInteger8List()read a list of 8-bit integers
WSGetInteger8Array()read a multidimensional array of 8-bit integers
WSReleaseInteger8List()release memory allocated by WSGetInteger8List()
WSReleaseInteger8Array()release memory allocated by WSGetInteger8Array()

New WSGetInteger8 functions.

WSTP API Behavior Changes

WSEnvironmentParameter

The API functions that create, modify, and use a WSENV parameters object have changed in Interface 4. In Interface 3, these functions operated on an object of type WSParameters. In Interface 4, WSParameters has been replaced by the WSEnvironmentParameter object.

WSNewParameters() API Function

WSNewParameters() now returns a WSEnvironmentParameter object that must be released by a call to WSReleaseParameters().

WSErrorMessage() API Function

The WSErrorMessage() function now returns a message string that must be released with WSReleaseErrorMessage(). In addition, the new WSErrorMessage() style functions with Unicode support also have a corresponding WSReleaseErrorMessage() function.

WSLinkName() API Function

The WSLinkName() function now returns a name string that must be released with WSReleaseLinkName(). In addition, the new WSLinkName() style functions with Unicode support also have corresponding WSReleaseLinkName() style functions.

WSGetLinkedEnvIDString0() API Function

Interface 4 no longer has the function WSGetLinkedEnvIDString0(). It has been replaced with WSGetLinkedEnvIDString(), and the new function has a slightly different interface than the old function.

UTF-16 and UTF-32 API Functions and Byte Order Marks

The Unicode functions that implement support for the UTF-16 and UTF-32 Unicode encoding forms now require strings and symbols to start with a byte order mark for putting and will return a string or symbol with a byte order mark on getting.

mlint64 64-Bit Type

On 32-bit platforms, the wstpint64 type is no longer a struct, but is now a native 64-bit integer type on all supported platforms.

Microsoft Windows__int64
Mac OS Xlong long
Linuxlong long

WSTP API Changes for const

The following WSTP API functions now take pointer arguments that are const type:

New WSTP Library Names

Microsoft Windows

Linux

Mac OS X

mprep

mprep now produces code suitable for use with the Interface 4 WSTP API.

WSTP API Changes

Removed API Functions

WSConvertUnicodeString()WSConvertUnicodeStringNL()
WSCreateMessageHandler0()WSCreateYieldFunction0()
WSDestroy()WSDisownUnicodeString()
WSDisownUnicodeSymbol()WSDoNotHandleSignalParameter0
WSGet16BitCharacters()WSGetLinkedEnvIDString0()
WSGetUnicodeString()WSGetUnicodeString0()
WSGetUnicodeSymbol()WSLinkSelect()
WSLoopbackOpen0()WSMake()
WSOldConvertUnicodeString()WSOpenS()
WSPut16BitCharacters()WSPutRealUnicodeString0()
WSPutUnicodeString()WSPutUnicodeSymbol()
WSSetEnvIDString0()WSSetMessageHandler0()
WSSetYieldFunction0()WSTestPoint1()
WSTestPoint2()WSTestPoint3()
WSTestPoint4()WSTransfer()
WSUnsetSignalHandler0()WSVersionNumbers0()

Renamed API Functions

Old API FunctionNew API Function
WSCheckString()WSTestString()
WSCheckSymbol()WSTestSymbol()
WSCreate0()WSCreateLinkWithExternalProtocol()
WSDisownBinaryNumberArray()WSReleaseBinaryNumberArray()
WSDisownBinaryNumberList()WSReleaseBinaryNumberList()
WSDisownByteArray()WSReleaseByteArray()
WSDisownByteString()WSReleaseByteString()
WSDisownByteSymbol()WSReleaseByteSymbol()
WSDisownDomainNameList()WSReleaseDomainNameList()
WSDisownDoubleArray()WSReleaseDoubleArray()
WSDisownFloatArray()WSReleaseFloatArray()
WSDisownIntegerArray()WSReleaseIntegerArray()
WSDisownLongDoubleArray()WSReleaseLongDoubleArray()
WSDisownLongIntegerArray()WSReleaseLongIntegerArray()
WSDisownNetworkAddressList()WSReleaseNetworkAddressList()
WSDisownRealArray()WSReleaseRealArray()
WSDisownRealList()WSReleaseRealList()
WSDisownShortIntegerArray()WSReleaseShortIntegerArray()
WSDisownString()WSReleaseString()
WSDisownSymbol()WSReleseSymbol()
WSDoNotHandleSignalParameter0()WSDoNotHandleSignalParameter()
WSFilterArgv0()WSFilterArgv()
WSGetArrayType0()WSGetArrayTypeWithDepthAndLeafType()
WSGetBinaryNumberArray0()WSGetBinaryNumberArrayWithLeafType()
WSGetBinaryNumberArrayData0()WSGetBinaryNumberArrayDataWithHeads()
WSGetString0WSGetNumberAsString()
WSGetByteString0()WSGetNumberAsByteString()
WSGetUCS2String0()WSGetNumberAsUCS2String()
WSGetUTF16String0()WSGetNumberAsUTF16String()
WSGetUTF32String0()WSGetNumberAsUTF32String()
WSGetUTF8String0()WSGetNumberAsUTF8String()
WSHandleSignal0()WSHandleSignal()
WSNextCharacter0()WSNextCharacterFromStringWithLength()
WSNumberControl0()WSNumericsQuery()
WSPutArrayLeaves0()WSPutArrayLeaves()
WSPutArrayType0()WSPutArrayType()
WSPutBinaryNumberArrayData()WSPutBinaryNumberArrayDataWithHeads()
WSPutRealByteString0()WSPutRealNumberAsByteString()
WSPutRealUCS2String0()WSPutRealNumberAsUCS2String()
WSPutRealUTF16String0()WSPutRealNumberAsUTF16String()
WSPutRealUTF32String0()WSPutRealNumberAsUTF32String()
WSPutRealUTF8String0()WSPutRealNumberAsUTF8String()
WSReleaseGetArrayState0()WSReleaseGetArrayState()
WSReleasePutArrayState0()WSReleasePutArrayState()
WSValid0()WSValid()

New API Functions

WSCompilerID()WSGetAvailableLinkProtocolNames()
WSGetLinksFromEnvironment()WSReleaseCompilerID()
WSReleaseLinkProtocolNames()WSReleaseLinksFromEnvironment()
WSReleaseParameters()WSReleaseUCS2CompilerID()
WSReleaseUTF16CompilerID()WSReleaseUTF32CompilerID()
WSReleaseUTF32CompilerID()WSReleaseUTF8CompilerID()
WSUCS2CompilerID()WSUTF16CompilerID()
WSUTF32CompilerID()WSUTF8CompilerID()
WSDisableLinkLock()WSDisableLoggingStream()
WSEnableLinkLock()WSEnableLoggingStream()
WSGetInteger8()WSGetInteger8Array()
WSGetInteger8ArrayData()WSGetInteger8List()
WSGetUCS2Function()WSGetUTF16Function()
WSGetUTF32Function()WSGetUTF8Function()
WSIsLinkLoopback()WSLinkEnvironment()
WSLogFileNameForLink()WSLogStreamToFile()
WSLowLevelDeviceName()WSPutInteger8()
WSPutInteger8Array()WSPutInteger8ArrayData()
WSPutInteger8List()WSPutUCS2Function()
WSPutUTF16Function()WSPutUTF32Function()
WSPutUTF8Function()WSReleaseErrorMessage()
WSReleaseInteger8Array()WSReleaseInteger8List()
WSReleaseLinkName()WSReleaseLogFileNameForLink()
WSRleeaseLowLevelDeviceName()WSReleaseUCS2ErrorMessage()
WSReleaseUCS2LinkName()WSReleaseUTF16ErrorMessage()
WSReleaseUTF16LinkName()WSReleaseUTF32ErrorMessage()
WSReleaseUTF32LinkName()WSReleaseUTF8ErrorMessage()
WSReleaseUTF8LinkName()WSSetThreadSafeLinksParameter()
WSStopLoggingStream()WSStopLoggingStreamToFile()
WSTestUCS2Head()WSTestUCS2String()
WSTestUCS2Symbol()WSTestUTF16Head()
WSTestUTF16String()WSTestUTF16Symbol()
WSTestUTF32Head()WSTestUTF32String()
WSTestUTF32Symbol()WSTestUTF8Head()
WSTestUTF8String()WSTestUTF8Symbol()
WSUCS2ErrorMessage()WSUCS2LinkName()
WSUTF16ErrorMessage()WSUTF16LinkName()
WSUTF32ErrorMessage()WSUTF16LinkName()
WSUTF8ErrorMessage()WSUTF8LinkName()
WSWaitForLinkActivity()WSWaitForLinkActivityWithCallback()
WSTestHeadWithArgCount()WSTestUCS2HeadWithArgCount()
WSTestUTF16HeadWithArgCount()WSTestUTF32HeadWithArgCount()
WSTestUTF8HeadWithArgCount()