WSTP 接口4

WSTP 在接口4中的改变

新的链接协议

接口4引入新的链接协议,称为IntraProcess. IntraProcess 是为同样进程中的线程间的快速、全双工连接而设计的.
#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;
}
创建一个监听 IntraProcess 链接的范例代码.

线程安全链接

接口4引入新的 API 函数和为链接对象启用线程安全的内部功能. 在 Wolfram Symbolic Transfer Protocol (WSTP) 的先前版本,你只可以一次一个线程,通过 WSTP API 函数访问链接对象. 现在的程序库实现机制使得在 API 级即可为链接对象提供线程安全,使之可以在同一个链接对象中从多个线程同时安全调用 WSTP API 函数.
WSEnableLinkLock()
激活链接对象的线程安全机制
WSDisableLinkLock()
对链接对象禁用线程安全
线程安全 API 函数.

引入日志

接口4 WSTP 程序库引入了记录从 WSTP 流传递给文件系统中的文件的表达式的能力.
WSLogStreamToFile()
激活信息日志,并把表达式流记录在已命名的文件中
WSStopLoggingStreamToFile()
对给定链接停止记录到已命名的文件中
WSStopLoggingStream()
对给定链接关闭日志机制
WSDisableLoggingStream()
对给定链接临时禁用日志
WSEnableLoggingStream()
对给定连接重新启用日志
日志 API 函数.

服务发现和通告

接口4 WSTP 程序库引入了新的 API 函数,是为提供服务发现和使用 WSTP 协议进行通信服务的通告操作而设计.
WSBrowseForLinkServices()
为发现链接服务初始化网络浏览操作
WSStopBrowsingForLinkServices()
对可用链接服务停止浏览网络
WSResolveLinkService()
为已命名的链接服务初始化分析操作
WSStopResolvingLinkService()
为已命名的链接服务停止分析连接详情
WSRegisterLinkServiceWithPortAndHostname()
在带有端口和主机名的机器上通告已命名的链接服务
WSRegisterLinkServiceWithHostname()
在带有主机名的机器上通告已命名的链接服务
WSRegisterLinkService()
在机器上通告已命名的链接服务,并让 WSTP 选择端口和主机名
WSStopRegisteringLinkService()
停止通告已命名的链接服务
服务器发现 API 函数.

链接服务器

接口4 WSTP 程序库引入为提供客户/服务器风格的一对多连接而设计的新的 API 函数. 该链接服务器功能允许通过编程使得 WSTP TCPIP 链接协议的连接可用并且允许许多客户连接到同样的 WSTP TCPIP 端点.
WSNewLinkServer()
创建一个新的链接服务器对象,让 WSTP 程序库选择 TCPIP 端口和接口.
WSNewLinkServerWithPort()
在给定名称的端口上创建一个新的链接服务器对象,让 WSTP 程序库选择 TCPIP 接口.
WSNewLinkServerWithPortAndInterface()
在给定名称的端口和接口上创建一个新的链接服务器对象.
WSShutdownLinkServer()
关闭链接服务器连接.
WSRegisterCallbackFunctionWithLinkServer()
为链接服务器注册一个回叫函数,当一个新用户连接到链接服务器端点时会被调用.
WSWaitForNewLinkFromLinkServer()
同步等待用户连接到链接服务器端点.
WSPortFromLinkServer()
获取由链接服务器端点使用的端口号.
WSInterfaceFromLinkServer()
获取由链接服务器端点使用的接口.
WSContextFromLinkServer()
恢复在创建时用链接服务器对象注册的上下文.
WSReleaseInterfaceFromLinkServer()
释放在调用 WSInterfaceFromLinkServer() 时由 WSTP 程序库分配的内存.
链接服务器 API 函数.

对常用的 API 函数提供完全的 Unicode 支持

接口4 WSTP 程序库引入新的为先前只能用 ASCII 版本的函数,现在可以使用 Unicode 编码格式而设计的 API 函数.

WSPutFunction()

WSPutUCS2Function()
发送一个 UCS-2 编码函数和它的参量
WSPutUTF16Function()
发送一个 UTF-16 编码函数和它的参量
WSPutUTF32Function()
发送一个 UTF-32 编码函数和它的参量
WSPutUTF8Function()
发送一个 UTF-8 编码函数和它的参量
新的 WSPutFunction() API 函数.

WSGetFunction()

WSGetUCS2Function()
获取一个 UCS-2 编码函数和它的参量
WSGetUTF16Function()
获取一个 UTF-16 编码函数和它的参量
WSGetUTF32Function()
获取一个 UTF-32 编码函数和它的参量
WSGetUTF8Function()
获取一个 UTF-8 编码函数和它的参量
新的 WSGetFunction() API 函数.

WSErrorMessage()

