The standard spy library

The standard spy library provides a unique interface to acquire events:

The library itself can get the events only from a circular buffer. However, if on the system runs a spy daemon that comunicates with the remote machine (via the farm spy daemon ) or reads from a YBOS file, the library can access also that type of events.

In order to use the library, three (plus one) steps are needed:

  1. connection to the circular buffer
    This step is normally done once at the startup.

    The syntax of the command is:
    int spy_open(char *keyname, SPY_id *sid);

    where:

    • keyname is the name of the circular buffer (i.e. "/tmp/B_1_1")
    • sid is the pointer to the spy ID that will be used inside other spy routines

    The return value of the routine is SPY_ERROR_OK if everything went OK, any other value should be treated as an error.

  2. information retrieval
    This step is repeated several times during the execution of the application.

    The syntax of the command is:
    int spy_get(SPY_id sid, char *buf, int *bufsize);

    where:

    • sid is the spy ID obtained during the connection to the circular buffer
    • buf is a pointer to a buffer. Will be filled with data of an event, if everything goes OK.
    • bufsize is :
      • IN : The size of the buffer
      • OUT: The size of the event

    The return value of the routine is:

    • SPY_ERROR_OK if everything went OK
    • SPY_ERROR_EMPTY if no new events are currently available (if bufsize!=0, the buffer was to small to contain the new event)
    • any other value should be treated as an error.

  3. internal buffer flushing
    This step is seldom used. It is useful only if you don't use the spy for a long period you want be sure the next event you get is a fresh one.

    The syntax of the command is:
    int spy_refresh(SPY_id sid);

    where:

    • sid is the spy ID obtained during the connection to the circular buffer

    The return value of the routine is:

    • SPY_ERROR_OK if everything went OK
    • any other value should be treated as an error.

  4. disconnection from the circular buffer
    This step is normally done once before exiting.

    The syntax of the command is:
    int spy_close(SPY_id sid);

    where:

    • sid is the spy ID obtained during the connection to the circular buffer

    The return value of the routine is SPY_ERROR_OK if everything went OK, any other value should be treated as an error. However, since this is the disconnecting phase, most of the time you can ignore the result.

The applications using this library should include spy.h and be linked with libspy.a.

Back to the spy libraries Top of the page.
Send comments to: Igor Sfiligoi
Created:14.12.1998
Last modified:16.12.1998