WSGetLinkedEnvIDString (C Function)

int WSGetLinkedEnvIDString(WSLINK link,const char **e)

returns the identification string of the WSTP environment connected to link and stores it in e.

Details

  • WSGetLinkedEnvIDString() allocates the memory for the string eid. You must call WSReleaseEnvIDString() to disown this memory. If WSGetLinkedEnvIDString() fails and the function's return value indicates an error, do not call WSReleaseEnvIDString() on the contents of e.
  • WSGetLinkedEnvIDString() returns an immutable string.
  • The environment identification returned by WSGetLinkedEnvIDString() is a null-terminated ASCII string.
  • WSGetLinkedEnvIDString() will not work until link is connected.
  • WSGetLinkedEnvIDString() returns 0 in the event of an error, and a nonzero value if the function succeeds.
  • Use WSError() to retrieve the error code if WSGetLinkedEnvIDString() fails.
  • WSGetLinkedEnvIDString() is declared in the WSTP header file wstp.h.

Examples

Basic Examples  (1)

#include <string.h>
#include "wstp.h"

/* read the id from a link and check for "My Remote Program" */

#define ERROR -1

int f(WSLINK lp)
{
    int isCorrectProg;
    const char *e;

    if(! WSGetLinkedEnvIDString(lp, &e))
        {
            /* unable to read the link id from lp */
            return ERROR;
        }

    isCorrectProg = strcmp(envid, "My Remote Program") == 0;

    WSReleaseEnvIDString(lp, e, length);

    return isCorrectProg;
}