IVI-3.7 Event Server Spec v1

Interchangeable
Virtual
Instruments
IVI-3.7: IVI Event Server Specification
April 2002
Revision 1.0
Important Information
The IVI Event Server Specification (IVI-3.7) is authored by the IVI Foundation member companies. For a
vendor membership roster list, please visit the IVI Foundation web site at www.ivifoundation.org, or
contact the IVI Foundation at 2515 Camino del Rio South, Suite 340, San Diego, CA
92108.
The IVI Foundation wants to receive your comments on this specification. You can contact the Foundation
through email at ivilistserver@ivifoundation.org, through the web site at
www.ivifoundation.org, or you can write to the IVI Foundation, 2515 Camino del Rio
South, Suite 340, San Diego, CA 92108. Warranty
The IVI Foundation and its member companies make no warranty of any kind with regard to this material,
including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.
The IVI Foundation and its member companies shall not be liable for errors contained herein or for
incidental or consequential damages in connection with the furnishing, performance, or use of this material.
Trademarks
Product and company names listed are trademarks or trade names of their respective companies.
IVI-3.7: IVI Event Server Specification 2 IVI Foundation

1. Overview of the IVI Event Server Specification .............................7
1.1 Introduction ...................................................................................................................................... 7
1.2 IVI Event Server Overview .............................................................................................................. 7
1.3 References ........................................................................................................................................ 7
1.4 Definitions of Terms and Acronyms ................................................................................................ 8
1.5 Implementation................................................................................................................................. 9
2. IVI Event Server Capabilities.........................................................10

2.1 Component Diagram ...................................................................................................................... 10
2.2 Component Diagram Terminology................................................................................................. 11
2.2.1 IVI Event Server In Proc.................................................................................................. 11
2.2.2 IVI Event Server .............................................................................................................. 11
2.2.3 IIviEventServer ................................................................................................................ 11
2.2.4 IIviEventCallback, IIviEventCallbackFast....................................................................... 11
2.2.5 IIviEventSource................................................................................................................ 11
2.2.6 IVI Event Entry, IIviEventEntry ...................................................................................... 11
2.3 Capabilities of Major Components................................................................................................. 11
2.3.1 IVI Event Server In Proc.................................................................................................. 12
2.3.2 IVI Event Server .............................................................................................................. 12
2.3.3 IVI Event Entry................................................................................................................ 12
3. General Requirements...................................................................13
3.1 Nonfunctional Requirements.......................................................................................................... 13
3.2 Use Cases ....................................................................................................................................... 13
3.2.1 Actor: Client wanting to receive events (Sink Client)...................................................... 13
3.2.2 Actor: Client wanting to send events (Source Client) ...................................................... 13
3.2.3 Actor: Client wanting to retrieve the events (Retrieve Client) ......................................... 13
3.2.4 Actor: Client wanting to manage the events (Event Manager Client).............................. 14
4. IVI Event Server In Proc interfaces ...............................................15

4.1 IIviEventServer .............................................................................................................................. 15
4.1.1 Connect Source ................................................................................................................ 15
4.1.2 Connect Sink .................................................................................................................... 18
4.1.3 Disconnect Source............................................................................................................ 20
4.1.4 Disconnect Sink ............................................................................................................... 21
4.1.5 Send Event ....................................................................................................................... 22
4.1.6 Send Event Ex .................................................................................................................. 23
4.1.7 Get Next Event................................................................................................................. 24
4.1.8 Get Previous Event........................................................................................................... 25
4.1.9 Change My Source Event Level....................................................................................... 26
4.2 IIviEventManager........................................................................................................................... 27
4.2.1 Get Event Source Locations............................................................................................. 27
4.2.2 Get Event Sink Locations................................................................................................. 29
4.2.3 Get Event Source Info ...................................................................................................... 31
4.2.4 Get Event Sink Info.......................................................................................................... 32
4.2.5 SetEventSourceInfo.......................................................................................................... 33
4.2.6 Set Event Sink Info .......................................................................................................... 34
IVI Foundation 3 IVI-3.7: IVI Event Server Specification

5. IVI Event Server Interfaces............................................................35
6. Sink Client Interface ......................................................................36

6.1 IIviEventCallback........................................................................................................................... 36
6.1.1 Event Callback ................................................................................................................. 36
6.2 IIviEventCallbackFast .................................................................................................................... 37
6.2.1 Event Callback Fast.......................................................................................................... 37
7. Source Client Interface ..................................................................38

7.1 IIviEventSource.............................................................................................................................. 38
7.1.1 Event Level Changed ....................................................................................................... 38
8. IVI Event Entry Interface................................................................39

8.1 IIviEventEntry ................................................................................................................................ 39
8.1.1 IIviEventEntry Attributes................................................................................................. 39
8.1.1.1 Time Stamp .................................................................................................... 39
8.1.1.2 Nanoseconds .................................................................................................. 40
8.1.1.3 Description ..................................................................................................... 41
8.1.1.4 Select Code .................................................................................................... 42
8.1.1.5 Event Code..................................................................................................... 43
8.1.1.6 Event Type ..................................................................................................... 44
8.1.1.7 Host Name...................................................................................................... 45
8.1.1.8 Process Id ....................................................................................................... 46
8.1.1.9 Subsystem Name............................................................................................ 47
8.1.1.10 Role Name...................................................................................................... 48
8.1.1.11 View Name .................................................................................................... 49
8.1.2 IIviEventEntry Functions ................................................................................................. 50
8.1.2.1 Configure Location ........................................................................................ 50
8.1.2.2 Set Info........................................................................................................... 51
8.1.2.3 Get Info .......................................................................................................... 52
8.1.2.4 Format Event Entry ........................................................................................ 53
9. IVI Event Server Attribute Value Definitions ................................54
10. IVI Event Server Function Parameter Value Definitions..............55
11. Sample Use Scenario.....................................................................56
12. Client Requirements ......................................................................57

12.1 Source Client .................................................................................................................................. 57
12.2 Sink Client...................................................................................................................................... 57
13. Limitations......................................................................................58
13.1 Distributed Systems........................................................................................................................ 58
Appendix A: IDL file ................................................................................59

LIST OF FIGURES
FIGURE 2-1 – IVI EVENT SERVER ARCHITECTURE COMPONENT DIAGRAM 10

FIGURE 11-1 – IVI EVENT SERVER USE SCENARIO 56

IVI Event Server Specification Revision History
This section is an overview of the revision history of the IVI Event Server specification.
Table 1-1. Ivi-3.7 Revisions
Revision Number
Date of Revision Revision Notes
Revision 0.1 November 2, 2000 Original draft.

Revision 0.2 February 5, 2001 All data types are now automation data types.
Removed MSS from the interface function names.
Revision 0.3 February 13, 2001 Updated the problem statement with an example.
Added couple missing use case terminologies.
Interface function parameters and return codes are
now documented in tables.
Added missing IiviEventManager to the
component diagram and interface descriptions.
Revision 0.4 April 23, 2001 Style changes.
Added Ivi prefix to all event server interfaces and
classes.
Event Entry now contains a bunch of properties
with one high level function and other functions.
To avoid VB memory leaks, [out] parameters are
now either [in, out] or [out, retval].
The returned error codes are now all fit within
what’s defined in IVI Inherent Capabilities Spec.
Revision 0.5 June 29, 2001 FINAL DRAFT
Ivi Foundation Copyright notice added to IDL.
Revision 0.6 August 16, 2001 Ivi Foundation mailing address updated.
Final Review took place July 9 - July 27. As a
result of the review the following change was
made. The Event Server will no longer
automatically generate the HostName and Process
ID when the user calls put_HostName or
put_Process ID.
Reason: Distributed clients will want to call both
functions and will not want to have HostName or
Process ID overwritten.
ConfigLocation is a convenient high-level
function, which will still automatically generate
the host name and the process ID.
Revision 1.0 Apri 11, 2002 Accepted all changes. This is the final version.

