WSTP Interface 4

Interface 4用のWSTPにおける変更点

新しいリンクプロトコル

Interface 4では「IntraProcess」と呼ばれる新しいリンクプロトコールが導入された.IntraProcessは同一プロセス中のスレッド間での高速な全二重接続のために設計されている.
#include "wstp.h"

int main()
{
    WSENV env;
    WSINK 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 == (WSINK)0 || error != WSEOK)
    { /* Unable to create link object */ }

    /* ... */

    WSClose(link);
    WSDeinitialize(env);
    return 0;
}
リッスンするIntraProcessリンクを生成するコードの例

スレッドセーフリンク

Interface 4では,リンクオブジェクトに対してスレッドセーフな新しいAPI関数と内部機能が導入された.以前のバージョンのWolfram Symbolic Transfer Protocol (WSTP)では,WSTP API関数を介して安全にリンクオブジェクトにアクセスできるのは,一度に1つのスレッドからだけであった.今回ライブラリにAPIレベルでリンクオブジェクトに対してスレッドの安全性を提供するメカニズムが実装されたことで,複数のスレッドから同時に同じリンクオブジェクトに対してWSTP API関数を安全に呼び出すことができるようになった.
WSEnableLinkLock()
リンクオブジェクトに対するスレッドセーフメカニズムを有効にする
WSDisableLinkLock()
リンクオブジェクトに対するスレッドセーフメカニズムを無効にする
スレッドセーフAPI関数

ログの導入

Interface 4 WSTPライブラリでは,WSTPストリームを通過する式をファイルシステムの中のファイルにログできる機能が導入されている.
WSLogStreamToFile()
メッセージのログを有効にし,式のストリームを指定されたファイルにログする
WSStopLoggingStreamToFile()
与えられたリンクに対して,指定されたファイルへのログを中止する
WSStopLoggingStream()
与えられたリンクに対して,ログ機能を無効にする
WSDisableLoggingStream()
与えられたリンクに対するログ機能を一時的に無効にする
WSEnableLoggingStream()
与えられたリンクに対するログを再び有効にする
API関数のログ

サービス発見と宣伝

Interface 4 WSTPライブラリでは,通信にWSTPプロトコルを使用するサービス発見および宣伝操作を提供するために設計された,新しいAPI関数が導入されている.
WSBrowseForLinkServices()
リンクサービス発見のためのネットワークブラウズ操作を開始する
WSStopBrowsingForLinkServices()
利用可能なリンクサービスを探してネットワークをブラウズすることを中止する
WSResolveLinkService()
指定されたリンクサービスに対する解決操作を開始する
WSStopResolvingLinkService()
指定されたリンクサービスに対する接続詳細の解決を中止する
WSRegisterLinkServiceWithPortAndHostname()
ポートとホスト名においてマシン上で指定されたリンクサービスを宣伝する
WSRegisterLinkServiceWithHostname()
ホスト名のあるマシン上で指定されたリンクサービスを宣伝する
WSRegisterLinkService()
マシン上で指定されたリンクサービスを宣伝し,WSTPにポートとホスト名を選ばせる
WSStopRegisteringLinkService()
指定されたリンクサービスの宣伝を中止する
サービス発見のAPI関数

リンクサーバ

Interface 4 WSTPライブラリには,クライアント/サーバスタイルの1対多接続を提供するための設計された新しいAPIが導入されている.このリンクサーバ機能により,プログラムがWSTP TCPIPリンクプロトコル接続を利用可能にすることができるようになり,多数のクライアントが同じWSTP TCPIPエンドポイントに接続できるようになり.
WSNewLinkServer()
新規のリンクサーバオブジェクトを生成し,WSTPライブラリにTCPIPポートとインターフェースを選ばせる
WSNewLinkServerWithPort()
指定されたポート上に新規のリンクサーバオブジェクトを生成し,WSTPライブラリにTCPIPインターフェースを選ばせる
WSNewLinkServerWithPortAndInterface()
指定されたポートとインターフェース上に新規のリンクサーバオブジェクトを生成する
WSShutdownLinkServer()
リンクサーバ接続を閉じる
WSRegisterCallbackFunctionWithLinkServer()
新規のうクライアントがリンクサーバエンドポイントに接続したときに呼び出すリンクサーバに対するコールバック関数を登録する
WSWaitForNewLinkFromLinkServer()
クライアントがリンクサーバエンドポイントに接続するのを同時に待つ
WSPortFromLinkServer()
リンクサーバエンドポイントによって使われるポート番号を得る
WSInterfaceFromLinkServer()
リンクサーバエンドポイントによって使われるインターフェースを得る
WSContextFromLinkServer()
生成時にリンクサーバオブジェクトに登録したコンテキストを取り戻す
WSReleaseInterfaceFromLinkServer()
WSInterfaceFromLinkServer()への呼び出しでWSTPライブラリによって割り当てられたメモリを解放する
リンクサーバAPI関数

