EPICS_base/pvaClient
0
0
Fork 0
Code Issues Pull Requests Projects Wiki Activity

doxygen changes

Browse Source
This commit is contained in:
mrkraimer
2017-07-12 06:11:29 -04:00
parent 609c887c19
commit 8c7506449b
16 changed files with 509 additions and 221 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
README.md
View File

@ -21,29 +21,3 @@ It can also be built by:
edit configure/RELEASE.local
make
Examples
------------
Project exampleCPP has examples for pvaClientCPP
Status
------
* The API is for EPICS Version 4 release 4.6.0
* Everything defined in pvaClient.h is ready but see below for remaining work.
* Everything defined in pvaClientMultiChannel.h is ready but see below for remaining work.
pvaClientChannel
---------------
Channel::getField and channelArray are not supported for release 4.6
pvaClientMultiChannel
---------------
For release 4.5 support is available for multiDouble and NTMultiChannel.
In the future additional support should be provided that at least includes NTScalarMultiChannel.
Testing with some channels not connected has not been done.

15
documentation/RELEASE_NOTES.md
View File

@ -1,6 +1,16 @@
EPICS V4 release 4.7
====================
Works with release/7.0 of pvDataCPP and release/6.0 of pvAccessCPP
------------------------------------------------------------------
Will not work with older versions.
destroy methods removed
-----------------------
All the destroy methods are removed since implementation is RAII compliant.s
API changes to PvaClientMonitor
-------------------------------
@ -31,11 +41,6 @@ A new method is also implemented
PvaClientMonitorRequesterPtr const & monitorRequester
);
Works with release/6.0 of pvAccessCPP
--------------------------------------
Not sure this will work with older versions of pvAccessCPP.
EPICS V4 release 4.6
====================

23
documentation/htmldoxygen/pvaClient.html
View File

@ -117,6 +117,29 @@ This method is just creates a new PvaClientChannel and returns it to the caller.
The caller must call the PvaClientChannel connect methods.
</p>
<h2>Blocking vs Non-Blocking Methods</h2>
<p>Each component of pvaClient provides a set of blocking and non-blocking calls.
For example several components (examples are <b>PvaClientChannel</b> and <b>PvaChannelGet</b>)
have methods:</p>
<dl>
<dt>connect</dt>
<dd>
This calls issueConnect and then waitConnect.
If waitConnect fails an exception is thrown.
Since waitConnect is a blocking method so is this.
</dd>
<dt>issueConnect</dt>
<dd>
This is a request to connect, i. e. issue a request to the server to create something
on the server. This is a non blocking call.
</dd>
<dt>waitConnect</dt>
<dd>
This waits for the server to respond to issueConnect.
It blocks until the server responds or a timeout occurs.
</dd>
</dl>
</body>
</html>

81
documentation/htmldoxygen/pvaClientChannel.html
View File

@ -35,9 +35,88 @@
<h1>PvaClientChannel</h1>
<h2>Overview</h2>
<p>
<b>Not Yet Written</b>
pvaClientChannel is a synchronous wrapper for the pvAccess::Channel API, which is a callback based API.
Thus it is easier to use than pvAccess::Channel itself.
</p>
<p>An instance of <b>PvaClientChannel</b> connects to a single channel.
An instance can only be created via class <b>PvaClient</b> which has both synchronous methods, which block, and non blocking methods.
The synchrouous methods block until a connection is made to the channel and throw an exception if a
timeout occurs while trying to make a connection.
The non blocking methods leave connection to the caller.
</p>
<p><b>PvaClientChannel</b> has methods:</p>
<dl>
<dt>Connect to channel</dt>
<dd>These can be called indirectly by a blocking request to <b>PvaClient</b>
or by the client if a non blocking request is made to <b>PvaClient</b>.
</dd>
<dt>Channel state change requester</dt>
<dd>The client can provide a callback that is called each time the connection state
of the channel changes.
</dd>
<dt>Creating all of the following</dt>
<dd>
<pre>
PvaClientField NOT IMPLEMENTED
PvaClientProcess
PvaClientGet
PvaClientPut
PvaClientPutGet
PvaClientMonitor
PvaClientArray NOT IMPLEMENTED
PvaClientRPC
</pre>
</dd>
</dl>
<h2>Connect: Blocking vs Non-Blocking </h2>
<p><b>PvaClientChannel</b> has methods:</p>
<dl>
<dt>connect</dt>
<dd>
This calls issueConnect and then waitConnect.
If waitConnect fails an exception is thrown.
Since waitConnect is a blocking method so is this.
</dd>
<dt>issueConnect</dt>
<dd>
This is a request to connect to the channel. This is a non blocking call.
</dd>
<dt>waitConnect</dt>
<dd>
This waits for the server to respond to issueConnect.
It blocks until the server responds or a timeout occurs.
</dd>
</dl>
<h2>Get and Put Caching</h2>
<p>
<b>PvaClientChannel</b> has methods:
</p>
<pre>
PvaClientGetPtr get(std::string const &amp; request);
PvaClientPutPtr put(std::string const &amp; request);
</pre>
<p>
Each of these caches.
For example all calls to <b>get</b> with the same <b>request</b> will share the same
<b>PvaChannelGet</b>
</p>
<p>
For example consider a client that makes multiple calls like:
</p>
<pre>
double value;
value = pva->channel(channelName)->get()->getData()->getDouble();
...
value = pva->channel(channelName)->get()->getData()->getDouble();
</pre>
<p>
Only the first call creates a new PvaClientChannel and a new PvaClientGet.
The second call reuses the cached PvaClientChannel and PvaClientGet.
</p>
</body>
</html>

