WSTP 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;
}
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 |
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 |
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 |
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(). |
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 |
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 |
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 |
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 |
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 |
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 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 |
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 |
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 |
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 |
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 Function | New Function | |
WSDisownUnicodeString()
| ||
WSDisownUnicodeSymbol()
| ||
WSDisownBinaryNumberArray()
|
WSReleaseBinaryNumberArray()
| |
WSDisownBinaryNumberList()
|
WSReleaseBinaryNumberList()
| |
WSDisownByteArray()
|
WSReleaseByteArray()
| |
WSDisownByteString()
|
WSReleaseByteString()
| |
WSDisownByteSymbol()
|
WSReleaseByteSymbol()
| |
WSDisownDomainNameList()
| ||
WSDisownDoubleArray()
|
WSReleaseDoubleArray()
| |
WSDisownFloatArray()
|
WSReleaseFloatArray()
| |
WSDisownIntegerArray()
|
WSReleaseIntegerArray()
| |
WSDisownIntegerList()
|
WSReleaseIntegerList()
| |
WSDisownLongDoubleArray()
|
WSReleaseLongDoubleArray()
| |
WSDisownLongIntegerArray()
|
WSReleaseLongIntegerArray()
| |
WSDisownNetworkAddressList()
| ||
WSDisownRealArray()
|
WSReleaseRealArray()
| |
WSDisownRealList()
|
WSReleaeRealList()
| |
WSDisownShortIntegerArray()
|
WSReleaseShortIntegerArray()
| |
WSDisownString()
| ||
WSDisownSymbol()
|
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 Function | New Function Name | |
WSCreateMessageHandler0()
|
WSCreateMessageHandler()
| |
WSDoNotHandleSignalParameter0()
| ||
WSFilterArgv0()
|
WSFilterArgv()
| |
WSGetArrayType0()
|
WSGetArrayTypeWithDepthAndLeafType()
| |
WSGetBinaryNumberArray0()
|
WSGetBinaryNumberArrayWithLeafType()
| |
WSGetBinaryNumberArrayData0()
|
WSGetBinaryNumberArrayDataWithHeads()
| |
WSGetString0()
| ||
WSGetByteString0()
|
WSGetNumberAsByteString()
| |
WSHandleSignal0()
| ||
WSNextCharacter0()
|
WSNextCharacterFromStringWithLength()
| |
WSNumberControl0()
|
WSNumericsQuery()
| |
WSPutArrayLeaves0()
|
WSPutArrayLeaves()
| |
WSPutArrayType0()
|
WSPutArrayType()
| |
WSPutRealByteString0()
|
WSPutRealNumberAsByteString()
| |
WSReleaseGetArrayState0()
|
WSReleaseGetArrayState()
| |
WSReleasePutArrayState0()
|
WSReleasePutArrayState()
| |
WSValid0()
|
WSValid()
| |
WSGetLinkedEnvIDString0()
| ||
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.
Unicode and 16Bit Functions
In the Interface 4 WSTP library, all function names that contain Unicode or 16Bit have been removed.
Removed API Function | New Function or Equivalent Function | |
WSConvertUnicodeString()
|
WSConvertUCS2String()
| |
WSConvertUnicodeStringNL()
|
WSConvertUCS2StringNL()
| |
WSDisownUnicodeString()
| ||
WSDisownUnicodeSymbol()
| ||
WSGet16BitCharacters()
|
WSGetUCS2Characters()
| |
WSGetUnicodeString()
| ||
WSGetUnicodeString0()
| ||
WSGetUnicodeSymbol()
| ||
WSOldConvertUnicodeString()
|
WSOldConvertUCS2String()
| |
WSPut16BitCharacters()
|
WSPutUCS2Characters()
| |
WSPutRealUnicodeString0()
| ||
WSPutUnicodeString()
| ||
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() |
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.
WSTP API Changes for const
WSPutByteArray() | |
WSPutShortIntegerArray() | |
WSPutIntegerArray() | |
WSPutLongIntegerArray() | |
WSPutInteger8Array() | |
WSPutInteger16Array() | |
WSPutInteger32Array() | |
WSPutInteger64Array() | |
WSPutFloatArray() | |
WSPutDoubleArray() | |
WSPutReal32Array() | |
WSPutReal64Array() | |
WSPutReal128Array() | |
WSPutIntegerList() | |
WSPutRealList() | |
WSPutInteger8List() | |
WSPutInteger16List() | |
WSPutInteger32List() | |
WSPutInteger64List() | |
WSPutReal32List() | |
WSPutReal64List() | |
WSPutReal128List() |
New WSTP Library Names
Microsoft Windows
- The .mlp link protocol dynamic library files have been removed and the corresponding functionality merged into the main WSTP dlls.
- The WSTP dlls are no longer installed in the Windows System32 (SysWOW64) directory. Instead these libraries are contained in the Wolfram System layout.
Linux
- The WSTP SDK now contains new versions of the library named libWSTP32i4.a, libWSTP32i4.so, libWSTP64i4.a, and libWSTP64i4.so.
- For the first time on Linux, the WSTP Developer Kit now contains two interface revisions. The Developer Kit contains the new Interface 4 libraries as well as the old Interface 3 libraries. The WSTP header file wstp.h can be used with either version of the library. To use wstp.h with the Interface 3 version of the library, be sure to define the C preprocessor macro value WSINTERFACE to 3.
Mac OS X
- For the first time, the WSTP Developer Kit for OS X now contains two interface revisions. The Developer Kit contains the new Interface 4 as well as the old Interface 3 libraries. The WSTP header file wstp.h can be used with either version of the library. To use wstp.h with the Interface 3 version of the library, be sure to define the C preprocessor macro value WSINTERFACE to 3.
- The WSTP framework (wstp.framework) contains both Interface 4 and Interface 3 versions of the WSTP library framework. You can use the new framework with both new programs linked with Interface 4 and with old programs linked with Interface 3. New programs that link with the new framework will automatically use Interface 4.
mprep
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 Function | New API Function | |
WSCheckString()
| ||
WSCheckSymbol()
| ||
WSCreate0()
|
WSCreateLinkWithExternalProtocol()
| |
WSDisownBinaryNumberArray()
|
WSReleaseBinaryNumberArray()
| |
WSDisownBinaryNumberList()
|
WSReleaseBinaryNumberList()
| |
WSDisownByteArray()
|
WSReleaseByteArray()
| |
WSDisownByteString()
|
WSReleaseByteString()
| |
WSDisownByteSymbol()
|
WSReleaseByteSymbol()
| |
WSDisownDomainNameList()
| ||
WSDisownDoubleArray()
|
WSReleaseDoubleArray()
| |
WSDisownFloatArray()
|
WSReleaseFloatArray()
| |
WSDisownIntegerArray()
|
WSReleaseIntegerArray()
| |
WSDisownLongDoubleArray()
|
WSReleaseLongDoubleArray()
| |
WSDisownLongIntegerArray()
|
WSReleaseLongIntegerArray()
| |
WSDisownNetworkAddressList()
| ||
WSDisownRealArray()
|
WSReleaseRealArray()
| |
WSDisownRealList()
|
WSReleaseRealList()
| |
WSDisownShortIntegerArray()
|
WSReleaseShortIntegerArray()
| |
WSDisownString()
| ||
WSDisownSymbol()
|
WSReleseSymbol()
| |
WSDoNotHandleSignalParameter0()
| ||
WSFilterArgv0()
|
WSFilterArgv()
| |
WSGetArrayType0()
|
WSGetArrayTypeWithDepthAndLeafType()
| |
WSGetBinaryNumberArray0()
|
WSGetBinaryNumberArrayWithLeafType()
| |
WSGetBinaryNumberArrayData0()
|
WSGetBinaryNumberArrayDataWithHeads()
| |
WSGetString0
| ||
WSGetByteString0()
|
WSGetNumberAsByteString()
| |
WSGetUCS2String0()
| ||
WSGetUTF16String0()
| ||
WSGetUTF32String0()
| ||
WSGetUTF8String0()
| ||
WSHandleSignal0()
| ||
WSNextCharacter0()
|
WSNextCharacterFromStringWithLength()
| |
WSNumberControl0()
|
WSNumericsQuery()
| |
WSPutArrayLeaves0()
|
WSPutArrayLeaves()
| |
WSPutArrayType0()
|
WSPutArrayType()
| |
WSPutBinaryNumberArrayData()
|
WSPutBinaryNumberArrayDataWithHeads()
| |
WSPutRealByteString0()
|
WSPutRealNumberAsByteString()
| |
WSPutRealUCS2String0()
| ||
WSPutRealUTF16String0()
| ||
WSPutRealUTF32String0()
| ||
WSPutRealUTF8String0()
| ||
WSReleaseGetArrayState0()
|
WSReleaseGetArrayState()
| |
WSReleasePutArrayState0()
|
WSReleasePutArrayState()
| |
WSValid0()
|
WSValid()
|
New API Functions
WSCompilerID()
| ||
WSReleaseCompilerID()
| ||
WSReleaseUCS2CompilerID()
| ||
WSReleaseUTF16CompilerID()
|
WSReleaseUTF32CompilerID()
| |
WSReleaseUTF32CompilerID()
|
WSReleaseUTF8CompilerID()
| |
WSUCS2CompilerID()
|
WSUTF16CompilerID()
| |
WSUTF32CompilerID()
|
WSUTF8CompilerID()
| |
WSGetInteger8ArrayData()
| ||
WSLowLevelDeviceName()
| ||
WSPutInteger8ArrayData()
| ||
WSRleeaseLowLevelDeviceName()
| ||