In order to maximize the power of the API, it is written in C++ and exports a number of classes to the client. These classes represent the event base, the event contexts (task contexts, interrupt contexts, and the idle context), and the individual events. These classes are called WVEventBase, WVContext, and WVEvent respectively, and are defined in installDir/host/include/wvapi.h.

There is also a class that acts as a cursor, which points into the event base and can be moved around to search for events of specific kinds, in one context or in any. This class is called WVCoords and is defined in wvapi.h.

In keeping with the latest C++ Standards, these public classes are implemented as containers similar to STL containers. They provide iterator classes which allow searching and extraction of sub-ranges using Standard Library algorithms.

The API ships as a dynamically-linked shared library and functions as a Tcl extension package that can be loaded into tclsh or wish at runtime with the load command.

To instantiate an object representing a complete event log, an object of class WVEventBase is created. Its constructor requires the name of the event-log file, usually ending in a .wvr suffix. If the file cannot be opened, is not in the required format, or some error occurs while building the in-memory data structures, a wv_error exception is thrown.

The WVEventBase class exposes the following useful public member functions:

WVEventBase(Tcl_Interp *pTcl=0); 

takes an optional Tcl interpreter and constructs an empty event base. If no Tcl interpreter is supplied, one is created.

STATUS load(const char *fileName); 

attempts to load an event-log file or files into the event base. The routine returns OK or ERROR and may throw wv_error exceptions if underlying file-system errors occur.

UINT32 size() const; 

returns the number of contexts in the event base.

WVContext operator[](unsigned index) const; 

returns a WVContext object from the index position in the event-base sequence of contexts.

const_iterator begin() const; 

returns a WVEventBase::const_iterator representing the start of the sequence.

const_iterator end() const; 

returns a WVEventBase::const_iterator representing the first position past the end of the sequence.

string name() const; 

returns the name of the event base.

int cpuId() const; 

returns the processor ID of the event base.

string eventName(const WVEvent& ev) const; 

returns the name of the event ev in human-readable format. This name is gathered from the event-description file loaded when the parser is loaded.

WVContext contextFromUniqueId(int uid) const; 

returns a WVContext object that corresponds to the unique ID given as the argument.

WV_TIME startTime() const;  
WV_TIME endTime() const; 

return the first and last timestamps of the events contained within the event base.

This section details the public member functions of the WVContext class, which represents a single context (task, interrupt, or idle) within the instrumented target. Internally, it is composed of a simple reference into the private internal data structures which takes up very little real application memory. Thus, it is safe for the application to build lists or vectors of these objects, for whatever reason.

The class also exposes an iterator type. It represents positions inside the context, viewing the context as a sequence of events and allowing application of STL standard algorithms to perform binary searches and other functions.

The public member functions of the WVContext class are:

UINT32 size() const; 

returns the size of the context when viewed as a sequence of events, in other words, the number of events in the sequence.

int uniqueId() const; 

returns a unique integer which distinguishes this context from all others within the same event base, including those that may have the same taskID( ) or name( ) values.

VX_ID taskId() const; 

returns the target-specific task ID, which may not be unique because task IDs can be reused by VxWorks. To uniquely identify a task within the event base, use the uniqueID( ) method to get a unique integer value.

string name() const; 

returns the task name (for example, tMainTask).

int priority() const; 

returns the task priority.

iterator begin() const; 

returns a WVContext::iterator representing the start of the sequence.

iterator end() const; 

returns a WVContext::iterator representing the first position past the end of the sequence.

BOOL isInterrupt() const; 

tests whether this is an interrupt context (as opposed to a task context).

BOOL isIdle() const; 

tests whether this is the idle context.

This section details the public member functions and public data members of the class WVEvent, which represents a single event from the event base. When you create an object of this class, it retrieves the real event data from the private event-base data structures within the API library and stores them in the private data members of the WVEvent object. You then access this data using public member functions.

