PvaClient is a synchronous API for accessing PVData via PVAccess. -It also provides a number of convenience methods. -It allows the client to request access without checking for failure, -but throws an exception if a request fails. -A client can also check for failues and thus prevent exceptions.
- -Doxygen documentation is available at doxygenDoc
- -The PvaClient API has the following features:
-Simple examples of using pva:
-
-// pvaGet
-PvaClientPtr pva = PvaClient::create();
-double value = pva->channel("exampleDouble")->get()->getData()->getDouble();
-
-// pvaPut
-PvaClientChannelPtr channel = pva->channel("exampleDouble");
-PvaClientPutPtr put = channel->put();
-PvaClientPutDataPtr putData = put->getData();
-putData->putDouble(3.0); put->put();
-
-// pvaMonitor
-PvaClientMonitorPtr monitor = pva->channel("examplePowerSupply")->monitor("");
-PvaClientMonitorDataPtr pvaData = monitor->getData();
-while(true) {
- monitor->waitEvent();
- cout << "changed\n";
- pvaData->showChanged(cout);
- cout << "overrun\n";
- pvaData->showOverrun(cout);
- monitor->releaseEvent();
-}
-
-// pvaProcess
-PvaClientChannelPtr channel = pva->channel("exampleDouble");
-PvaClientProcessPtr process = channel->createProcess();
-process->process();
-
-
-A separate project exampleCPP has examples for pvDatabaseCPP -and for pvaClientCPP. -See it for pvaClientCPP examples. -
-pvaClient does not provide support for:
--If a proper RELEASE.local is present one directory level above pvaClientCPP. +pvaClientCPP is one of the components of + +EPICS Version 4 + +
+This document is only a guide to help locate code and documentation related to pvDatabaseCPP
-Just type: +It is intended for developers that want to use pvDatabaseCPP.
--make --
-An example of a proper RELEASE.local is: +
A guide for developers is available at + +developerGuide +
-
-EPICS4_DIR=/home/epicsv4/master
-EXAMPLE=${EPICS4_DIR}/exampleCPP
-PVDATABASE=${EPICS4_DIR}/pvDatabaseCPP
-PVACLIENT=${EPICS4_DIR}/pvaClientCPP
-PVASRV=${EPICS4_DIR}/pvaSrv
-PVACCESS=${EPICS4_DIR}/pvAccessCPP
-NORMATIVETYPES=${EPICS4_DIR}/normativeTypesCPP
-PVDATA=${EPICS4_DIR}/pvDataCPP
-PVCOMMON=${EPICS4_DIR}/pvCommonCPP
-
-EPICS_BASE=/home/install/epics/base
-
-
-pvaClientCPP can also be built if a file RELEASE.local exists in directory configure. -To create one do the following:
--mrk> pwd -/home/hg/pvaClientCPP/configure -mrk> cp ExampleRELEASE.local RELEASE.local --
Then edit RELEASE.local so that it has the correct location of each -product pvaClientCPP requires. -Than at the top level just execute make:
--mrk> cd .. -mrk> pwd -/home/epicsv4/master/pvaClientCPP -mrk> make -- -
An instance of PvaClient is obtained via the call:
--PvaClientPtr pva = PvaClient::create(); -- -
PvaClient has methods to create instances of PvaClientChannel. -The client can specify the provider name or use the default provider. -The client can manage it's own channels or can let pvaClient cache channels. -An example of using the cached method is:
-
-PvaClientChannelPtr pvaChannel = pva->channel("exampleDouble");
-
-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, pva caches the pvaChannel so that if the -client makes another request for the same channel the cached object is -returned to the client. +
This guide discusses all the components that are part of an EPICS V4 release. +Some understanding of the components and how they are related is necessary in order to +develop code that uses pvDatabaseCPP. +In particular read everything related to pvaClient.
-An example of using a non cached method is:
-
-PvaClientChannelPtr pvaChannel = pva->createChannel("exampleDouble");
-
-This will create an PvaClientChannel 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. +
The developerGuide discusses code in a way that applies to both CPP and C++. +For the descriptions of the CPP specific code consult the next section.
-This provides methods for connecting to a channel and for creating instances of -PvaClientField, PvaClientProcess, ..., PvaClientPutGet.
-Connection must be made before any create method is called or -an exception is raised. -The following is a synchronous connection request:
--pvaChannel->connect(5.0); // BLOCKS AND THROWS IF NO CONNECT --
This blocks until then connection is made or until timout occurs. -An exception is raised if the connection request fails. +
doxygen documentation is available at +doxygen
-The same request can be made without blocking and without exceptions.
-
-pvaChannel->issueConnect(); // DOES NOT BLOCK
-.....
-Status status =pvaChannel->waitConnect(5.0); // BLOCKS DOES NOT THROW
-if(!status.isOK()) {
- // failure do something
-}
-
-Once the channel is connected other PvaClient objects can be created. -For example:
--PvaClientGetPtr pvaGet = pvaChannel->get(); // DOES BLOCK --
This is a caching request. -If the client already has made an identical request the client will receive the -cached object. -If a new pvaGet is created than it is connected before it is returned to the client. -
-The client can also managed it's own objects:
--PvaClientGetPtr pvaGet = pvaChannel->createGet(); // DOES NOT BLOCK --
The client must connect the pvaGet.
-This provides the data returned by pvaGet and pvaPutGet. -It is obtained via:
--PvaClientGetDataPtr pvaData = pvaGet->getData(); --
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. +
Example code is available as part of this release. + +exampleCPP +
-An example is:
--double value = pvaData->getDouble(); --
It also keeps a bitSet showing which fields have changed since the last channelGet or channelPutGet.
- -To the client this looks identical to PvaClientGetData except that -it provides two BitSets: changedBitSet and overrrunBitSet. -It is used by pvaMonitor. -
-This is used to provided data for pvaPut and pvaPutGet. -It has many of the same methods as pvaGetData. -It does not have a bitSet. -It also has put methods like:
--void pvaData->putDouble(5.0); --
This provides methods to connect to channelGet and to issue get request. -To connect via a single synchronous call:
--easyGet->connect(); // BLOCKS AND CAN THROW --
This can also be done in two steps:
--pvaGet->issueConnect(); // DOES NOT BLOCK -... -Status status = pvaGet->waitConnect(); // BLOCKS AND DOES NOT THROW --
Once connected gets are issued via either:
--void pvaGet->get(); // BLOCKS AND CAN THROW --or -
-pvaGet->issueGet(); // DOES NOT BLOCK -... -Status status = pvaGet->waitGet(); // BLOCKS AND DOES NOT THROW --
This is similar to pvaGet except that it wraps channelPut instead of channelGet. -
-Once connected puts are issued via either:
--void pvaPut->put(); // BLOCKS AND CAN THROW --or -
-pvaPut->issuePut(); // DOES NOT BLOCK -... -Status status = pvaPut->waitPut(); // BLOCKS AND DOES NOT THROW --
Connecting is similar to pvaGet and pvaPut. -The other methods are:
-Connecting is similar to pvaGet. -It has methods:
-Connecting is similar to pvaGet. -It has methods:
-Look at javaDoc for details.
- -This provides methods for connecting to multiple channels. -
-This provides support for channelGet to multiple channels where each channel has a value field that is a numeric scalar. -
-This provides support for channelPut to multiple channels where each channel has a value field that is a numeric scalar. -
-This provides support for monitoring changes to multiple channels where each channel has a value field that is a numeric scalar. -
-This provides support for channelGet to multiple channels where each channel has a value field that has any valid type. -
-This provides support for channelPut to multiple channels where each channel has a value -field that has any valid type. -
-This provides support for monitoring changes to multiple channels where each channel has a -value field that has any valid type. -
-This provides support for monitoring changes to multiple channels where each channel has a value field that has any valid type. -The client can get the data as normative type NTMultiChannel. +
In particular look at exampleClient. +It has many examples of using pvaClientCPP.
null if the request failed.
@@ -1493,7 +1544,15 @@ class epicsShareClass PvaClientRPC :
{
public:
POINTER_DEFINITIONS(PvaClientRPC);
- /** Create a PvaClientRPC.
+ /** @brief Create a PvaClientRPC.
+ * @param &pvaClient Interface to PvaClient
+ * @param channel Interface to Channel
+ * @return The interface to the PvaClientRPC.
+ */
+ static PvaClientRPCPtr create(
+ PvaClientPtr const &pvaClient,
+ epics::pvAccess::Channel::shared_pointer const & channel);
+ /** @brief Create a PvaClientRPC.
* @param &pvaClient Interface to PvaClient
* @param channel Interface to Channel
* @param pvRequest The request structure.
@@ -1504,31 +1563,33 @@ public:
epics::pvAccess::Channel::shared_pointer const & channel,
epics::pvData::PVStructurePtr const &pvRequest
);
- /** Destructor
+ /** @brief Destructor
*/
~PvaClientRPC();
- /** Call issueConnect and then waitConnect.
+ /** @brief Call issueConnect and then waitConnect.
+ *
* An exception is thrown if connect fails.
*/
void connect();
- /** Issue the channelRPC connection to the channel.
+ /** @brief Issue the channelRPC connection to the channel.
+ *
* This can only be called once.
* An exception is thrown if connect fails.
* @throw runtime_error if failure.
*/
void issueConnect();
- /** Wait until the channelRPC connection to the channel is complete.
+ /** @brief Wait until the channelRPC connection to the channel is complete.
* @return status;
*/
epics::pvData::Status waitConnect();
- /** issue a request and wait for response
+ /** @brief Issue a request and wait for response
* @param pvArgument The data to send to the service.
* @return The result
* @throw runtime_error if failure.
*/
epics::pvData::PVStructure::shared_pointer request(
epics::pvData::PVStructure::shared_pointer const & pvArgument);
- /** issue a request and return immediately.
+ /** @brief issue a request and return immediately.
* @param pvArgument The data to send to the service.
* @param pvaClientRPCRequester The requester that is called with the result.
* @throw runtime_error if failure.
diff --git a/src/pv/pvaClientMultiChannel.h b/src/pv/pvaClientMultiChannel.h
index faa9cb8..ffaff18 100644
--- a/src/pv/pvaClientMultiChannel.h
+++ b/src/pv/pvaClientMultiChannel.h
@@ -62,7 +62,7 @@ class epicsShareClass PvaClientMultiChannel :
{
public:
POINTER_DEFINITIONS(PvaClientMultiChannel);
- /** Create a PvaClientMultiChannel.
+ /** @brief Create a PvaClientMultiChannel.
* @param pvaClient The interface to pvaClient.
* @param channelNames The names of the channel..
* @param providerName The name of the provider.
@@ -76,69 +76,70 @@ public:
size_t maxNotConnected=0
);
/**
- * Destructor
+ * @brief Destructor
*/
~PvaClientMultiChannel();
- /** Get the channelNames.
+ /** @brief Get the channelNames.
* @return The names.
*/
epics::pvData::shared_vector