OpenersNotesSection(Spacer1)Details

Use WSPutRawData() in conjunction with (NonWLLink[WSPutType(), paclet:ref/c/WSPutType]) and (NonWLLink[WSPutRawSize(), paclet:ref/c/WSPutRawSize]) to manually put data to a link rather than using the type-specific API functions such as (NonWLLink[WSPutInteger32(), paclet:ref/c/WSPutInteger32]) or (NonWLLink[WSPutUTF8String(), paclet:ref/c/WSPutUTF8String]).

Sending numerical data with WSPutRawData() bypasses the WSTP library's internal mechanisms for ensuring data compatibility between heterogeneous computer systems. To use this function, users will need to account for endianness and C-type size differences between computer systems.

When sending character data, use (NonWLLink[WSPutType(), paclet:ref/c/WSPutType]) with the token argument WSTKOLDSTR for string data or WSTKOLDSYM for symbol data. Do not use WSPutRawData() to send character data in any format other than 7-bit ASCII encoding.

When sending numerical data, use (NonWLLink[WSPutType(), paclet:ref/c/WSPutType]) with the correct token for the binary data. The WSTP header file (RefLink[wstp.h, paclet:ref/file/wstp.h]) contains the complete list of these tokens, but the more common tokens are listed here for convenience:

WSPutRawData() returns a 0 in the event of an error and a nonzero value if the function succeeds.

Use (NonWLLink[WSError(), paclet:ref/c/WSError]) to retrieve the error code if WSPutRawData() fails.

WSPutRawData() is declared in the WSTP header file (RefLink[wstp.h, paclet:ref/file/wstp.h]).

OpenersPrimaryExamplesSection(Spacer1)Examples  (1)

OpenersExampleSection0(Spacer1)Basic Examples  (1)

#include "wstp.h"

/* send a function as raw data to a link */

void f(WSLINK lp)
{
	int a = 2, b = 3;

	if(! WSPutType(lp, WSTKFUNC))
		{ return; /* unable to put the function type to lp */ }

	if(! WSPutArgCount(lp, 2))
		{ return; /* unable to put the number of arguments to lp */ }

	if(! WSPutType(lp, WSTKOLDSYM))
		{ return; /* unable to put function head type to lp */ }
	
	if(! WSPutRawSize(lp, 4))
		{ return; /* unable to put the size of the symbol to lp */ }

	if(! WSPutRawData(lp, (const unsigned char *)"Plus", 4))
		{ return; /* unable to put the raw bytes to lp */ }

	if(! WSPutType(lp, WSTK_CINT))
		{ return; /* unable to put the argument type to lp */ }

	if(! WSPutRawSize(lp, sizeof(int)))
		{ return; /* unable to put the size of the integer to lp */ }

	if(! WSPutRawData(lp, (const unsigned char *)&a, sizeof(a)))
		{ return; /* unable to put the raw bytes of a to lp */ }

	if(! WSPutType(lp, WSTK_CINT))
		{ return; /* unable to put the second argument type to lp */ }

	if(! WSPutRawSize(lp, sizeof(int)))
		{ return; /* unable to put the size of the integer to lp */ }

	if(! WSPutRawData(lp, (const unsigned char *)&b, sizeof(b)))
		{ return; /* unable to put the raw bytes of b to lp */ }
}

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(NonWLLink[WSPutNext(), paclet:ref/c/WSPutNext])  ▪  (NonWLLink[WSPutType(), paclet:ref/c/WSPutType])  ▪  (NonWLLink[WSPutRawSize(), paclet:ref/c/WSPutRawSize])  ▪  (NonWLLink[WSPutArgCount(), paclet:ref/c/WSPutArgCount])}})}})

({{DocumentationFooterIconsRelatedTutorial.png, ({{Tutorials}, {▪(RefLinkPlain[Manipulating Expressions in External Programs, paclet:tutorial/ManipulatingExpressionsInExternalPrograms])}, {▪(RefLinkPlain[WSTP C API Developer Guide (Mac OS X), paclet:tutorial/WSTPDeveloperGuide-MacintoshOverview])}, {▪(RefLinkPlain[WSTP C API Developer Guide (Unix and Linux), paclet:tutorial/WSTPDeveloperGuide-UnixOverview])}, {▪(RefLinkPlain[WSTP C API Developer Guide (Windows), paclet:tutorial/WSTPDeveloperGuide-WindowsOverview])}})}})

({{DocumentationFooterIconsRelatedGuide.png, ({{Related Guides}, {▪(RefLinkPlain[Low-Level WSTP Operations, paclet:guide/LowLevelWSTPOperations])}, {▪(RefLinkPlain[WSTP C Functions for Exchanging Data, paclet:guide/WSTPCFunctionsForExchangingData])}, {▪(RefLinkPlain[WSTP C Functions for Exchanging Expressions, paclet:guide/WSTPCFunctionsForExchangingExpressions])}, {▪(RefLinkPlain[WSTP C Language Functions, paclet:guide/WSTPCLanguageFunctions])}})}})