一般のAPI関数に対する完全なUnicodeサポート

Interface 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関数

WLErrorMessage()

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

Interface 3ではWSTP API関数名の新しいパターンが導入された.Interface 4でもInterface 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関数

Interface 4 WSTPライブラリでは,0で終わるすべての関数が削除された.便利なサービスを提供していた関数については,Interface 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関数

Interface 4 WSTPライブラリでは,WSCheckファミリの関数が,対応するWSTestを後継として廃止される予定になっている.
WSCheckFunction()
WSCheckFunctionWithArgCount()

Unicode関数と16Bit関数

Interface 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関数

Interface 3はWSPutInteger16(),WSPutInteger32(), およびWSGetInteger16(),WSGetInteger32(),等,WSPutIntegerおよびWSGetIntegerの関数ファミリに新しい形式を導入した.Interface 4ライブラリでは8ビット整数のサポートが加わった.
WSPutInteger8()
8ビット整数を送る
WSPutInteger8List()
8ビット整数のリストを送る
WSPutInteger8Array()
8ビット整数の多次元配列を送る
WSGetInteger8()
8ビット整数を読む
WSGetInteger8List()
8ビット整数のリストを読む
WSGetInteger8Array()
8ビット整数の多次元配列を読む
WSReleaseInteger8List()
WLGetInteger8List()により割り当てられたメモリを解放する
WSReleaseInteger8Array()
WLGetInteger8Array()により割り当てられたメモリを解放する
新しいWSGetInteger8関数

WSTP APIの動作の変更

WSEnvironmentParameter

Interface 4では,WSENVパラメータオブジェクトを生成,修正,利用するAPI関数が変更された.Interface 3ではこれらの関数はタイプWSParametersのオブジェクトに効果があった.Interface 4では,WSParametersの代りにWSEnvironmentParameterオブジェクトになった.

WSNewParameters() API関数

WSNewParameters()が,WSReleaseParameters()への呼出しにより解放されなければならないWSEnvironmentParameterオブジェクトを返すようになった.

WSErrorMessage() API 関数

WSErrorMessage()関数が,WSReleaseErrorMessage()と一緒に解放されなければならないメッセージ文字列を返すようになった.さらに,Unicodeサポートを含む新しいWSErrorMessage()スタイルの関数も対応するWSReleaseErrorMessage()関数を持つようになった.

WSLinkName() API関数

WSLinkName()関数がWSReleaseLinkName()と一緒に解放されなければならない名前の文字列を返すようになった.さらに,Unicodeサポートを含む新しいWSLinkName()スタイルの関数も対応するWSReleaseLinkName()スタイルの関数を持つようになった.

WSGetLinkedEnvIDString0() API関数

Interface 4では関数WSGetLinkedEnvIDString0()がなくなった.この代りにWSGetLinedEnvIDString()が使われるようになった.この新関数は前の関数とはわずかに異なるインターフェースを持つ.

UTF-16およびUTF-32のAPI関数とバイト順マーク

UTF-16およびUTF-32のUnicodeコード化形式のサポートを実装するUnicode関数で,文字列やシンボルのPutにはバイト順マークから始めることが必要になった.また,Getではバイト順マークを含む文字列やシンボルが返される.

mlint64 64ビットタイプ

32ビットのプラットフォームでは,wstpint64型が構造体ではなくなり,すべてのサポートされるプラットフォーム上でネイティブの64ビット整数型となった.
Microsoft Windows
__int64
Mac OS X
long long
Linux
long long

constに対するWSTP API関数の変更点

次のWSTP API関数では,const型のポインタ引数が取れるようになった.

新しいWSTPライブラリの名前

Microsoft Windows

Linux

Mac OS X

mprep

mprepはInterface 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()