Do not create too many WVEvent objects at once when dealing with a large event log, because each object takes up some small but significant amount of application memory when created. Instead, create events one at a time within a loop, by iterating over a WVContext with an WVContext::iterator object and dereferencing the iterator each time, as shown by the following example:

WVContext::iterator i; 
for (i = ctxt.begin(); i != ctxt.end(); i++) 
{ 
WVEvent e = *i; 
 
// do something useful with e like look at its time, its 
// parameters, etc... 
}

The following public member-functions are available from the class:

string name() const; 

returns a C++ SL string object containing the event name (for example, semTake).

UINT32 type() const; 

returns the event-type code as an integer number (for example, 10015).

WV_TIME timeStamp() const; 

returns the timestamp of the event in standard WindView format.

int numParams() const; 

returns the number of parameters to the event.

UINT32 param(int index) const; 

returns the indexth parameter of the event. The order, type, and meanings of the event parameters can be found in the event dictionary (see B. Event Dictionary).

bool isStateChange() const; 

indicates whether a particular event was a state-change event.

UINT32 state() const; 

returns the current state of the task or context. It works for all events, not just state-change events.

Public member functions for comparison and equality of two event objects are also provided. These allow WVEvent objects to be stored in STL containers and manipulated by STL algorithms. Thus, an application can make a copy of small parts of the event base and manipulate it in many ways.

This class provides a simple way of traversing the event base and limiting or filtering the events displayed in various ways. Given an existing WVEventBase object, a WVCoords object can be created to look at events inside the event base, applying various restrictions. These restrictions include the type of event to look at, which can be any event or a specific type, and the context to search, which can be any context or a specific one.

The public member function move( ) and the operators ++ and -- move the WVCoords object through the event base. They return a boolean value indicating whether the movement was made or not. If not, no more events meeting the current search criteria could be found. The WVCoords object can be dereferenced using the operator *( ) and results in a WVContext::iterator, which can itself be dereferenced to retrieve an actual WVEvent object.

The following public member functions are available from the class:

WVCoords(); 

is the default constructor.

WVCoords(const WVEventBase*, WV_TIME, const WVContext&, EVENT_TYPE); 

is a constructor where the caller must provide a particular context and a particular event type.

WVCoords(const WVEventBase*, const WVContext::iterator&); 

is a constructor where the caller must provide an existing WVContext::iterator, in other words, an existing event location within the event base.

BOOL move(int direction); 

moves the coordinates object forwards (direction = 1) or backwards (direction = -1) through the event base, with possible restrictions applied.

static WVContext anyContext(); 

is a helper function which returns a pseudo-NULL value meaning any context. This is to used when constructing an object using the WVCoords constructor in the four-argument form.

static EVENT_TYPE anyEvent(); 

is a helper function which returns a pseudo-NULL value meaning any event. This is used when constructing an object using the WVCoords constructor in the four-argument form.

const WVEventBase& eventBase() const; 

returns the event-base object referenced by the coordinates object.

WVContext::iterator operator*() const; 

is the dereference operation; it returns an iterator indicating the specific event pointed to by the current coordinates.

BOOL operator++(int); 

is a shortcut for move(-1).

BOOL operator--(int); 

is a shortcut for move(1).

void contextLock(BOOL); 

locks the search to the current context.

void eventTypeLock(BOOL); 

locks the search to the current event type.

void eventTypeSet(EVENT_TYPE); 

sets the search target event type.

void contextSet(const WVContext&); 

sets the search target context.

void timeSet(WV_TIME); 

sets the search target time.

string contextName() const; 

returns the name of current context.

Table D-1 shows the compiler that can be used with the C++ API library on each host. The API library can only be expected to work with other applications if compiled with these toolchains.

Table D-1:  Supported Compilers

In general, the WindView API classes report runtime errors with C++ exceptions. All standard library exceptions, like bad_alloc, are caught internally. The API classes re-throw wv_error exceptions with suitable human-readable messages plus an integer error code. The error-code values are defined in the header installDir/host/include/wvapi.h which ships with the library.