OpenersNotesSection(Spacer1)Details

WSGetByteString() allocates memory for the array of character codes. You must call (NonWLLink[WSReleaseByteString(), paclet:ref/c/WSReleaseByteString]) to disown this memory. If WSGetByteString() fails and the function's return value indicates an error, do not call (NonWLLink[WSReleaseByteString(), paclet:ref/c/WSReleaseByteString]) on the value contained in s.

WSGetByteString() is convenient in situations where no special characters occur.

The character codes used by WSGetByteString() are exactly the ones returned by ToCharacterCode in the Wolfram Language.

The array of character codes in WSGetByteString() is not terminated by a null character.

Characters such as newlines are specified by their raw character codes, not by ASCII forms such as ∖n.

WSGetByteString() returns immutable data.

WSGetByteString() returns 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 WSGetByteString() fails.

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

/* read a string encoded with codes from ToCharacterCode[] from a link */

void f(WSLINK lp)
{
	const unsigned char *string;
	int length;

	if(! WSGetByteString(lp, &string, &length, 0))
		{
			/* unable to read the byte string from lp */
			return;
		}

	/* ... */

	WSReleaseByteString(lp, string, length);
}

({{DocumentationFooterIconsRelatedFunction.png, ({{See Also}, {(NonWLLink[WSReleaseByteString(), paclet:ref/c/WSReleaseByteString])  ▪  (NonWLLink[WSGetString(), paclet:ref/c/WSGetString])  ▪  (NonWLLink[WSGetUCS2String(), paclet:ref/c/WSGetUCS2String])  ▪  (NonWLLink[WSGetUTF8String(), paclet:ref/c/WSGetUTF8String])  ▪  (NonWLLink[WSGetUTF16String(), paclet:ref/c/WSGetUTF16String])  ▪  (NonWLLink[WSGetUTF32String(), paclet:ref/c/WSGetUTF32String])}})}})

({{DocumentationFooterIconsRelatedTutorial.png, ({{Tutorials}, {▪(RefLinkPlain[Manipulating Expressions in External Programs, paclet:tutorial/ManipulatingExpressionsInExternalPrograms])}, {▪(RefLinkPlain[Handling Lists, Arrays and Other Expressions, paclet:tutorial/HandlingListsArraysAndOtherExpressions])}, {▪(RefLinkPlain[Portability of WSTP Programs, paclet:tutorial/PortabilityOfWSTPPrograms])}, {▪(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[Alphabetical Listing of WSTP C Functions, paclet:guide/AlphabeticalListingOfWSTPCFunctions])}, {▪(RefLinkPlain[WSTP C Functions for Exchanging Strings, paclet:guide/WSTPCFunctionsForExchangingStrings])}})}})