WSUCS2ErrorMessage()
返回一个 UCS-2 字符串编码中的链接的错误信息
WSUTF16ErrorMessage()
返回一个 UTF-16 字符串编码中的链接的错误信息
WSUTF32ErrorMessage()
返回一个 UTF-32 字符串编码中的链接的错误信息
WSUTF8ErrorMessage()
返回一个 UTF-8 字符串编码中的链接的错误信息
新的 WSErrorMessage() API 函数.

WSLinkName()

WSUCS2LinkName()
返回在 UCS-2 字符串编码中的链接名称
WSUTF16LinkName()
返回在 UTF-16 字符串编码中的链接名称
WSUTF32LinkName()
返回在 UTF-32 字符串编码中的链接名称
WSUTF8LinkName()
返回在 UTF-8 字符串编码中的链接名称
新的 WSLinkName() API 函数.

WSTestHead()

WSTestUCS2Head()
为编码为一个 UCS-2 字符串的函数标头测试在链接上的表达式
WSTestUTF16Head()
为编码为一个 UTF-16 字符串的函数标头测试在链接上的表达式
WSTestUTF32Head()
为编码为一个 UTF-32 字符串的函数标头测试在链接上的表达式
WSTestUTF8Head()
为编码为一个 UTF-8 字符串的函数标头测试在链接上的表达式
新的 WSTestHead() API 函数.

WSTestHeadWithArgCount()

WSTestHeadWithArgCount()
为编码为一个 ASCII 字符串和一个给定参量数的函数标头测试在链接上的表达式
WSTestUCS2HeadWithArgCount()
为编码为一个 UCS-2 字符串和一个给定参量数的函数标头测试在链接上的表达式
WSTestUTF16HeadWithArgCount()
为编码为一个 UTF-16 字符串和一个给定参量数的函数标头测试在链接上的表达式
WSTestUTF32HeadWithArgCount()
为编码为一个 UTF-32 字符串和一个给定参量数的函数标头测试在链接上的表达式
WSTestUTF8HeadWithArgCount()
为编码为一个 UTF-8 字符串和一个给定参量数的函数标头测试在链接上的表达式
新的 WSTestHeadWithArgCount() API 函数.

新的字符串测试 API 函数

WSTestString()
为编码为一个 ASCII 字符串的字符串值测试在链接上的表达式
WSTestUCS2String()
为编码为一个 UCS-2 字符串的字符串值测试在链接上的表达式
WSTestUTF16String()
为编码为一个 UTF-16 字符串的字符串值测试在链接上的表达式
WSTestUTF32String()
为编码为一个 UTF-32 字符串的字符串值测试在链接上的表达式
WSTestUTF8String()
为编码为一个 UTF-8 字符串的字符串值测试在链接上的表达式
字符串测试 API 函数.

新的符号测试 API 函数

WSTestSymbol()
为编码为一个 ASCII 字符串的符号串值测试在链接上的表达式
WSTestUCS2Symbol()
为编码为一个 UCS-2 字符串的符号串值测试在链接上的表达式
WSTestUTF16Symbol()
为编码为一个 UTF-16 字符串的符号串值测试在链接上的表达式
WSTestUTF32Symbol()
为编码为一个 UTF-32 字符串的符号串值测试在链接上的表达式
WSTestUTF8Symbol()
为编码为一个 UTF-8 字符串的符号串值测试在链接上的表达式
符号测试 API 函数.

获取一个作为字符串的数字

WSGetNumberAsString()
从链接读取一个数字作为 ASCII 字符串
WSGetNumberAsUCS2String()
从链接读取一个数字作为 UCS-2 字符串
WSGetNumberAsUTF16String()
从链接读取一个数字作为 UTF-16 字符串
WSGetNumberAsUTF32String()
从链接读取一个数字作为 UTF-32 字符串
WSGetNumberAsUTF8String()
从链接读取一个数字作为 UTF-8 字符串
获取数字作为字符串 API 函数.

把实数作为一个字符串

WSPutRealNumberAsString()
发送一个作为 ASCII 字符串的浮点数
WSPutRealNumberAsUCS2String()
发送一个作为 UCS-2 字符串的浮点数
WSPutRealNumberAsUTF16String()
发送一个作为 UTF-16 字符串的浮点数
WSPutRealNumberAsUTF32String()
发送一个作为 UTF-32 字符串的浮点数
WSPutRealNumberAsUTF8String()
发送一个作为 UTF-8 字符串的浮点数
发送一个实数作为一个字符串 API 函数.

更一致的 WSTP API

接口3在 WSTP API 函数名称中引入了新的模式. 接口4继续接口3的传统,去除废弃的函数名称、重命名旧的函数以及旧的、不一致或模糊的名称,并添加新的 API 函数.

WSDisown 函数

WSDisown 函数已被去除/或重命名为 WSRelease. 如果你需要允许 WSTP 释放在 WSGet 函数中已分配的资源,调用对应的 WSRelease API 函数来释放资源.
已去除/重命名的函数
新函数
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()