44
documentation/htmldoxygen/pvaClientChannelProcess.html
View File

@ -1,44 +0,0 @@
<?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>PvaClientProcess</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 }
span.opt { color: grey }
span.nterm { font-style:italic }
span.term { font-family:courier }
span.user { font-family:courier }
span.user:before { content:"<" }
span.user:after { content:">" }
.nonnorm { font-style:italic }
p.ed { color: #AA0000 }
span.ed { color: #AA0000 }
p.ed.priv { display: inline; }
span.ed.priv { display: inline; }
/*]]>*/</style>
<!-- Script that generates the Table of Contents -->
<script type="text/javascript"
src="http://epics-pvdata.sourceforge.net/script/tocgen.js">
</script>
</head>
<body>
<h1>PvaClientProcess</h1>
<p>
<b>Not Yet Written</b>
</p>
</body>
</html>

44
documentation/htmldoxygen/pvaClientChannelPut.html
View File

@ -1,44 +0,0 @@
<?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>PvaClientChannelPut</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 }
span.opt { color: grey }
span.nterm { font-style:italic }
span.term { font-family:courier }
span.user { font-family:courier }
span.user:before { content:"<" }
span.user:after { content:">" }
.nonnorm { font-style:italic }
p.ed { color: #AA0000 }
span.ed { color: #AA0000 }
p.ed.priv { display: inline; }
span.ed.priv { display: inline; }
/*]]>*/</style>
<!-- Script that generates the Table of Contents -->
<script type="text/javascript"
src="http://epics-pvdata.sourceforge.net/script/tocgen.js">
</script>
</head>
<body>
<h1>PvaClientChannelPut</h1>
<p>
<b>Not Yet Written</b>
</p>
</body>
</html>

44
documentation/htmldoxygen/pvaClientChannelPutGet.html
View File

@ -1,44 +0,0 @@
<?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>PvaClientPutGet</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 }
span.opt { color: grey }
span.nterm { font-style:italic }
span.term { font-family:courier }
span.user { font-family:courier }
span.user:before { content:"<" }
span.user:after { content:">" }
.nonnorm { font-style:italic }
p.ed { color: #AA0000 }
span.ed { color: #AA0000 }
p.ed.priv { display: inline; }
span.ed.priv { display: inline; }
/*]]>*/</style>
<!-- Script that generates the Table of Contents -->
<script type="text/javascript"
src="http://epics-pvdata.sourceforge.net/script/tocgen.js">
</script>
</head>
<body>
<h1>PvaClientPutGet</h1>
<p>
<b>Not Yet Written</b>
</p>
</body>
</html>

41
documentation/htmldoxygen/pvaClientChannelStateChangeRequester.html
View File

@ -35,9 +35,46 @@
<h1>PvaClientChannelStateChangeRequester</h1>
<p>
<b>Not Yet Written</b>
<p>This class has the single method <b>channelStateChange</b>.
It is called each time the channel connection status changes.
</p>
<p>
<b>NOTE:</b>
The implementation must not call a method that blocks waiting for a response from the server.
It it does the client may be blocked forever.
</p>
<p>
An example of illegal code is:
</p>
<pre>
virtual void channelStateChange(PvaClientChannelPtr const & channel, bool isConnected)
{
if(isConnected&&!pvaClientPut)
{
pvaClientPut = pvaClientChannel->createPut(request);
pvaClientPut->connect();
}
}
</pre>
<p>
This is illegal because the call to <b>connect</b> blocks.
</p>
<p>The following is an example of legal code:
</p>
<pre>
virtual void channelStateChange(PvaClientChannelPtr const & channel, bool isConnected)
{
if(isConnected&&!pvaClientPut)
{
pvaClientPut = pvaClientChannel->createPut(request);
pvaClientPut->issueConnect();
}
}
</pre>
<p>This is legal code because neither <b>createPut</b> or <b>issueConnect</b>
blocks.
</p>
</body>
</html>

32
documentation/htmldoxygen/pvaClientChannelGet.html → documentation/htmldoxygen/pvaClientGet.html
View File

@ -35,8 +35,38 @@
<h1>PvaClientGet</h1>
<p>
<b>Not Yet Written</b>
pvaClientGet is a synchronous wrapper for the pvAccess::ChannelGet API, which is a callback based API.
Thus it is easier to use than pvAccess::ChannelGet itself.
</p>
<p>An instance of PvaClientGet is created via a call to one of the followimg:</p>
<pre>
class PvaClientChannel
...
{
...
PvaClientGetPtr get(std::string const & request = "field(value,alarm,timeStamp)");
PvaClientGetPtr createGet(std::string const & request = "");
PvaClientGetPtr createGet(epics::pvData::PVStructurePtr const & pvRequest);
...
};
<p>An instance of <b>PvaClientGet/b> connects to a single channel.
<b>PvaClientGet</b> has both synchronous methods, which block, and non blocking methods.
</p>
<p><b>PvaClientChannel</b> has methods:</p>
<pre>
connect Calls issueConnect and then waitConnect.
issueConnect issues a request to the server to create the server side of ChannelPut.
waitConnect blocks until server responds that it has created the ChannelPut.
get Calls issueGet and then waitGet.
issueGet issues a get request to the server.
waitGet waits until the server send a message that the get is complete.
getData get the data.
</pre>
<p>
Note that <b>issueConnect</b> and <b>issueGet</b> do not block but all other methods
do block.
</p>
</body>

25
documentation/htmldoxygen/pvaClientGetData.html
View File

@ -35,9 +35,28 @@
<h1>PvaClientGetData</h1>
<p>
<b>Not Yet Written</b>
</p>
<p>This class provides access to the data returned by calls to get data via <b>PvaChannelGet</b>
It provides methods:</p>
<pre>
getStructure Get the introspection interface for data returned from server
getPVStructure Get the complete set of data returned from the server.
getChangedBitSet Get the bitSet that shows which fields have a new value since last get.
showChanged Show all the fields that have changed value since the last get,
getAlarm If a alarm field is available get it.
getTimeStamp If a timeStamp field is available get it.
hasValue Does the PVStructure have a top level field named value
NOTE: The following only apply it hasValue is true.
isValueScalar Is the value field a scalar?
isValueScalarArray Is the value field a scalar array?
getValue Get the value field.
getScalarValue Get a scalar value field.
getArrayValue Get an array value field.
getScalarArrayValue Get a scalar array value field.
getDouble Get scalar value field as a double.
getString Get value field as a string.
getDoubleArray Get value field as a double array.
getStringArray Get value field as a string array.
</pre>
</body>
</html>

32
documentation/htmldoxygen/pvaClientMonitorData.html
View File

@ -4,7 +4,7 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>PvaClientMonitotData</title>
<title>PvaClientMonitorData</title>
<link rel="stylesheet" type="text/css"
href="http://epics-pvdata.sourceforge.net/base.css" />
<link rel="stylesheet" type="text/css"
@ -33,11 +33,33 @@
</head>
<body>
<h1>PvaClientMonitotData</h1>
<h1>PvaClientMonitorData</h1>
<p>
<b>Not Yet Written</b>
</p>
<p>This class provides access to the data returned by calls to get data via <b>PvaChannelGet</b>
It provides methods:</p>
<pre>
getStructure Get the introspection interface for data returned from server
getPVStructure Get the complete set of data returned from the server.
getChangedBitSet Get the bitSet that shows which fields have a new value since last monitor event.
getOverrunBitSet Get the bitSet that shows which fields have changed more than once since last monitor event.
showChanged Show all the fields that have changed value since the last monitor event,
showChanged Show all the fields that have changed value more than once since last monitor event.
getAlarm If a alarm field is available get it.
getTimeStamp If a timeStamp field is available get it.
hasValue Does the PVStructure have a top level field named value
NOTE: The following only apply it hasValue is true.
isValueScalar Is the value field a scalar?
isValueScalarArray Is the value field a scalar array?
getValue Get the value field.
getScalarValue Get a scalar value field.
getArrayValue Get an array value field.
getScalarArrayValue Get a scalar array value field.
getDouble Get scalar value field as a double.
getString Get value field as a string.
getDoubleArray Get value field as a double array.
getStringArray Get value field as a string array.
</pre>
</body>
</html>

29
documentation/htmldoxygen/pvaClientProcess.html
View File

@ -36,7 +36,34 @@
<h1>PvaClientProcess</h1>
<p>
<b>Not Yet Written</b>
pvaClientProcess is a synchronous wrapper for the pvAccess::ChannelProcess API, which is a callback based API.
Thus it is easier to use than pvAccess::ChannelProcess itself.
</p>
<p>An instance of PvaClientProcess is created via a call to one of the followimg:</p>
<pre>
class PvaClientChannel
...
{
...
PvaClientProcessPtr createProcess(std::string const & request = "");
PvaClientProcessPtr createProcess(epics::pvData::PVStructurePtr const & pvRequest);
...
};
<p>An instance of <b>PvaClientProcess/b> connects to a single channel.
<b>PvaClientProcess</b> has both synchronous methods, which block, and non blocking methods.
</p>
<p><b>PvaClientChannel</b> has methods:</p>
<pre>
connect Calls issueConnect and then waitConnect.
issueConnect issues a request to the server to create the server side of ChannelPut.
waitConnect blocks until server responds that it has created the ChannelPut.
process Calls issueProcess and then waitProcess.
issueProcess issues a process request to the server.
waitProcess waits until the server send a message that the process is complete.
</pre>
<p>
Note that <b>issueConnect</b> and <b>issueProcess</b> do not block but all other methods
do block.
</p>
</body>

82
documentation/htmldoxygen/pvaClientPut.html Normal file
View File

@ -0,0 +1,82 @@
<?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>PvaClientChannelPut</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 }
span.opt { color: grey }
span.nterm { font-style:italic }
span.term { font-family:courier }
span.user { font-family:courier }
span.user:before { content:"<" }
span.user:after { content:">" }
.nonnorm { font-style:italic }
p.ed { color: #AA0000 }
span.ed { color: #AA0000 }
p.ed.priv { display: inline; }
span.ed.priv { display: inline; }
/*]]>*/</style>
<!-- Script that generates the Table of Contents -->
<script type="text/javascript"
src="http://epics-pvdata.sourceforge.net/script/tocgen.js">
</script>
</head>
<body>
<h1>PvaClientChannelPut</h1>s
<p>
pvaClientPut is a synchronous wrapper for the pvAccess::ChannelPut API, which is a callback based API.
Thus it is easier to use than pvAccess::ChannelPut itself.
</p>
<p>
<b>NOTE:</b>
Except for union fields pvaClientPut takes care of modifying the bitSet associated with
the data sent to the server.
</p>
<p>An instance of PvaClientPut is created via a call to one of the followimg:</p>
<pre>
class PvaClientChannel
...
{
...
PvaClientPutPtr put(std::string const & request = "field(value,alarm,timeStamp)");
PvaClientPutPtr createPut(std::string const & request = "");
PvaClientPutPtr createPut(epics::pvData::PVStructurePtr const & pvRequest);
...
};
<p>An instance of <b>PvaClientPut/b> connects to a single channel.
<b>PvaClientPut</b> has both synchronous methods, which block, and non blocking methods.
</p>
<p><b>PvaClientPut</b> has methods:</p>
<pre>
connect Calls issueConnect and then waitConnect.
issueConnect issues a request to the server to create the server side of ChannelPut.
waitConnect blocks until server responds that it has created the ChannelPut.
get Calls issueGet and then waitGet.
issueGet issues a request to the server to get the latest data.
waitGet waits until the server send a message that the get is complete.
put Calls issuePut and then waitPut.
issuePut issues a put request to the server.
waitPut waits until the server send a message that the put is complete.
getData get the data.
</pre>
<p>
Note that <b>issueConnect</b>, <b>issueGet</b> and <b>issuePut</b> do not block but all other methods
do block.
</p>
</body>
</html>

33
documentation/htmldoxygen/pvaClientPutData.html
View File

@ -35,10 +35,41 @@
<h1>PvaClientPutData</h1>
<p>This class provides access to data to send to the server via a <b>PvaChannelPut</b>
It is created by <b>PvaChannelPut<b> or <b>PvaChannelPutGet</b>.
This the client only gets access to an instance by getting it from <b>PvaChannelPut<b> or <b>PvaChannelPutGet</b>.
<p>
<b>Not Yet Written</b>
<p>Note also that for all field types except <b>union</b> the <b>BitSet</b> for the data is updated
by <b>PvaChannelPut<b> or <b>PvaChannelPutGet</b> whenever the client changes a field.
For a <b>union</b> or <b>unionArray</b> field the client must update the <b>BitSet</b>.
</p>
<p>
PvaClientPutData provides methods:</p>
<pre>
getStructure Get the introspection interface for data sent to server
getPVStructure Get the complete set of data sent to the server.
getChangedBitSet Get the bitSet that shows which fields have a new value since last get.
showChanged Show all the fields that have changed value since the last get,
getAlarm If a alarm field is available get it.
getTimeStamp If a timeStamp field is available get it.
hasValue Does the PVStructure have a top level field named value
NOTE: The following only apply it hasValue is true.
isValueScalar Is the value field a scalar?
isValueScalarArray Is the value field a scalar array?
getValue Get the value field.
getScalarValue Get a scalar value field.
getArrayValue Get an array value field.
getScalarArrayValue Get a scalar array value field.
getDouble Get scalar value field as a double.
getString Get value field as a string.
getDoubleArray Get value field as a double array.
getStringArray Get value field as a string array.
putDouble Put scalar value field as a double.
putString Put value field as a string.
putDoubleArray Put value field as a double array.
putStringArray Put value field as a string array.
</pre>
</body>
</html>

84
documentation/htmldoxygen/pvaClientPutGet.html Normal file
View File

@ -0,0 +1,84 @@
<?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>PvaClientPutGetGet</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 }
span.opt { color: grey }
span.nterm { font-style:italic }
span.term { font-family:courier }
span.user { font-family:courier }
span.user:before { content:"<" }
span.user:after { content:">" }
.nonnorm { font-style:italic }
p.ed { color: #AA0000 }
span.ed { color: #AA0000 }
p.ed.priv { display: inline; }
span.ed.priv { display: inline; }
/*]]>*/</style>
<!-- Script that generates the Table of Contents -->
<script type="text/javascript"
src="http://epics-pvdata.sourceforge.net/script/tocgen.js">
</script>
</head>
<body>
<h1>PvaClientPutGetGet</h1>
<p>
pvaClientPutGet is a synchronous wrapper for the pvAccess::ChannelPutGet API, which is a callback based API.
Thus it is easier to use than pvAccess::ChannelPut itself.
</p>
<p>
<b>NOTE:</b>
Except for union fields pvaClientPutGet takes care of modifying the bitSet associated with
the data sent to the server.
</p>
<p>An instance of PvaClientPutGet is created via a call to one of the followimg:</p>
<pre>
class PvaClientChannel
...
{
...
PvaClientPutGetPtr createPutGet(std::string const & request);
PvaClientPutGetPtr createPutGet(epics::pvData::PVStructurePtr const & pvRequest);
...
};
<p>An instance of <b>PvaClientPutGet/b> connects to a single channel.
<b>PvaClientPutGet</b> has both synchronous methods, which block, and non blocking methods.
</p>
<p><b>PvaClientPutGet</b> has methods:</p>
<pre>
connect calls issueConnect and then waitConnect.
issueConnect issues a request to the server to create the server side of ChannelPut.
waitConnect blocks until server responds that it has created the ChannelPut.
putGet call issuePutGet and then waitPutGet.
issuePutGet issue a putGet and return immediately.
waitPutGet wait until putGet completes.
getGet calls issueGetGet and then waitGetGet.
issueGetGet issues a request to the server to get the latest data for the get data.
waitGetGet waits until the server send a message that the getGet is complete.
getPut calls issueGetPut and then waitGetPut.
issueGetPut issues a request to the server to get the latest data for the put data.
waitGetPut waits until the server send a message that the getPut is complete.
getPutData get the put portion of the data.
getGetData get the get portion of the data.
</pre>
<p>
Note that <b>issueConnect</b>, <b>issuePutGet</b>, <b>issueGetGet</b> and <b>issueGetPut</b> do not block but all other methods block.
</p>
</body>
</html>

95
src/pv/pvaClient.h
View File

@ -187,7 +187,7 @@ typedef std::tr1::shared_ptr<PvaClientPutCache> PvaClientPutCachePtr;
/**
* @brief A callback for change in connection status.
*
* <a href = "../htmldoxygen/pvaClientChannelStateChangeRequester.html">Overview of PvaClientChannelStateChangeRequester</a
* <a href = "../htmldoxygen/pvaClientChannelStateChangeRequester.html">Overview of PvaClientChannelStateChangeRequester</a>
*
*/
class PvaClientChannelStateChangeRequester
@ -200,6 +200,8 @@ public:
virtual ~PvaClientChannelStateChangeRequester(){}
/**
* @brief A channel connection state change has occurred.
*
* <b>Warning</b> A call to a method that blocks should not be made by this method.
* @param channel The channel.
* @param isConnected The new connection status.
*/
@ -222,12 +224,18 @@ public:
* @brief Destructor
*/
~PvaClientChannel();
/** @brief Set a client stateChangeRequester.
*
* @param stateChangeRequester The client stateChangeRequester implementation.
*/
void setStateChangeRequester(PvaClientChannelStateChangeRequesterPtr const &stateChangeRequester);
/** @brief Get the name of the channel to which PvaClientChannel is connected.
*
* @return The channel name.
*/
std::string getChannelName();
/** @brief Get the the channel to which PvaClientChannel is connected.
*
* @return The channel interface.
*/
epics::pvAccess::Channel::shared_pointer getChannel();
@ -239,50 +247,53 @@ public:
*/
void connect(double timeout=5.0);
/** @brief Issue a connect request and return immediately.
*
*/
void issueConnect();
/** @brief Wait until the connection completes or for timeout.
*
* @param timeout The time in seconds to wait. A value of 0 means forever.
* @return status.
* @throw runtime_error if failure.
*/
epics::pvData::Status waitConnect(double timeout = 5.0);
/** @brief Create a PvaClientField for the specified subField.
*
* @param subField The desired subField, i. e. "field.field...."
* An empty string, i. e. "", asks for the entire top level struture as defined by the server.
* @return The interface.
*/
PvaClientFieldPtr createField(std::string const & subField = "");
/** @brief First call createRequest as implemented by pvDataCPP and then call the next method.
*
* @param request The syntax of request is defined by the copy facility of pvData.
* @return The interface.
* @throw runtime_error if failure.
*/
PvaClientProcessPtr createProcess(std::string const & request = "");
/** Creates an PvaClientProcess.
/** Creates a PvaClientProcess.
*
* @param pvRequest The syntax of pvRequest is defined by the copy facility of pvData.
* @return The interface.
* @throw runtime_error if failure.
*/
PvaClientProcessPtr createProcess(epics::pvData::PVStructurePtr const & pvRequest);
/** @brief Get a cached PvaClientGet or create and connect to a new PvaClientGet.
/** @brief create a PvaChannelGet
*
* If connection can not be made an exception is thrown.
* @param request The syntax of request is defined by the copy facility of pvData.
* Get a cached PvaClientGet or create and connect to a new PvaClientGet.
* @return The interface.
* @throw runtime_error if failure.
*/
PvaClientGetPtr get(std::string const & request = "field(value,alarm,timeStamp)");
/** @brief create a PvaClientGet.
*
* First call createRequest as implemented by pvDataJava and then call the next method.
* Then get a cached PvaClientGet or create and connect to a new PvaClientGet.
* First call createRequest as implemented by pvData and then call the next method.
* @param request The syntax of request is defined by the copy facility of pvData.
* @return The interface.
* @throw runtime_error if failure.
*/
PvaClientGetPtr createGet(std::string const & request = "field(value,alarm,timeStamp)");
/** @brief Creates an PvaClientGet.
*
* @param pvRequest The syntax of pvRequest is defined by the copy facility of pvData.
* @return The interface.
* @throw runtime_error if failure.
@ -290,8 +301,7 @@ public:
PvaClientGetPtr createGet(epics::pvData::PVStructurePtr const & pvRequest);
/** @brief create a PvaClientPut.
*
* First call createRequest as implemented by pvDataJava.
* Then get a cached PvaClientPut or create and connect to a new PvaClientPut.
* Get a cached PvaClientPut or create and connect to a new PvaClientPut.
* Then call it's get method.
* @param request The syntax of request is defined by the copy facility of pvData.
* @return The interface.
@ -307,6 +317,7 @@ public:
*/
PvaClientPutPtr createPut(std::string const & request = "field(value)");
/** @brief Create a PvaClientPut.
*
* @param pvRequest The syntax of pvRequest is defined by the copy facility of pvData.
* @return The interface.
*/
@ -321,6 +332,7 @@ public:
PvaClientPutGetPtr createPutGet(
std::string const & request = "putField(argument)getField(result)");
/** @brief Create a PvaClientPutGet.
*
* @param pvRequest The syntax of pvRequest is defined by the copy facility of pvData.
* @return The interface.
*/
@ -350,6 +362,7 @@ public:
*/
PvaClientMonitorPtr monitor(std::string const & request = "field(value,alarm,timeStamp)");
/** @brief Call the next method with request = "field(value,alarm,timeStamp)"
*
* @param pvaClientMonitorRequester The client callback.
* @return The interface.
* @throw runtime_error if failure.
@ -368,7 +381,8 @@ public:
std::string const & request,
PvaClientMonitorRequesterPtr const & pvaClientMonitorRequester);
/**
* @brief First call createRequest as implemented by pvDataJava and then calls the next method.
* @brief First call createRequest as implemented by pvDataJava and then call the next method.
*
* @param request The syntax of request is defined by the copy facility of pvData.
* @return The interface.
* @throw runtime_error if failure.
@ -377,11 +391,13 @@ public:
std::string const & request = "field(value,alarm,timeStamp)");
/** Create an PvaClientMonitor.
* @param pvRequest The syntax of pvRequest is defined by the copy facility of pvData.
*
* @return The interface.
* @throw runtime_error if failure.
*/
PvaClientMonitorPtr createMonitor(epics::pvData::PVStructurePtr const & pvRequest);
/** @brief Issue a channelRPC request
*
* @param pvRequest The pvRequest that is passed to createRPC.
* @param pvArgument The argument for a request.
* @return The result.
@ -391,6 +407,7 @@ public:
epics::pvData::PVStructurePtr const & pvRequest,
epics::pvData::PVStructurePtr const & pvArgument);
/** @brief Issue a channelRPC request
*
* @param pvArgument The argument for the request.
* @return The result.
* @throw runtime_error if failure.
@ -398,11 +415,13 @@ public:
epics::pvData::PVStructurePtr rpc(
epics::pvData::PVStructurePtr const & pvArgument);
/** @brief Create a PvaClientRPC.
*
* @return The interface.
* @throw runtime_error if failure.
*/
PvaClientRPCPtr createRPC();
/** @brief Create a PvaClientRPC.
*
* @param pvRequest The pvRequest that must have the same interface
* as a pvArgument that is passed to an rpc request.
* @return The interface.
@ -415,10 +434,6 @@ public:
/** @brief Get the number of cached gets and puts.
*/
size_t cacheSize();
/** Deprecated method
* \deprecated This method will go away in future versions.
*/
void destroy() EPICS_DEPRECATED {}
private:
static PvaClientChannelPtr create(
PvaClientPtr const &pvaClient,
@ -477,11 +492,13 @@ public:
*/
void setMessagePrefix(std::string const & value);
/** @brief Get the structure.
*
* @return The Structure
* @throw runtime_error if failure.
*/
epics::pvData::StructureConstPtr getStructure();
/** @brief Get the pvStructure.
*
* @return the pvStructure.
* @throw runtime_error if failure.
*/
@ -494,6 +511,7 @@ public:
*/
epics::pvData::BitSetPtr getChangedBitSet();
/** @brief Show the fields that have changed value since the last get.
*
* @param out The stream that shows the changed fields.
* @return The stream that was passed as out.
*/
@ -610,36 +628,43 @@ public:
*/
~PvaClientPutData() {}
/** @brief Set a prefix for throw messages.
*
* @param value The prefix.
*/
void setMessagePrefix(std::string const & value);
/** @brief Get the structure.
* @return The Structure
* @throw runtime_error if failure.
*/
epics::pvData::StructureConstPtr getStructure();
*
* @return The Structure
* @throw runtime_error if failure.
*/
epics::pvData::StructureConstPtr getStructure();
/** @brief Get the pvStructure.
*
* @return the pvStructure.
* @throw runtime_error if failure.
*/
epics::pvData::PVStructurePtr getPVStructure();
/** @brief Get the changed BitSet for the pvStructure
*
* This shows which fields have changed values.
* @return The bitSet
* @throw runtime_error if failure.
*/
epics::pvData::BitSetPtr getChangedBitSet();
/** @brief Show the fields that have changed values.
*
* @param out The stream that shows the changed fields.
* @return The stream that was passed as out.
*/
std::ostream & showChanged(std::ostream & out);
/**
* @brief Is there a top level field named value.
*
* @return The answer.
*/
bool hasValue();
/** @brief Is the value field a scalar?
*
* @return The answer.
*/
bool isValueScalar();
@ -648,10 +673,12 @@ public:
*/
bool isValueScalarArray();
/** Get the interface to the value field.
*
* @return The interface. an excetion is thrown if a value field does not exist.
*/
epics::pvData::PVFieldPtr getValue();
/** @brief Get the interface to a scalar value field.
*
* @return The interface for a scalar value field.
* @throw runtime_error if failure.
*/
@ -896,7 +923,7 @@ typedef std::tr1::shared_ptr<ChannelProcessRequesterImpl> ChannelProcessRequeste
/**
* @brief An easy to use alternative to ChannelProcess.
*
* <a href = "../htmldoxygen/pvaClientChannelProcess.html">Overview of PvaClientChannelProcess</a>
* <a href = "../htmldoxygen/pvaClientProcess.html">Overview of PvaClientProcess</a>
*/
class epicsShareClass PvaClientProcess
{
@ -936,17 +963,13 @@ public:
* An exception is thrown if get fails.
*/
void process();
/** @brief Issue a process and return immediately.
/** @brief Issue a process request and return immediately.
*/
void issueProcess();
/** @brief Wait until process completes.
* @return status.
*/
epics::pvData::Status waitProcess();
/** Deprecated method
* \deprecated This method will go away in future versions.
*/
void destroy() EPICS_DEPRECATED {}
private:
std::string getRequesterName();
void message(std::string const & message,epics::pvData::MessageType messageType);
@ -990,7 +1013,7 @@ typedef std::tr1::shared_ptr<ChannelGetRequesterImpl> ChannelGetRequesterImplPtr
/**
* @brief An easy to use alternative to ChannelGet.
*
* <a href = "../htmldoxygen/pvaClientChannelGet.html">Overview of PvaClientChannelGet</a>
* <a href = "../htmldoxygen/pvaClientGet.html">Overview of PvaClientGet</a>
*/
class epicsShareClass PvaClientGet
{
@ -1042,10 +1065,6 @@ public:
* @return The interface.
*/
PvaClientGetDataPtr getData();
/** Deprecated method
* \deprecated This method will go away in future versions.
*/
void destroy() EPICS_DEPRECATED {}
private:
std::string getRequesterName();
void message(std::string const & message,epics::pvData::MessageType messageType);
@ -1097,7 +1116,7 @@ typedef std::tr1::shared_ptr<ChannelPutRequesterImpl> ChannelPutRequesterImplPtr
/**
* @brief An easy to use alternative to ChannelPut.
*
* <a href = "../htmldoxygen/pvaClientChannelPut.html">Overview of PvaClientChannelPut</a>
* <a href = "../htmldoxygen/pvaClientPut.html">Overview of PvaClientPut</a>
*/
class epicsShareClass PvaClientPut
{
@ -1162,10 +1181,6 @@ public:
* @return The interface.
*/
PvaClientPutDataPtr getData();
/** Deprecated method
* \deprecated This method will go away in future versions.
*/
void destroy() EPICS_DEPRECATED {}
private :
std::string getRequesterName();
void message(std::string const & message,epics::pvData::MessageType messageType);
@ -1216,7 +1231,7 @@ typedef std::tr1::shared_ptr<ChannelPutGetRequesterImpl> ChannelPutGetRequesterI
/**
* @brief An easy to use alternative to ChannelPutGet.
*
* <a href = "../htmldoxygen/pvaClientChannelPutGet.html">Overview of PvaClientChannelPutGet</a>
* <a href = "../htmldoxygen/pvaClientPutGet.html">Overview of PvaClientPutGet</a>
*/
class epicsShareClass PvaClientPutGet
{
@ -1300,10 +1315,6 @@ public:
* @return The interface.
*/
PvaClientGetDataPtr getGetData();
/** Deprecated method
* \deprecated This method will go away in future versions.
*/
void destroy() EPICS_DEPRECATED {}
private :
std::string getRequesterName();
void message(std::string const & message,epics::pvData::MessageType messageType);
@ -1488,10 +1499,6 @@ public:
* @return The interface.
*/
PvaClientMonitorDataPtr getData();
/** Deprecated method
* \deprecated This method will go away in future versions.
*/
void destroy() EPICS_DEPRECATED {}
private:
std::string getRequesterName();
void message(std::string const & message,epics::pvData::MessageType messageType);