WSGetMessage (C Function)

int WSGetMessage(WSLINK link,int* code,int*param)

reads an out-of-band message code from the urgent message channel associated with link and stores the code in code and any parameter in param.

Details

  • WSGetMessage() returns a nonzero value if it reads an out-of-band message and 0 otherwise.
  • WSGetMessage() is a nonblocking function.
  • WSGetMessage() can return the following messages:
  • WSTerminateMessageshut down the current program
    WSInterruptMessageinterrupt the current operation
    WSAbortMessageabort the current operation
    WSEndPacketMessageobsolete message
    WSSynchronizeMessagesynchronize the internal expression streams for both sides of the link
    WSImDyingMessageother side of the link is shutting down
    WSWaitingAcknowledgementother side of the link needs a response
    WSMarkTopLevelMessageWSTP library internal message
    WSLinkClosingMessageWSTP library internal message
    WSAuthenticationFailurefailure to authenticate message
    WSFirstUserMessagebeginning of user-defined message space
    WSLastUserMessageend of user-defined message space
  • WSFirstUserMessage should be used as the starting value for any user-defined messages. You could define a new message as #define MyAppMessage WSFirstUserMessage + 1.
  • User-defined messages should not have values larger than WSLastUserMessage.
  • Standard WSTP messages do not have any parameters.
  • WSGetMessage() is declared in the WSTP header file wstp.h.

Examples

Basic Examples  (1)

#include "wstp.h"

/* read an out-of-band message code from a link */

void f(WSLINK lp)
{
    int code, param;

    if(WSMessageReady(lp))
    {
        if(! WSGetMessage(lp, &code, &param))
            { /* unable to read the message code from lp */ }
    }
}