314 lines
10 KiB
HTML
314 lines
10 KiB
HTML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
|
|
<title>easyPVA C++ Overview</title>
|
|
<link rel="stylesheet" type="text/css"
|
|
href="http://epics-pvdata.sourceforge.net/base.css" />
|
|
<link rel="stylesheet" type="text/css"
|
|
href="http://epics-pvdata.sourceforge.net/epicsv4.css" />
|
|
<style type="text/css">
|
|
/*<![CDATA[*/
|
|
.about { margin-left: 3em; margin-right: 3em; font-size: .83em}
|
|
table { margin-left: auto; margin-right: auto }
|
|
.diagram { text-align: center; margin: 2.5em 0 }
|
|
body { margin-right: 10% }
|
|
/*]]>*/</style>
|
|
|
|
<!-- Script that generates the Table of Contents -->
|
|
<script type="text/javascript" src="http://epics-pvdata.sourceforge.net/script/tocgen.js"></script>
|
|
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<div class="head">
|
|
<h1>easyPVA C++ Overview</h1>
|
|
|
|
</div> <!-- head -->
|
|
|
|
<div id="toc">
|
|
<h2 class="nocount">Table of Contents</h2>
|
|
</div>
|
|
|
|
<!-- Place what you would like in the Table of Contents, inside the contents div -->
|
|
<div id="contents" class="contents">
|
|
<hr />
|
|
|
|
<h2>Introduction</h2>
|
|
|
|
<p>EasyPVA is a synchronous API for accessing PVData via PVAccess.
|
|
It also provides a number of convience methods.
|
|
It allows the client to request access without checking for failure,
|
|
but throws an exception when a reuest fails.
|
|
A client can also check for failues and thus prevent failures.</p>
|
|
|
|
<p>The EasyPVA API has the following features:</p>
|
|
<ol>
|
|
<li>Provides a synchronous API rather than the callback API provided by pvAccess.</li>
|
|
<li>Makes common requests easy.</li>
|
|
<li>Provides full access to the pvAccess API for more demanding
|
|
applications</li>
|
|
<li>Allows efficient client side programs.</li>
|
|
<li>Takes care of most object resource management problems.</li>
|
|
</ol>
|
|
<p>Simple examples of using easyPVA:</p>
|
|
<pre>
|
|
// easyGet
|
|
EasyPVAPtr easyPVA = EasyPVA::create();
|
|
double value = easyPVA->channel("exampleDouble")->get()->getData()->getDouble();
|
|
|
|
// easyPut
|
|
EasyChannelPtr channel = easyPVA->channel("exampleDouble");
|
|
EasyPutPtr put = channel->put();
|
|
EasyPutDataPtr putData = put->getData();
|
|
putData->putDouble(3.0); put->put();
|
|
|
|
// easyMonitor
|
|
EasyMonitorPtr monitor = easyPVA->channel("examplePowerSupply")->monitor("");
|
|
EasyMonitorDataPtr easyData = monitor->getData();
|
|
while(true) {
|
|
monitor->waitEvent();
|
|
cout << "changed\n";
|
|
easyData->showChanged(cout);
|
|
cout << "overrun\n";
|
|
easyData->showOverrun(cout);
|
|
monitor->releaseEvent();
|
|
}
|
|
|
|
// easyProcess
|
|
EasyChannelPtr channel = easyPVA->channel("exampleDouble");
|
|
EasyProcessPtr process = channel->createProcess();
|
|
process->process();
|
|
|
|
</pre>
|
|
|
|
<h2>EasyPVA</h2>
|
|
<p>An instance of EasyPVA is obtained via the call:</p>
|
|
<pre>
|
|
EasyPVAPtr easyPVA = EasyPVA::create();
|
|
</pre>
|
|
|
|
<p>EasyPVA has methods to create instances of <b>EasyChannel</b>.
|
|
The client can specify the provider name or use the default provider.
|
|
The client can manage it's own channels or can let easyPVA cache channels.
|
|
An example of using the cache method is:</p>
|
|
<pre>
|
|
string channelName("exampleDouble");
|
|
EasyChannelPtr easyChannel = easyPVA->channel(channelName);
|
|
</pre>
|
|
<p>This will attempt to connect to channel exampleDouble.
|
|
Since the client did not specify a timeout an exception wll be thrown if
|
|
the connection request fails.
|
|
The client will block until the connection is made or an exception is thrown.
|
|
If the request succeeds, easyPVA caches the easyChannel so that if the
|
|
client makes another request for the same channel the cached object is
|
|
returned to the client.
|
|
</p>
|
|
<p>An example of using a non cached method is:</p>
|
|
<pre>
|
|
string channelName("exampleDouble");
|
|
EasyChannelPtr easyChannel = easyPVA->createChannel(channelName);
|
|
</pre>
|
|
<p>This will create an EasyChannel and return it to the client.
|
|
The client must itself connect.
|
|
This is useful if the client wants to connect to multiple channels in parallel.
|
|
</p>
|
|
|
|
<h2>EasyChannel - Wrapper For Single Channel</h2>
|
|
<h3>EasyChannel</h3>
|
|
<p>This provides methods for connecting to a channel and for creating instances of
|
|
EasyField, EasyProcess, ..., EasyRPC.</p>
|
|
<p>Connection must be made before any create method is called or
|
|
an exception is raised.
|
|
The following is a synchronous connection request:</p>
|
|
<pre>
|
|
easyChannel->connect(5.0); // BLOCKS AND THROWS IF NO CONNECT
|
|
</pre>
|
|
<p>This blocks until then connection is made or until timout occurs.
|
|
An exception is raised if the connection request fails.
|
|
</p>
|
|
<p>The same request can be made without blocking and without exceptions.</p>
|
|
<pre>
|
|
easyChannel->issueConnect(); // DOES NOT BLOCK
|
|
.....
|
|
Status status =easyChannel->waitConnect(5.0); // BLOCKS DOES NOT THROW
|
|
if(!status.isOK()) {
|
|
// failure do something
|
|
}
|
|
</pre>
|
|
<p>Once the channel is connected other Easy objects can be created.
|
|
For example:</p>
|
|
<pre>
|
|
EasyGetPtr easyGet = easyChannel->get(); // DOES BLOCK
|
|
</pre>
|
|
<p>This is a caching request.
|
|
If the client already has made an identical request the client will receive the
|
|
cached object.
|
|
If a new easyGet is created than it is connected before it is returned to the client.
|
|
</p>
|
|
<p>The client can also managed it's own objects:</p>
|
|
<pre>
|
|
EasyGetPtr easyGet = easyChannel->createGet(); // DOES NOT BLOCK
|
|
</pre>
|
|
<p>The client must connect the easyGet.</p>
|
|
|
|
<h3>EasyGetData</h3>
|
|
<p>This provides the data returned by easyGet and easyPutGet.
|
|
It is obtained via:</p>
|
|
<pre>
|
|
EasyGetDataPtr easyData = easyGet->getData();
|
|
</pre>
|
|
<p>It provides methods to get everything returned by channelGet.
|
|
In addition there are methods that make it easier to handle a value
|
|
field that is a scalar or a scalarArray.
|
|
Also for a scalar that is a double or a scalarArray with element type double.
|
|
</p>
|
|
<p>An example is:</p>
|
|
<pre>
|
|
double value = easyData->getDouble();
|
|
</pre>
|
|
<p>It also keeps a bitSet showing which fields have changed since the last channelGet or channelPutGet.</p>
|
|
|
|
<h3>EasyMonitorData</h3>
|
|
<p>To the client this looks identical to EasyGetData except that
|
|
it provides two BitSets: changedBitSet and overrrunBitSet.
|
|
It is used by easyMonitor.
|
|
</p>
|
|
<h3>EasyPutData</h3>
|
|
<p>This is used to provided data for easyPut and easyPutGet.
|
|
It has many of the same methods as easyGetData.
|
|
It does not have a bitSet.
|
|
It also has put methods like:</p>
|
|
<pre>
|
|
void easyData->putDouble(5.0);
|
|
</pre>
|
|
<h3>EasyGet</h3>
|
|
<p>This provides methods to connect to channelGet and to issue get request.
|
|
To connect via a single synchronous call:</p>
|
|
<pre>
|
|
eastGet->connect(); // BLOCKS AND CAN THROW
|
|
</pre>
|
|
<p>This can also be done in two steps:</p>
|
|
<pre>
|
|
easyGet->issueConnect(); // DOES NOT BLOCK
|
|
...
|
|
Status status = easyGet->waitConnect(); // BLOCKS AND DOES NOT HROW
|
|
</pre>
|
|
<p>Once connected gets are issued via either:</p>
|
|
<pre>
|
|
void easyGet->get(); // BLOCKS AND CAN THROW
|
|
</pre>
|
|
or
|
|
<pre>
|
|
easyGet->issueGet(); // DOES NOT BLOCK
|
|
...
|
|
Status status = easyGet->waitGet(); // BLOCKS AND DOES NOT THROW
|
|
</pre>
|
|
<h3>EasyPut</h3>
|
|
<p>This is similar to easyGet except that it wraps channelPut instead of channelGet.
|
|
</p>
|
|
<p>Once connected puts are issued via either:</p>
|
|
<pre>
|
|
void easyPut->put(); // BLOCKS AND CAN THROW
|
|
</pre>
|
|
or
|
|
<pre>
|
|
easyPut->issuePut(); // DOES NOT BLOCK
|
|
...
|
|
Status status = easyPut->waitPut(); // BLOCKS AND DOES NOT THROW
|
|
</pre>
|
|
<h3>EasyMonitor</h3>
|
|
<p>Connecting is similar to easyGet and easyPut.
|
|
The other methods are:</p>
|
|
<dl>
|
|
<dt>start</dt>
|
|
<dd>Starts monitoring</dd>
|
|
<dt>stop</dt>
|
|
<dd>Stops monitoring</dd>
|
|
<dt>poll</dt>
|
|
<dd>polls for a monitorEvent.
|
|
The data is avalable via easyMonitorData.
|
|
</dd>
|
|
<dt>releaseEvent</dt>
|
|
<dd>Release the data from the last poll.
|
|
Note that this must be called before another poll is requested.
|
|
</dd>
|
|
<dt>waitEvent</dt>
|
|
<dd>Block until a monitorEvent is available.
|
|
If true is returned a poll has already been issued.
|
|
</dd>
|
|
<dt>setRequester</dt>
|
|
<dd>A client callback is registered to receive notice of monitorEvents.</dd>
|
|
</dl>
|
|
<h3>EasyProcess</h3>
|
|
<p>Connecting is similar to easyGet.
|
|
It has methods:</p>
|
|
<dl>
|
|
<dt>process</dt>
|
|
<dd>call issueProcess and waitProcess.</dd>
|
|
<dt>issueProcess</dt>
|
|
<dd>call channelProcess->process() and return immediately.
|
|
</dd>
|
|
<dt>waitProcess</dt>
|
|
<dd>Wait for process to complete.</dd>
|
|
</dl>
|
|
<h3>EasyPutGet</h3>
|
|
<p>Connecting is similar to easyGet.
|
|
It has methods:</p>
|
|
<dl>
|
|
<dt>putGet</dt>
|
|
<dd>calls issuePutGet and waitPutGet.
|
|
throws an exception if not successfull.
|
|
</dd>
|
|
<dt>issuePutGet</dt>
|
|
<dd>
|
|
Calls channel->putGet() and returns.
|
|
</dd>
|
|
<dt>waitPutGet</dt>
|
|
<dd>
|
|
Waits until putGet completes and returns status.
|
|
</dd>
|
|
<dt>getGet,issueGetGet, and waitGetGet</dt>
|
|
<dd>Gets the data for the get part of channelPutGet.</dd>
|
|
<dt>getPut,issueGetPut,and waitGetPut</dt>
|
|
<dd>Gets the data for the put part of channelPutGet.</dd>
|
|
<dt>getPutData</dt>
|
|
<dd>
|
|
Returns the EasyData for the put part of channelPutGet.
|
|
</dd>
|
|
<dt>getGetData</dt>
|
|
<dd>
|
|
Returns the EasyData for the get part of channelPutGet.
|
|
</dd>
|
|
</dl>
|
|
<p>Look at javaDoc for details.</p>
|
|
|
|
<h2>EasyMultiChannel - Wrapper For Multiple Channels</h2>
|
|
<h3>EasyMultiChannel</h3>
|
|
<p>This provides methods for connecting to multiple channels.
|
|
For now clients has no reason to use this directly.
|
|
Instead they will use it via EasyMultiDouble or EasyNTMultiChannel.
|
|
</p>
|
|
<h3>EasyMultiDouble</h3>
|
|
<p>This provides support for gets and puts to the value field of multiple channels.
|
|
Each channel must have a value field that is a numeric scalar.
|
|
The client always sees that data as a PVDoubleArray.
|
|
All channels must connect.
|
|
If any problems occur an exception is thrown.
|
|
</p>
|
|
<h3>EasyNTMultiChannel</h3>
|
|
<p>This provides support for gets and puts to the value field of multiple channels.
|
|
Each channel must have a value field.
|
|
The client always sees that data as a NTMultiChannel, which is one
|
|
of the types provided by normativeTypesCPP.
|
|
All channels must connect.
|
|
If any problems occur an exception is thrown.
|
|
</p>
|
|
|
|
</div> <!-- class="contents" -->
|
|
</body>
|
|
</html>
|