1. Overview of the IVI Event Server Specification
1.1 Introduction
In a measurement system, there often exist multiple components that need to communicate with each other.
When measurement solutions from multiple vendors are integrated together, differences in how messages
and events are handled can cause serious interoperability problems. A centralized event (messaging) server
that provides a standard way of communicating events, overcomes interoperability problems and hides the
complexity of managing multiple connections and multiple types of events from client components.
In simple systems, there may exist other ways of event communications, e.g., via in-process callbacks. In
more complex measurement systems, however, a centralized event server provides considerable value
especially in the case of cross-process or cross-machine communications with multiple components.
Moreover, the existence of a centralized event server does not prevent simpler communication mechanisms
to be used in some parts of the system.
To give an example of a complex measurement system, assume there are four major components in the
system, a Graphic User Interface (GUI) application program, a measurement server, and two measurement-
specific drivers. The components may reside in the same process or in different processes. While
responding to user interactions, the GUI program starts a separate task that issues an operation command on
the measurement server and then continues to respond to user interactions. To execute the command, the
measurement server starts two parallel lengthy tasks, one for each measurement-specific driver. When
either measurement-specific driver finishes its task, it will notify the measurement server via an event that
it has completed its task and the data is available. When the measurement server has finished combining
the data and other processing, it will notify the GUI via an event that it has completed its task and it is
ready for the next operation. When an error occurs in either measurement-specific driver, the driver sends
an error event to the measurement server. The measurement server inspects the error event and may
ultimately send an operation-failed event to the GUI. During all these interactions, there is a requirement
that all events be logged for later inspections.
The IVI foundation Event Server addresses the needs of many complex systems. This purpose of this
specification is to capture the requirements and top-level design of the Event Server. The Application
Programming Interface (API) of the current Event Server is also documented in this specification.
1.2 IVI Event Server Overview
This document describes the requirements and top-level design of the IVI Event Server that will be
provided by the IVI foundation. Following the introduction, the general requirements of the system are
listed. The top-level architecture design is given with a component diagram and terminologies used.
Capabilities of major components in the architecture are also described. Detailed descriptions of all the
interface properties and functions follow. A sample use scenario diagram is then given. Next, the
requirements on clients that use the IVI Event Server in a system are listed. The document ends with the
limitations on the current release of the IVI Event Server and an appendix of its Interface Definition
Language (IDL) file.
1.3 References
Two documents are related to this specification.

• IVI-3.10 --- IVI-MSS Specification
• IVI-3.2 --- Inherent Capabilities Specification

1.4 Definitions of Terms and Acronyms
Event An event could be as simple as a numeric code plus an optional

text description or it could be a complete interface from which a
client can query any information associated with the event. The
associated information with the event could include the names of
the host machine, the subsystem, the role, and the component
where the event is originated.
Event Type Events can be categorized into status, warning, debug, error and
event. To give some examples, an “operation-completion” event is
a status event; an “operation-failed” event is an error event; a
“parameter out of range” event could be either a warning event or
an error event; a debug tracing message could be sent as an debug
event; a time-critical trigger message could be sent as an “event”
type event.
Event Server Event Server serves as a Mediator in the Mediator pattern. 1 It

decouples the source and the sink clients and hides the complexity
of managing multiple connections and multiple event types. Event
Server actually contains multiple components. This will be
clarified in the next two sections. For use case analysis, Event
Server can be treated as a single component.
Source Client A source is similar to the Subject in the Observer pattern.1 It calls
the Event Server to send any events that the Sinks might be
interested in. A client can be both a source and a sink.
Sink Client A sink is similar to the Observer in the Observer pattern.1 It

implements an interface that the Event Server can call when there
is an event that the sink is interested in.
Retrieve Client A retrieve client is a client that wants to retrieve events from the
Event Server log file, in forward or backward order.
Event Manager Client An event manager client is a client that queries or modifies the
connections of the source and sink clients of the Event Server.
Use Case A use case describes a particular, observable system behavior. The
set of the use cases define the functional system requirements.
Actor An external entity to the system who in some way participates in

the use case.
1
E. Gamma, R. Helm, R. Johnson, and J. Vlissides, “Design Patterns”, Addison Wesley, 1995.
1.5 Implementation
The IVI Foundation supplied implementation of the Event Server is available from the IVI Foundation web
site.

2. IVI Event Server Capabilities
2.1 Component Diagram
This is a simplified view of the Event Server architecture. Interfaces used solely between the Event Server
components are not shown in the diagram.
IUnknown IUnknown
IIviEventSource IIviEventServer
IVI Event Server
Source Client
In Proc
IIviEventManager
IUnknown
IUnknown
IUnknown
IIviEventManager
IIviEventCallback
IIviEventServer
IVI Event Server
IIviEventServer
IIviEventCallbackFast In Proc IVI Event
Sink Client IIviEventManager Server
IUnknown
IUnknown
IIviEventServer
IVI Event Server
In Proc
IIviEventCallback
Source and IIviEventManager
Sink Client
IUnknown
IUnknown
Log File
IIviEventEntry
IUnknown IVI Event
IIviEventEntry
IVI Event Entry
Entry
IIviEventCallback Event
Manager
Client
Figure 2-1 – IVI Event Server Architecture Component Diagram

2.2 Component Diagram Terminology
2.2.1 IVI Event Server In Proc
This is an in-process component, i.e., it runs in the client’s process space. All clients in a process are
attached to a single instance of Event Server In Proc component. The clients will directly talk to this in-
process component, not with the out-of-process Event Server.
2.2.2 IVI Event Server
There is a single out-of-process component called “EventServer” on one machine. When the system is
extended into distributed system, there will be a single master Event Server in the whole system and a slave
Event Server on each machine.
2.2.3 IIviEventServer
Both Event Server In Proc and Event Server implement the same interface called “IIviEventServer”. A
source client uses this interface on Event Server In Proc to send events. The Event Server In Proc uses this
interface on Event Server to forward the events to the Event Server. This interface is also used for a client
to retrieve events from the log file.
2.2.4 IIviEventCallback, IIviEventCallbackFast
A sink client implements either IIviEventCallback or IIviEventCallbackFast interface for receiving

interesting events. With IIviEventCallbackFast interface function, only minimum information about the
event is transmitted and received, thus it is a faster version of IIviEventCallback. If the client implements
both interfaces, the Event Server will favor the faster IIviEventCallbackFast interface.
2.2.5 IIviEventSource
A source client that wishes to receive event level change notifications may implement this interface. For
example, a sink client can request its source to stop sending any events if the source has implemented this
interface. This is not a required interface for a source.
2.2.6 IVI Event Entry, IIviEventEntry
IVI Event Entry and its IIviEventEntry interface provide a full set of query and manipulation functions for
an event.
2.3 Capabilities of Major Components

2.3.1 IVI Event Server In Proc
1. Implements the interface IIviEventServer.
2. Manages a “database” of in-process clients and their preferences.
3. Intercepts events of interest to a sink client in the same process and invokes the callback function on this
client.
4. Implements internal event caching in case that the machine or the network cannot absorb events faster than
the rate of event posting.
5. Optimizes latency of certain types of events.
6. Implements separate thread(s) for forwarding events to EventServer so that no caller will be blocked by the
forwarding operation.
7. Manages separate callback threads per sink client. A sink client is responsible to return from the callback
function as soon as possible. Delay in a callback thread will eventually influence the performance of that
client’s process.
2.3.2 IVI Event Server