以0结尾的 API 函数

在接口4 WSTP 程序库中,所有以0结尾的函数已被去除. 对于那些提供有用服务的函数,接口4提供新的函数名.
已去除的 API 函数
新的函数名
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 函数

在接口4 WSTP 程序库中,WSCheck 函数系列已被弃用以支持对应的 WSTest.
WSCheckFunction()
WSCheckFunctionWithArgCount()

Unicode 与 16Bit 函数

在接口4 WSTP 程序库中,所有包括 Unicode 或 16Bit 的函数名称已被去除.
已去除的 API 函数
新函数或等价函数
WSConvertUnicodeString()
WSConvertUCS2String()
WSConvertUnicodeStringNL()
WSConvertUCS2StringNL()
WSDisownUnicodeString()
WSDisownUnicodeSymbol()
WSGet16BitCharacters()
WSGetUCS2Characters()
WSGetUnicodeString()
WSGetUnicodeString0()
WSGetUnicodeSymbol()
WSOldConvertUnicodeString()
WSOldConvertUCS2String()
WSPut16BitCharacters()
WSPutUCS2Characters()
WSPutRealUnicodeString0()
WSPutUnicodeString()
WSPutUnicodeSymbol()
WSPutUnicodeSymbol()

Integer8 函数

接口3为 WSPutIntegerWSGetInteger 函数系列引入新的形式,它们是 WSPutInteger16()WSPutInteger32()... 和 WSGetInteger16()WSGetInteger32() .... 接口4程序库添加了对8位整数的支持.
WSPutInteger8()
发送一个8位整数
WSPutInteger8List()
发送一个8位整数列表
WSPutInteger8Array()
发送一个8位整数的多维数组
WSGetInteger8()
读取一个8位整数
WSGetInteger8List()
读取一个8位整数列表
WSGetInteger8Array()
读取一个8位整数的多维数组
WSReleaseInteger8List()
释放由 WSGetInteger8List()分配的内存
WSReleaseInteger8Array()
释放由 WSGetInteger8Array()分配的内存
新的 WSGetInteger8 函数.

WSTP API 行为改变

WSEnvironmentParameter

在接口4中创建、修改和使用 WSENV 参数对象的 API 函数已改变. 在接口3中,这些函数操作于 WSParameters 类型的对象上. 在藉口中,WSParameters 已被 WSEnvironmentParameter 对象取代.

WSNewParameters() API 函数

WSNewParameters() 现在返回一个 WSEnvironmentParameter 对象,它必须通过调用 WSReleaseParameters() 进行释放.

WSErrorMessage() API 函数

WSErrorMessage() 函数现在返回消息字符串,它必须由 WSReleaseErrorMessage() 释放. 另外,带有 Unicode 支持的新的 WSErrorMessage() 风格函数有对应的 WSReleaseErrorMessage() 函数.

WSLinkName() API 函数

WSLinkName() 函数现在返回的名称字符串,必须由 WSReleaseLinkName() 释放. 另外,带有 Unicode 支持的新的 WSLinkName() 风格函数有对应的 WSReleaseLinkName() 风格函数.

WSGetLinkedEnvIDString0() API 函数

接口4不再带有函数 WSGetLinkedEnvIDString0(). 它被 WSGetLinkedEnvIDString()取代,新的函数有稍微不同的接口.

UTF-16 和 UTF-32 API 函数和字节顺序标记

实现支持 UTF-16 和 UTF-32 Unicode 编码形式的 Unicode 函数现在需要以字节顺序标记为开头的字符串和符号,将返回以字节顺序标记为开头的字符串或符号.

mlint64 64-Bit 类型

在32位平台上,wstpint64 类型不再是一个结构,现在在所有支持平台上是一个本地64位整数类型.
Microsoft Windows
__int64
Mac OS X
long long
Linux
long long

WSTP API 对 const 的改变

以下 WSTP API 函数现在支持 const 类型的指针参量:

新的 WSTP 程序库名称

Microsoft Windows

Linux

Mac OS X

mprep

mprep 现在产生适于与接口 4 WSTP API 使用的代码.
WSTP API 变化

已去除的 API 函数

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

重新命名的 API 函数

旧 API 函数
新 API 函数
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()

新 API 函数

WSCompilerID()
WSReleaseCompilerID()
WSReleaseUCS2CompilerID()
WSReleaseUTF16CompilerID()
WSReleaseUTF32CompilerID()
WSReleaseUTF32CompilerID()
WSReleaseUTF8CompilerID()
WSUCS2CompilerID()
WSUTF16CompilerID()
WSUTF32CompilerID()
WSUTF8CompilerID()
WSGetInteger8ArrayData()
WSLowLevelDeviceName()
WSPutInteger8ArrayData()
WSRleeaseLowLevelDeviceName()