1. Implements the interface IIviEventServer.
2. Manages a “database” of clients and their preferences.
3. Manages separate callback threads per sink client. A sink client is responsible to return from the callback
function as soon as possible. Moderate amount of delay in a callback thread, however, will likely only
influence the performance of that client’s process.
4. According to different types of events and client preferences, EventServer implements separate threads to
sort and/or persist the event.
5. Filters events so that a sink client will only receive those events that it is interested in.
6. Implements internal event caching in case that events cannot be processed faster than the rate of event
posting.
7. Optimizes latency of certain types of events.
8. Logs events into a central log file on the same machine and implements functionalities for retrieving events
from the log file in forward or backward order.
2.3.3 IVI Event Entry

1. Provides a full set of query and modification functions for an event.
2. When the Event Entry is created, it automatically generates the timestamp, the host name and the process
ID of the event. When the event server is extended into multiple machines, the clocks of the multiple
machines are assumed synchronized.

3. General Requirements
3.1 Nonfunctional Requirements
1. The first release of Event Server will be used in a single-computer system. The design of Event Server
shall allow easy extensibility into a distributed system.
2. The Event Server shall work on any Windows Operating systems with DCOM enabled, currently Win9x,
WinNT, and Win2000.
3. Performance of the Event Server is important since it effects how customer will perceive the whole system.
4. Event handling of one client shall not significantly influence the performance of the other clients.
5. Event Server shall provide reliable services to the clients. Even when the machine or the network cannot
absorb events faster than the rate of event posting, events shall not be lost.
6. Event Server shall not use unnecessary system resources when there is no event activities or no clients
requesting the service.
7. Events shall be able to hold any 32-bit error value from any clients.
8. Events shall be identifiable by its originating location.
9. Events shall be categorized into different types; each may have different requirements on event handling,
e.g., persistency or speed.
3.2 Use Cases
This section describes the common use cases of the Event Server. The terminologies used in the use cases
are defined in Section 1.4, Definitions of Terms and Acronyms.
3.2.1 Actor: Client wanting to receive events (Sink Client)

• Instantiate the sink connection to the Event Server.
• Modify the sink connection to the Event Server.
• Modify the types of the events that the source sends, i.e., change the event level.
• Receive an event from the Event Server.
• Detach from the Event Server.
3.2.2 Actor: Client wanting to send events (Source Client)

• Instantiate the source connection to the Event Server.
• Modify the source connection to the Event Server.
• Send an event.
• Receive the source event level change from the Event Server. (Optional)
• Detach from the Event Server.
3.2.3 Actor: Client wanting to retrieve the events (Retrieve Client)

• Get the next event in the log file.

• Get the previous event in the log file.
3.2.4 Actor: Client wanting to manage the events (Event Manager Client)
• Get the identification information of all source clients.
• Get the identification information of all sink clients.
• Get the event information of all source clients
• Get the event information of all sink clients.
• Set the event information for a source client.
• Set the event information for a sink client.

4. IVI Event Server In Proc interfaces
4.1 IIviEventServer
4.1.1 Connect Source
Description
There are two connect and two disconnect functions. If a component is both an event source and an event
sink, it calls both sets of connect and disconnect functions.
Before a source can send an event, it calls this function to connect itself to the Event Server. With this
function, the source client passes its own location information to the Event Server. It also specifies its
preferred settings for certain events. The source does not need to specify all the events it will send.
COM Method Prototype

HRESULT ConnectSource([in, unique] IIviEventSource * Source,
BSTR HostName, long ProcessId, BSTR SubSystemName,
BSTR RoleName, BSTR ViewName,
[in, unique] SAFEARRAY(IIviEventEntry * ) * Events,
[in, unique] SAFEARRAY(IviEventServerLatencyEnum) * Latencies,
[in, unique] SAFEARRAY(VARIANT_BOOL) * Orders,
[in, unique] SAFEARRAY(VARIANT_BOOL) * Logs,
[in, out] long * SourceCookie);
Parameters
Inputs Description Data Type

Source A source that wishes to receive event level change IIviEventSource
notifications can pass its IIviEventSource interface; *
otherwise, this parameter is passed in as NULL.
HostName The name of the host machine. If NULL or empty BSTR

string is specified as input, then the host name will
be automatically generated by the Event Server In
Proc.
ProcessId The ID of the process that the source client belongs long
to. If a value of zero or less is specified, then it will
Proc.
SubSystemName The name of the subsystem that the source client BSTR
belongs to, e.g., “This Measurement Subsystem”.
RoleName The name of the role that the source client belongs BSTR
to, e.g., “ Spectrum Analyzer”.
ViewName The name of the source client, e.g., “This Spectrum BSTR
Analyzer”.

Events A source can overwrite the default settings for SAFEARRAY(IIviE
certain events. This parameter is an array of events ventEntry * ) *
or masked events. The “events” parameter does not
represent all the events that the source will send,
rather, it represents the events for which the source
wants to overwrite the default settings. See
Compliance Notes for the default settings. To
specify the preferences, the “events” parameter can
be an array of single events, or it could be an array
of “masked” events. Events are masked by
specifying the event code as zero and by specifying
the select code as IviEventServerStatus,
IviEventServerEvent, IviEventServerWarning,
IviEventServerError, or IviEventServerDebug. See
Section 10. Event Server Parameter Value
Definitions for the select code definitions.
If NULLs are provided for this parameter or the size
of the array is zero, then it means that the source
accepts all the default settings. Accepting all default
settings is a common use case.
Latencies This is an array of latency settings corresponding to SAFEARRAY(IviEv
the “events” array. Refer to Defined values for entServerLatenc
Latencies for the latency setting definitions. yEnum) *
accepts all the default settings.
Orders This array also corresponds to the “events” array. SAFEARRAY(VARIA
This will determine whether the Event Server will NT_BOOL) *
sort the events or not.
Logs This array also corresponds to the “events” array. SAFEARRAY(VARIA
This will determine whether the Event Server will NT_BOOL) *
persist the events or not.
SourceCookie If 0, the event server gives back a new cookie to the [in, out] long
source to identify this connection. If nonzero, the *
event server will try to replace the setting of an
existing connection with the new settings. If this
fails, the server will treat it as a new connection.
Outputs Description Data Type

SourceCookie See the description of SourceCookie as an input. [in, out] long *
Defined Values for Latency

Name Identifier Description

Low Latency IviEventServerLatencyLow Events with latency setting of
IviEventServerLatencyLow will be sent first when the
server is running low on internal cache space.
Medium IviEventServerLatencyMedium When the server is running low on internal cache
Latency space, events with latency settings of
IviEventServerLatencyMedium will be sent after all
the events with IviEventServerLatencyLow have been
sent.
High Latency IviEventServerLatencyHigh When the server is running low on internal cache
space, events with latency settings of
IviEventServerLatencyHigh will be sent after all other
events have been sent.
Return Values
The IVI-3.2: Inherent Capabilities Specification defines general status codes that this function can return.
Compliance Notes
The source does not have to specify the settings for each event. In that case, the default settings in the
following table will be used.
Default Event Settings by Event Types
Event Type Latency Logged Sorted

Status Type Low Yes No
Event Type Low No No
Warning Type Medium Yes Yes
Error Type Medium Yes Yes
Debug Type High Yes Yes

4.1.2 Connect Sink
Description
Before a sink can receive an event, it must call this function to connect itself to the Event Server. With this
function, the sink client passes its own location information to the Event Server and also specifies its
interested events.

HRESULT ConnectSink([in, unique] IUnknown * IunkSink,
BSTR HostName, long ProcessId,
BSTR SubSystemName, BSTR RoleName,
BSTR ViewName,
[in, unique] SAFEARRAY(IIviEventEntry *) * InterestedEvents,
[in, out] long * SinkCookie);
Parameters

IUnkSink A sink client must implement either IIviEventCallback IUnknown *
or IIviEventCallbackFast interface for receiving
callbacks. The client supplies its IUnknown interface.
The server will do a QueryInterface to find out if it is an
IIviEventCallback or IIviEventCallbackFast interface
(see section 6 for the description of these two
interfaces). The Event Server will favor the faster
IIviEventCallbackFast if the client implements both
interfaces.
string is specified as input, then the host name will be
automatically generated by the Event Server In Proc.
ProcessId The ID of the process that the sink client belongs to. If long
a value of zero or less is specified, then it will be
automatically generated by the Event Server In Proc.
SubSystemName The name of the subsystem that the sink client belongs BSTR
to, e.g., “This Receive Subsystem”.
RoleName The name of the role that the sink client belongs to, BSTR
e.g., “ Measurement Server”.
ViewName The name of the sink client, e.g., “This Measurement BSTR
Server”.

InterestedEven A sink can provide an array of events that it is SAFEARRAY(IIv
ts interested in. Each IIviEventEntry interface pointer of iEventEntry *
the “interestedEvents” array represents an event or a ) *
masked event. Specifying NULL or providing an
empty array means that the sink client wishes to receive
all events.
To specify its interests, the “interestedEvents”
parameter can be an array of single events, or it could
be an array of “masked” events. Currently allowed
masks are any of the location information: host name,
process ID, subsystem name, role name or view name.
As an example, specifying NULL, empty string or “*”
for the role name means it is interested in all events as
long as the host name, process ID, and subsystem name
match. Specifying subsystem name as NULL, empty
string, or “*” means it is interested in all events as long
as the host name and process ID of the source matches.
Specifying 0 for process ID means it is interested in all
events as long as the host name matches.
Masks may also include the description field and the
select code.
The order of comparison from first to last is: host name,
process ID, subsystem name, role name, view name,
select code, event code, description.
SinkCookie If (*sinkCookie) is 0, the Server gives back a cookie to [in, out]
identify this connection, otherwise the server will try to long *
replace the setting of an existing connection with the
new settings. If this fails, the server will treat it as a
new connection.
SinkCookie See the description of SourceCookie as an input. [in, out]

long *
Return Values

4.1.3 Disconnect Source
Description
A source client (or a source and sink client) calls this function when it has finished using the Event Server
and before the client exits.
HRESULT DisconnectSource(long SourceCookie);
Parameters

SourceCookie The source connection identified by this cookie is torn long
down and cleaned up.
Return Values

4.1.4 Disconnect Sink
Description
A sink client (or a source and sink client) will call this function when it has finished using the Event Server
and before the client exits.
HRESULT DisconnectSink(long SinkCookie);
Parameters

SinkCookie The sink connection identified by this cookie is torn long
down and cleaned up.
Return Values

4.1.5 Send Event
Description
A source uses this function to send an event. This is the fast way to send an event with minimal
information.

HRESULT SendEvent(long EventCode, BSTR Description, long SourceCookie);
Parameters
EventCode This is a numeric code for the event. Event Sever will long
attempt to interpret this code as an HRESULT. The
most significant bit will be translated and converted to
either IviEventServerStatus (when the bit is 0) or
IviEventServerError (when the bit is 1). The select code
will contain this converted value. To send other types of
events, a client shall use SendEventEx.
Description This is a text description of the event. The parameter BSTR
can be NULL.
SourceCookie This identifies the source connection. long
Return Values

4.1.6 Send Event Ex
Description
A source uses this function to send an event. This is a slower version of SendEvent since it carries more
information.
HRESULT SendEventEx(long SelectCode, long EventCode,

BSTR Description,
[in, unique] SAFEARRAY(BSTR) * Infos,
long SourceCookie);
Parameters

SelectCode This is the select code of the event. See Section 10 IVI long
Event Server Parameter Value Definitions for its
definition. If the specified select code does not match
any of the defined values, the most significant bit of
EventCode will be translated and converted to either
IviEventServerStatus (when the bit is 0) or
IviEventServerError (when the bit is 1).
EventCode This is a numeric code for the event. long
Description This is a text description of the event. The parameter BSTR
can be NULL.
Infos The “infos” parameter specifies extra information of the SAFEARRAY(BST
event. If the “description” contains one or more “%s” R) *
strings, the FormatEventEntry method in IiviEventEntry
attempts to insert the array of extra information at those
locations. Otherwise, the “infos” is simply appended at
the end of the description. This parameter can be NULL
or empty which means there is no extra information
carried with this event.
SourceCookie This identifies the source connection. long
Return Values

4.1.7 Get Next Event
Description
A client uses this interface function to retrieve the next event that has already been persisted.
HRESULT GetNextEvent([in, out] long * EID,

[out, retval] IIviEventEntry ** EventEntry);
Parameters
EID This value uniquely identifies every event that is stored [in, out]
in the log file. long *
To get the first event, a client passes in zero as (*EID).
The server returns the first event in the log file and
updates the returned value of (*EID) to uniquely identify
the subsequent event in the log file. Thus by calling this
interface function in a loop and passing in an initial
value of zero, a client can traverse the entire length of
the log file from the first event to the last. After the last
event is retrieved, (*EID) is set to zero again and the first
event is returned.
EID See the description of EID as an input. [in, out]

long *
EventEntry This is the returned event. [out, retval]
IIviEventEntr
y **
Return Values

4.1.8 Get Previous Event
Description
A client uses this interface function to retrieve the previous event that has already been persisted. This
function is the reverse of GetNextEvent.
HRESULT GetPreviousEvent([in, out] long * EID,

Parameters

EID This value uniquely identifies every event that is [in, out]
stored in the log file. long *
To get the last event, a client passes in zero as (*EID).
The server returns the last event in the log file and
updates the (*EID) to uniquely identify the previous
event in the log file. Thus by calling this interface
function in a loop and passing in an initial value of
zero, a client can traverse the entire length of the log
file from the last event to the first. After the very first
event is retrieved, EID is set to zero again and the last
event is returned.

EID See the description of EID as an input. [in, out]
long *
EventEntry This is the returned event. [out, retval]
IIviEventEntr
y **
Return Values

4.1.9 Change My Source Event Level
Description
A sink client uses this function to inform its sources the types of events that they should be sending. A
source can ignore this command, since there is nothing enforced by the Event Server. The Event Server
will send this change request via the IIviEventSource interface of the source client if it exists.
HRESULT ChangeMySourceEventLevel(long Cookie,

long LevelVector);
Parameters
Cookie This identifies the sink connection. long

LevelVector This indicates the different levels of events. long
Defined Values for Level Vector

Status Level IviEventServerLevelVectorStatus This bit indicates whether to send the status
events.
Event Level IviEventServerLevelVectorEvent This bit indicates whether to send the event type
events.
Warning IviEventServerLevelVectorWarning This bit indicates whether to send the warning
Level events.
Error Level IviEventServerLevelVectorError This bit indicates whether to send the error
events.
Debug Level IviEventServerLevelVectorDebug This bit indicates whether to send the debug
events.
One would turn on the appropriate bit to indicate sending certain level of events. The bits can be or’ed
together to indicate multiple levels of events.
Return Values

4.2 IIviEventManager
4.2.1 Get Event Source Locations
Description
This function is used by an Event Manager client to query all the existing source connections in the system.
Each source is identified by location information supplied at the client connection time. The array of
cookies further uniquely identifies the connections.
HRESULT GetEventSourceLocations(
[in, out, unique] SAFEARRAY(BSTR) * HostNames,
[in, out, unique] SAFEARRAY(long) * ProcessIds,
[in, out, unique] SAFEARRAY(BSTR) * SubSystemNames,
[in, out, unique] SAFEARRAY(BSTR) * RoleNames,
[in, out, unique] SAFEARRAY(BSTR) * ViewNames,
[in, out, unique] SAFEARRAY(long) * SourceCookies);
Parameters
Refer to The parameters are made [in, out] to accommodate the
Output memory leak bug in Visual Basic.
parameters
table

HostNames Each array element matches with a cookie in the [in, out,
SourceCookies array. unique]
The host names for all sources. SAFEARRAY(BSTR)
*
ProcessIds Each array element matches with a cookie in the [in, out,
The process Ids for all sources. SAFEARRAY(long)
*
SubsystemName Each array element matches with a cookie in the [in, out,
s SourceCookies array. unique]
The subsystem names for all sources. SAFEARRAY(BSTR)
*
RoleNames Each array element matches with a cookie in the [in, out,
The role names for all sources. SAFEARRAY(BSTR)
*
ViewNames Each array element matches with a cookie in the [in, out,
The names for all sources. SAFEARRAY(BSTR)
*

SourceCookies The cookies for all source connections. [in, out,
unique]
SAFEARRAY(long)
*
Return Values

4.2.2 Get Event Sink Locations
Description
Similar to GetEvenSourceLocations except it returns all the sink connections.

HRESULT GetEventSinkLocations(
[in, out, unique] SAFEARRAY(long) * SinkCookies
);
Parameters

parameters
table

HostNames Each array element matches with a cookie in the [in, out,
The host names for all sources. SAFEARRAY(BSTR)
*
ProcessIds Each array element matches with a cookie in the [in, out,
The process Ids for all sources. SAFEARRAY(long)
*
SubsystemName Each array element matches with a cookie in the [in, out,
s SourceCookies array. unique]
The subsystem names for all sources. SAFEARRAY(BSTR)
*
RoleNames Each array element matches with a cookie in the [in, out,
The role names for all sources. SAFEARRAY(BSTR)
*
ViewNames Each array element matches with a cookie in the [in, out,
The names for all sources. SAFEARRAY(BSTR)
*

SourceCookies The cookies for all source connections. [in, out,
unique]
SAFEARRAY(long)
*
Return Values

4.2.3 Get Event Source Info
Description
This function is used by an Event Manager client to query the preference settings of a particular source
connection.
HRESULT GetEventSourceInfo(long SourceCookie,

[in, out, unique] SAFEARRAY(IIviEventEntry * ) * Events,
[in, out, unique] SAFEARRAY(IviEventServerLatencyEnum) * Latencies,
[in, out, unique] SAFEARRAY(VARIANT_BOOL) * Orders,
[in, out, unique] SAFEARRAY(VARIANT_BOOL) * Logs);
Parameters

parameters
table
Events The same array of events passed to ConnectSource. SAFEARRAY(IIviE

ventEntry * ) *
Latencies The same array of latencies passed to SAFEARRAY(IviEv
ConnectSource. entServerLatenc
yEnum) *
Orders The same array of orders passed to ConnectSource. SAFEARRAY(VARIA
NT_BOOL) *
Logs The same array of logs passed to ConnectSource. SAFEARRAY(VARIA
NT_BOOL) *
This is same as defined for Connect Source function.
Return Values

4.2.4 Get Event Sink Info
Description
This function is used by an event manager client to query the interested events of a particular sink
connection.
HRESULT GetEventSinkInfo(long SinkCookie,

[in, out, unique] SAFEARRAY(IIviEventEntry *) * InterestedEvents);
Parameters
parameters
table
InterestedEven The same array of events passed to ConnectSource. SAFEARRAY(IIviE

ts ventEntry * ) *
Return Values

4.2.5 SetEventSourceInfo
Description
This function is used by an event manager client to change the preference settings of a particular source
connection.
HRESULT SetEventSourceInfo(long SourceCookie,

[in, unique] SAFEARRAY(IviEventServerLatencyEnum) * Latencies,
[in, unique] SAFEARRAY(VARIANT_BOOL) * Logs);
Parameters

Events The same array of events passed to ConnectSource. SAFEARRAY(IIviE
ventEntry * ) *
Latencies The same array of latencies passed to SAFEARRAY(IviEv
ConnectSource. entServerLatenc
yEnum) *
Orders The same array of orders passed to ConnectSource. SAFEARRAY(VARIA
NT_BOOL) *
Logs The same array of logs passed to ConnectSource. SAFEARRAY(VARIA
NT_BOOL) *
This is same as defined for Connect Source function.
Return Values

4.2.6 Set Event Sink Info
Description
This function is used by an event manager client to change the interests of a particular sink connection.

HRESULT SetEventSinkInfo(long SinkCookie,
[in, unique] SAFEARRAY(IIviEventEntry *) * InterestedEvents);
Parameters
InterestedEven The same array of events passed to ConnectSource. SAFEARRAY(IIviE

ts ventEntry * ) *
Return Values

5. IVI Event Server Interfaces
This component implements the same interfaces as the Event Server In Proc component. Since the clients
always talk to the Event Sever In Proc component directly, the Event Server interfaces are not described in
this document.

6. Sink Client Interface
A sink client is responsible to return from the callback function as soon as possible. Moderate amount of
delay in a callback thread, however, will likely only influence the performance of one client process.
6.1 IIviEventCallback
6.1.1 Event Callback
Description
Each sink client who wishes to receive callbacks implements either IIviEventCallback or
IIviEventCallbackFast interface. If a sink client implements both interfaces, the Event Server will choose
the faster IIviEventCallbackFast interface. A sink client who wishes to query for location information of
the incoming event should implement IIviEventCallback interface. Through the IIviEventEntry interface
pointer, the sink client can query for the host name, the subsystem name, the process ID, the role name, and
the view name, timestamp, etc.
HRESULT EventCallback([in] IIviEventEntry * EventEntry);
Parameters

EventEntry This parameter contains full information about the IIviEventEntr
incoming event. y *
Return Values
If the function returns any standard COM exception codes, the server will retry later with the next event.
After a predetermined number of retries, the server will drop this sink connection. The events will still be
persisted if requested and will be sent to other working sink clients.

6.2 IIviEventCallbackFast
6.2.1 Event Callback Fast
Description
A sink client who only cares about the select code, the event code and the event message should implement
IIviEventCallbackFast.
HRESULT EventCallbackFast(long SelectCode, long EventCode, BSTR Description);
Parameters
SelectCode Refer to SendEvent function. long
EventCode Refer to SendEvent function. long
Description This is string description of the event sent by the source. BSTR
Return Values
If the function returns any standard COM exception codes, the server will retry later with the next event.
After a predetermined number of retries, the server will drop this sink connection. The events will still be
persisted if requested and will be sent to other working sinks.

7. Source Client Interface
7.1 IIviEventSource
7.1.1 Event Level Changed
Description
A source client who wishes to receive event level control from its clients should implement
IIviEventSource interface. When a sink requests an event level change through
ChangeMySourceEventLevel(), the Event Server invokes this function.
HRESULT EventLevelChanged(BSTR SinkHostName, long SinkProcessId,

BSTR SinkSubSystemName, BSTR SinkRoleName,
BSTR SinkViewName,
IviEventServerLevelVectorEnum LevelVector);
Parameters

SinkHostName The host name of the sink. BSTR
SinkProcessId The process ID of the sink. long
SinkSubSystemName The subsystem name of the sink. BSTR
SinkViewName The view name of the sink. BSTR
LevelVector A sink client could turn on/off the appropriate IviEventServerLevelV
bits in levelVector to ask its sources to send only ectorEnum
certain type of events.
Defined Values for Level Vector
The values are the same as in ChangeMySourceEventLevel function.
Return Values
If the function returns any standard COM exception codes, the server will retry later with the next event
change request. After a predetermined number of retries, the server will drop this source connection. The
events sent previously will still be persisted if requested and will be sent to any working sinks.

8. IVI Event Entry Interface
This component provides a full set of query and manipulation functions for an event.
8.1 IIviEventEntry
8.1.1 IIviEventEntry Attributes
The IIviEventEntry interface defines the following attributes:

• Time Stamp
• Nanoseconds
• Description
• Select Code
• Event Code
• Event Type
• Host Name
• Process Id
• Subsystem Name
• Role Name
• View Name
This section describes the behavior and requirements of each attribute.
8.1.1.1 Time Stamp

Data Type Access High Level Functions
DATE R/W Configure Location
COM Property Name
TimeStamp
Description
Set/Get the timestamp of an event. DATE is a standard OLE automation data type for expressing date and
time. The time includes hours, minutes, and seconds. To set/get the number of nanoseconds, use the
property “Nanoseconds”. The timestamp of an event entry is automatically set when it is first created,
however, a client may wish to change the timestamp by setting the TimeStamp property.

8.1.1.2 Nanoseconds
long R/W Configure Location
COM Property Name
Nanoseconds
Description
Set/Get the nanoseconds portion of the timestamp for an event. The nanoseconds portion of the timestamp
of an event entry is automatically set when it is first created, however, a client may wish to change it by
setting this property.

8.1.1.3 Description
BSTR R/W Configure Location
COM Property Name
Description
Description
Set/get the description of an event.

8.1.1.4 Select Code
COM Property Name
SelectCode
Description
Set/Get the select code of the event.
Defined Values for Select Code
Most bits of the select code are reserved for future use. The select code definition is currently the same as
the Event Type. See Section 9, IVI Event Server Attribute Values Definitions.

8.1.1.5 Event Code
COM Property Name
EventCode
Description
Set/Get the event code of the event. The event code is a numeric number for the event.

8.1.1.6 Event Type
IviEventServerEventTypeEnum R/W Configure Location
COM Property Name
EventType
Description
Set/Get the event type of the event. The event type is part of the select code of an event.
Defined Values for Event Type
Most bits of the Select Code are reserved for future use, so the current Select Code definitions are the same
as Event Type definitions.
Status Type IviEventServerStatus Events that indicate the status of an operation when
there is no error condition, for example, an “operation
completed” event is a status event.
Event Type IviEventServerEvent Events that are time-critical. For example, a trigger
event.
Warning IviEventServerWarning Events that indicate warning conditions, for example,
Type a “parameter out of range” event could be a warning
event.
Error Type IviEventServerError Events that indicate error conditions, for example, an
“operation failed” event is an error event.
Debug Type IviEventServerDebug Events for debugging purposes, for example, traces
inserted by the developers.

8.1.1.7 Host Name
COM Property Name
HostName
Description
Set/Get the host machine name of the event.

8.1.1.8 Process Id
COM Property Name
ProcessId
Description
Set/Get the process identifier of the event.

8.1.1.9 Subsystem Name
COM Property Name
SubsystemName
Description
Set/Get the name of the subsystem that the event belongs to, e.g., “Measurement Subsystem A”.

8.1.1.10 Role Name

COM Property Name
RoleName
Description
Set/Get the name of the role that the event belongs to, e.g., “ Spectrum Analyzer”.

8.1.1.11 View Name
COM Property Name
ViewName
Description
Set/Get the name of the source that the event belongs to, e.g., “ Spectrum Analyzer B”.

8.1.2 IIviEventEntry Functions
The IiviEventEntry interface defines the following functions:

• Configure Location
• Set Info
• Get Info
• Format Event Entry
8.1.2.1 Configure Location
Description
This function configures the location attributes of an event. These attributes are the host name, the process
identifier, the subsystem name, the role name and the view name.

HRESULT ConfigureLocation(BSTR hostName, long processId,
BSTR subSystemName, BSTR roleName, BSTR viewName);
Parameters
string is specified as input, then the host name will
Proc.
ProcessId The ID of the process that the event belongs to. If a long
value of zero or less is specified, then it will be
automatically generated by the Event Server In
Proc.
SubSystemName The name of the subsystem that the event belongs BSTR
to, e.g., “Measurement Subsystem A”.
RoleName The name of the role that the event belongs to, e.g., BSTR
“ Spectrum Analyzer”.
ViewName The name of the source that the event belongs to, BSTR
e.g., “Spectrum Analyzer B”.
Return Values

8.1.2.2 Set Info
Description
Set the extra information of the event. SetInfo and GetInfo are intentionally not made into properties
because of problems related to SAFEARRAYs in Visual Basic.
HRESULT SetInfo([in, unique] SAFEARRAY(BSTR) * infos);
Parameters

Infos The “infos” parameter specifies extra information of SAFEARRAY(
the event. If the “description” contains one or more BSTR) *
“%s” strings, the FormatEventEntry method in
IIviEventEntry, attempts to insert the array of extra
information at those locations. Otherwise, the
“infos” is simply appended at the end of the
description. This parameter can be NULL or empty
which means there is no extra information carried
with this event.
Return Values

8.1.2.3 Get Info
Description
Get the extra information carried with an event entry. SetInfo and GetInfo are intentionally not made into
properties because of problems related to SAFEARRAYs in Visual Basic.
HRESULT GetInfo([out, retval] SAFEARRAY(BSTR) * infos);
Parameters
Infos See SetInfo. [out, retval]
SAFEARRAY(
BSTR) *
Return Values

8.1.2.4 Format Event Entry
Description
This function returns the event as a formatted text string. The string will include all the information carried
with the event entry.
HRESULT FormatEventEntry([out, retval] BSTR * formatted);
Parameters
formatted The returned formatted string. [out, retval]
BSTR *
Return Values

9. IVI Event Server Attribute Value Definitions
This section specifies the actual value for each defined attribute value.
Event Type
Property: EventType
Value Name Identifier Actual Value

Status Type IviEventServerStatus 0x10000000
Event Type IviEventServerEvent 0x20000000
Warning Type IviEventServerWarning 0x40000000
Error Type IviEventServerError 0x80000000
Debug Type IviEventServerDebug 0x08000000
Select Code
Property: SelectCode
Most bits of the Select Code are reserved for future use. Currently it is defined the same as for the Event
Type Property.

10. IVI Event Server Function Parameter Value Definitions
This section specifies the actual values for each function parameter that defines values.
Connect Source
Parameter: Latency
Value Name Identifier Actual

Value
Low Latency IviEventServerLatencyLow 1
Medium Latency IviEventServerLatencyMedium 2
High Latency IviEventServerLatencyHigh 3
GetEventSourceInfo
Parameter: Latency
The same as defined for the Latency parameter of Connect Source function.
ChangeMySourceEventLevel
Parameter: LevelVector
Value Name Identifier Actual

Value
Status Level IviEventServerLevelVectorStatus 0x0001
Event Level IviEventServerLevelVectorEvent 0x0002
Warning Level IviEventServerLevelVectorWarning 0x0004
Error Level IviEventServerLevelVectorError 0x0008
Debug Level IviEventServerLevelVectorDebug 0x0010
One would turn on the appropriate bit to indicate sending certain level of events. For example, "send
everything except debug events" would be 0x000F (i.e., 0x0001 | 0x0002 | 0x0004 | 0x0008); "Send
everything" would be 0x001F (i.e., 0x0001 | 0x0002 | 0x0004 | 0x0008 | 0x0010); "Send nothing" would be
0x0000.
Event Level Changed

Parameter: LevelVector
The same as defined for the LevelVector parameter of ChangeMySourceEventLevel function.

11. Sample Use Scenario
Sink Client Sink & Source Client Source Client
Measurement Measurement
GUI Event Server In Proc
Server Specific RCM
ConnectSink
ConnectSink
ConnectSource
ConnectSource
SendEvent
EventCallbackFast
SendEvent
EventCallbackFast
DisconnectSource
DisconnectSink
DisconnectSource
DisconnectSink
Figure 11-1 – IVI Event Server Use Scenario

12. Client Requirements
The threading models of all Event Server components, Event Server In Proc, Event Entry, and Event Server
are “Both”. To maximize performances, the Event Server components are initialized in the Free-Threaded
COM apartment.
12.1 Source Client
To be a source client of the Event Server, the client does not need to be a COM component unless it wishes
to implement the IIviEventSource interface to receive event level change notifications. Currently, any
Win32 applications accepting OLE automation data types can call the IIviEventServer interface functions
to connect to the Event Server and send events.
If the source client does implement the IiviEventSource interface and connects to the Event Source with a
reference to this interface, the source client shall place the DisconnectSource call in a separate method that
will be called before FinalRelease. This will allow the Event Server to release its reference on the source.
12.2 Sink Client
To be a sink client of the Event Server, the client shall be a COM component that implements either the
IIviEventCallback or the IIviEventCallbackFast interface.
The sink client shall place the DisconnectSink call in a separate method that will be called before its
FinalRelease. This rule allows the Event Server to release its reference on the sink.

13. Limitations
13.1 Distributed Systems
Distributed machines are not supported in this release of Event Server. Adding this support will introduce
new issues like DCOM security and system configuration.

Appendix A: IDL file
// IviEventServerDLL.idl : IDL source for IviEventServerDLL.dll
// Copyright: (c) 1999, Agilent Technologies, All rights reserved.
// Copyright: (c) 2001, IVI Foundation, All rights reserved.
// Author: Qi Gao
//
// This file will be processed by the MIDL tool to
// produce the type library (IviEventServerDLL.tlb) and marshalling code.
import "oaidl.idl";
import "ocidl.idl";
typedef
[
public,
v1_enum,
HELP_EVENT_SERVER(LATENCY_ENUM)
]
enum IviEventServerLatencyEnum
{
IviEventServerLatencyLow = 1,
IviEventServerLatencyMedium = 2,
IviEventServerLatencyHigh = 3
} IviEventServerLatencyEnum;
typedef
[
public,
v1_enum,
HELP_EVENT_SERVER(LEVELVECTOR_ENUM)
]
enum IviEventServerLevelVectorEnum
{
IviEventServerLevelVectorStatus = 0x00000001,
IviEventServerLevelVectorEvent = 0x00000002,
IviEventServerLevelVectorWarning = 0x00000004,
IviEventServerLevelVectorError = 0x00000008,
IviEventServerLevelVectorDebug = 0x00000010
} IviEventServerLevelVectorEnum;
typedef
[
public,
v1_enum,
HELP_EVENT_SERVER(EVENTTYPE_ENUM)
]
enum IviEventServerEventTypeEnum
{
IviEventServerEventTypeStatus = 0x10000000,
IviEventServerEventTypeEvent = 0x20000000,
IviEventServerEventTypeWarning = 0x40000000,
IviEventServerEventTypeError = 0x80000000,
IviEventServerEventTypeDebug = 0x08000000
} IviEventServerEventTypeEnum;

[
object,
uuid(D43333AB-2BC0-11d2-B0D9-0060B01A08CB),
helpstring("IIviEventEntry Interface"),
pointer_default(unique)
]
interface IIviEventEntry : IUnknown
{
[propput, helpstring(“property SetTimeStamp”)]
HRESULT TimeStamp(DATE timestamp);
[propget, helpstring(“property GetTimeStamp”)]
HRESULT TimeStamp([out, retval] DATE * timestamp);
[propput, helpstring(“property SetNanoseconds”)]

HRESULT Nanoseconds (long nanoseconds);
[propget, helpstring(“property GetNanoseconds”)]
HRESULT Nanoseconds ([out, retval] long * nanoseconds);
[propput, helpstring(“property SetDescription)]

HRESULT Description (BSTR description);
[propget, helpstring(“property GetDescription”)]
HRESULT Description ([out, retval] BSTR * description);
[propput, helpstring(“property SetSelectCode”)]

HRESULT SelectCode (long SelectCode);
[propget, helpstring(“property GetSelectCode”)]
HRESULT SelectCode ([out, retval] long * SelectCode);
[propput, helpstring(“property SetEventCode”)]

HRESULT EventCode (long EventCode);
[propget, helpstring(“property GetEventCode”)]
HRESULT EventCode ([out, retval] long * EventCode);
[propput, helpstring(“property SetEventType”)]

HRESULT EventType(IviEventServerEventTypeEnum eventType);
[propget, helpstring(“property GetEventType”)]
HRESULT EventType([out, retval] IviEventServerEventTypeEnum *
eventType);
[propput, helpstring(“property SetHostName”)]

HRESULT HostName(BSTR HostName);
[propget, helpstring(“property GetHostName”)]
HRESULT HostName([out, retval] BSTR * HostName);
[propput, helpstring(“property SetProcessId”)]

HRESULT ProcessId (long ProcessId);
[propget, helpstring(“property Get ProcessId”)]
HRESULT ProcessId ([out, retval] long * ProcessId);
[propput, helpstring(“property SetSubsystemName”)]

HRESULT SubsystemName (BSTR SubsystemName);
[propget, helpstring(“property GetHostName”)]
HRESULT SubsystemName ([out, retval] BSTR * SubsystemName);
[propput, helpstring(“property SetRoleName”)]

HRESULT RoleName (BSTR RoleName);
[propget, helpstring(“property GetRoleName”)]
HRESULT RoleName ([out, retval] BSTR * RoleName);
[propput, helpstring(“property SetViewName”)]

HRESULT ViewName (BSTR ViewName);
[propget, helpstring(“property GetViewName”)]
HRESULT ViewName ([out, retval] BSTR * ViewName);
[helpstring("method ConfigureLocation")]
HRESULT ConfigureLocation(BSTR hostName, long processId,
BSTR subSystemName,BSTR roleName,
BSTR viewName);
[helpstring("method SetInfo")]
HRESULT SetInfo([in, unique] SAFEARRAY(BSTR) * infos);

[helpstring("method GetInfo")]
HRESULT GetInfo([out, retval] SAFEARRAY(BSTR) * infos);
[helpstring("method FormatEventEntry")]
HRESULT FormatEventEntry([out, retval] BSTR * formatted);
}
[
object,
uuid(21442235-1FDD-11d2-B0C8-0060B01A08CB),
helpstring("IIviEventCallback Interface"),
]
interface IIviEventCallback : IUnknown
{
[helpstring("method EventCallback")]
HRESULT EventCallback([in] IIviEventEntry * EventEntry);
};
[
object,
uuid(81AF9E1F-35E5-11d2-A614-0060B01A08CB),
helpstring("IIviEventCallbackFast Interface"),
]
interface IIviEventCallbackFast : IUnknown
{
[helpstring("method EventCallbackFast")]
HRESULT EventCallbackFast(long SelectCode,
long EventCode, BSTR description);
};
[
object,
uuid(701F8253-9442-11d2-A62D-0060B01A08CB),
helpstring("IIviEventSource Interface"),
]
interface IIviEventSource : IUnknown
{
[helpstring("method EventLevelChanged")]
HRESULT EventLevelChanged(
BSTR sinkHostName, long sinkProcessId,
BSTR sinkSubSystemName, BSTR sinkRoleName,
BSTR sinkViewName, long levelVector);
};
[
object,
uuid(427B4383-2C92-11D2-98BC-0060B0A3F2B3),
helpstring("IIviEventServer Interface"),
]
interface IIviEventServer : IUnknown
{
[helpstring("method ConnectSource")]
HRESULT ConnectSource(
[in, unique] IIviEventSource * Source,
BSTR SubSystemName,
BSTR RoleName,
BSTR ViewName,
[in, unique] SAFEARRAY(IviEventServerLatencyEnum) *
Latencies,
[in, unique] SAFEARRAY(VARIANT_BOOL) * Logs,
[in, out] long * SourceCookie);
[helpstring("method ConnectSink")]
HRESULT ConnectSink(
[in, unique] IUnknown * IUnkSink,
BSTR SubSystemName, BSTR RoleName,
BSTR ViewName,
[in, unique] SAFEARRAY(IIviEventEntry *) *InterestedEvents,
[in, out] long * SinkCookie);
[helpstring("method DisconnectSource")]
HRESULT DisconnectSource(long SourceCookie);
[helpstring("method DisconnectSink")]
HRESULT DisconnectSink(long SinkCookie);
[helpstring("method SendEvent")]
HRESULT SendEvent(long EventCode, BSTR Description,
long SourceCookie);
[helpstring("method SendEventEx")]
HRESULT SendEventEx(long SelectCode, long EventCode,
BSTR description, [in, unique] SAFEARRAY(BSTR) * Infos,
long SourceCookie);
[helpstring("method GetNextEvent")]
HRESULT GetNextEvent([in, out] long * EID,
[helpstring("method GetPreviousEvent")]
HRESULT GetPreviousEvent([in, out] long * EID,
[helpstring("method ChangeMySourceEventLevel")]
HRESULT ChangeMySourceEventLevel(
long Cookie,
long LevelVector);
};

[
object,
uuid(CE247C62-4064-11d3-8F3C-0060B0FC9326),
helpstring("IIviEventManager Interface"),
]
interface IIviEventManager : IUnknown
{
[helpstring("method GetEventSourceLocations")]
HRESULT GetEventSourceLocations(
[in, out, unique] SAFEARRAY(long) * SourceCookies
);
[helpstring("method GetEventSinkLocations")]
HRESULT GetEventSinkLocations(
[in, out, unique] SAFEARRAY(long) * SinkCookies
);
[helpstring("method GetEventSourceInfo")]
HRESULT GetEventSourceInfo(
long SourceCookie,
[in, out, unique] SAFEARRAY(IIviEventEntry * ) * Events,
[in, out, unique] SAFEARRAY(IviEventServerLatencyEnum) *
Latencies,
[in, out, unique] SAFEARRAY(VARIANT_BOOL) * Orders,
[in, out, unique] SAFEARRAY(VARIANT_BOOL) * Logs
);
[helpstring("method GetEventSinkInfo")]
HRESULT GetEventSinkInfo(
long SinkCookie,
[in, out, unique] SAFEARRAY(IIviEventEntry *)*
InterestedEvents
);
[helpstring("method SetEventSourceInfo")]
HRESULT SetEventSourceInfo(
long SourceCookie,
[in, unique] SAFEARRAY(IviEventServerLatencyEnum) *
Latencies,
[in, unique] SAFEARRAY(VARIANT_BOOL) * Logs
);
[helpstring("method SetEventSinkInfo")]
HRESULT SetEventSinkInfo(
long SinkCookie,
[in, unique] SAFEARRAY(IIviEventEntry *) * InterestedEvents
);
};
[
uuid(27C46644-3070-11D2-B0D9-0060B01A08CB),
version(1.0),
helpstring("IviEventServerDLL 1.0 Type Library")
]
library IVIEVENTSERVERDLLLib
{
importlib("stdole32.tlb");
importlib("stdole2.tlb");
interface IIviEventCallback;
interface IIviEventCallbackFast;
interface IIviEventSource;
[
uuid(3881DE8C-2702-11D2-98BA-0060B0A3F2B3),
helpstring("IviEventServerDLL Class")
]
coclass IviEventServerDLL
{
[default] interface IIviEventServer;
interface IIviEventManager;
};
[
uuid(8602A19E-2BAF-11D2-B0D9-0060B01A08CB),
helpstring("IviEventEntry Class")
]
coclass IviEventEntry
{
[default] interface IIviEventEntry;
};
};

IVI-3.7 Event Server Spec v1

Uploaded by

Document Information

Original Description:

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

IVI-3.7 Event Server Spec v1

Uploaded by

Copyright:

Available Formats

Interchangeable

IVI-3.7: IVI Event Server Specification

IVI-3.7: IVI Event Server Specification 2 IVI Foundation

2. IVI Event Server Capabilities.........................................................10

4. IVI Event Server In Proc interfaces ...............................................15

IVI Foundation 3 IVI-3.7: IVI Event Server Specification

6. Sink Client Interface ......................................................................36

7. Source Client Interface ..................................................................38

8. IVI Event Entry Interface................................................................39

9. IVI Event Server Attribute Value Definitions ................................54

10. IVI Event Server Function Parameter Value Definitions..............55

11. Sample Use Scenario.....................................................................56

12. Client Requirements ......................................................................57

Appendix A: IDL file ................................................................................59

IVI-3.7: IVI Event Server Specification 4 IVI Foundation

FIGURE 2-1 – IVI EVENT SERVER ARCHITECTURE COMPONENT DIAGRAM 10

IVI Foundation 5 IVI-3.7: IVI Event Server Specification

Table 1-1. Ivi-3.7 Revisions

Revision 0.1 November 2, 2000 Original draft.

IVI-3.7: IVI Event Server Specification 6 IVI Foundation

1.2 IVI Event Server Overview

Two documents are related to this specification.

IVI Foundation 7 IVI-3.7: IVI Event Server Specification

Event An event could be as simple as a numeric code plus an optional

Event Server Event Server serves as a Mediator in the Mediator pattern. 1 It

Sink Client A sink is similar to the Observer in the Observer pattern.1 It

Actor An external entity to the system who in some way participates in

IVI Foundation 9 IVI-3.7: IVI Event Server Specification

2.1 Component Diagram

Figure 2-1 – IVI Event Server Architecture Component Diagram

IVI-3.7: IVI Event Server Specification 10 IVI Foundation

2.2.1 IVI Event Server In Proc

2.2.2 IVI Event Server

2.2.4 IIviEventCallback, IIviEventCallbackFast

A sink client implements either IIviEventCallback or IIviEventCallbackFast interface for receiving

2.2.6 IVI Event Entry, IIviEventEntry

2.3 Capabilities of Major Components

IVI Foundation 11 IVI-3.7: IVI Event Server Specification

2.3.2 IVI Event Server

2.3.3 IVI Event Entry

IVI-3.7: IVI Event Server Specification 12 IVI Foundation

3.1 Nonfunctional Requirements

3.2 Use Cases

3.2.1 Actor: Client wanting to receive events (Sink Client)

3.2.2 Actor: Client wanting to send events (Source Client)

3.2.3 Actor: Client wanting to retrieve the events (Retrieve Client)

IVI Foundation 13 IVI-3.7: IVI Event Server Specification

IVI-3.7: IVI Event Server Specification 14 IVI Foundation

4.1.1 Connect Source

COM Method Prototype

Inputs Description Data Type

HostName The name of the host machine. If NULL or empty BSTR

IVI Foundation 15 IVI-3.7: IVI Event Server Specification

Outputs Description Data Type

Defined Values for Latency

IVI-3.7: IVI Event Server Specification 16 IVI Foundation

Default Event Settings by Event Types

Event Type Latency Logged Sorted

IVI Foundation 17 IVI-3.7: IVI Event Server Specification

COM Method Prototype

Inputs Description Data Type

IVI-3.7: IVI Event Server Specification 18 IVI Foundation

Outputs Description Data Type