EPICS pvAccessCPP

Release 4.0 - 2015.12.10

Abstract

pvAccessCPP is the C++ implementation of pvAccess, which is network support for transporting structured data as defined by pvData.

pvAccess is one of a related set of products: relatedDocumentsV4.html

Status of this Document

This is the 12-December-2015 version of the C++ implementation of pvAccess. The code is a complete implementation of pvAccess.

Table of Contents


Preface

This product is available via an open source license

This document describes the pvAccess Application Program Interface (API). The reader is assumed to have a basic understanding of EPICS V4 as described in:
EPICS V4 Developer's Guide

The pvAccess API is callback based and uses Status to report problems to the client, which means that it can be complex to use. If your primary interest is client access then, instead of reading this document, read:
pvaClientCPP

If your primary interest is implementing support for PVRecords then, before reading this documement read:
pvDatabaseCPP

Doxygen documentation is available at doxygenDoc

Introduction

This document briefly describes the most important classes, class methods, and global methods used by client and/or service code. Not all classes and methods are described. When source code from include files is shown it is often a simplified version. Ptr is shorthand for ::shared_pointer For example:

ChannelFindPtr
instead of
ChannelFind::shared_pointer

pvAccess provides network support for structured data as described by pvData.

Basic Concepts

pvAccess has the following basic concepts:

client and server
pvAccess provides a way for a client to communicate with a server. All data passed between client and server is via pvData.
channel
A channel is a communication path between a client and a server. Each channel has a channelName that is unique within the local area network.
provider
A provider is the server side of the communication between client and server. An arbitrary number of providers can exist.

The client and server can exists in the same process or if the provider is pva the provider can be at some remote location in the network.

Each provider must have a providerName that is unique in the local process.

An arbitrary number of channelProviders can be implemented on both the client and server side.

registry
This allows clients and providers to locate each other.

ChannelProviderRegistry Overview

Three global methods are available:

getChannelProviderRegistry
Get the single instance of ChannelProviderRegistry.
registerChannelProviderFactory
Register a ChannelProvider
unregisterChannelProviderFactory
Remove a ChannelProvider

ChannelProviderRegistry provides the method:

getProvider

ChannelProvider Overview

Provides the following methods:

createChannel
Create a channel.

Channel Overview

Channel provides methods to create the following:

ChannelProcess
Client can make requests to process the channel.
ChannelGet
Client can make requests to get data from a channel.
ChannelPut
Client can make requests to put data to a channel.
ChannelPutGet
Client can make requests to put data to a channel, process the channel, and get data from the channel.
Monitor
Monitor data changes in the channel.
ChannelArray
Get or put data to a sub-array.
ChannelRPC
Similar to ChannelPutGet but data types can change for each request.

ChannelProviders implemented by pvAccessCPP

Client Side

pva network protocol
This connects the client to a server via the pva network protocol, which is a protocol for passing pvData objects. The protocol is described in:
pvAccess Protocol Specification
ca network protocol
This connects the client to a server via the ca network protocal, i. e. it connects to an existing V3 IOC. This is client side only code. It transforms data between pvData and ca DBR data, The ca protocol is described in:
Channel Access Reference Manual

Since both the client and server side of pvAccess use the same ChannelProviderRegistry an an arbitrary number of providers can register. Note in particular that both the client and server sides of pva can both register. This allows server code to also use pva client to communicate with other servers.

Server Side

pva network protocol
The server side for pva network protocol. It connects the server side of the network to ChannelProviders.
rpcService
This is the "glue" code for implementing the server side of a ChannelRPC service. An actual service must implement method request.
PipelineService
This is the "glue" code for implementing the server side pipeline service (reliable monitors using flow control).

The server side of the pva network protocal. allows an arbitrary number of providers to register with it. Existing examples are:

local provider
pvDatabase implements a PVDatabase, which is a memory resident database of PVRecords. Each PVRecord has a name, which is the channel name, and a top level PVStructure. A record is "smart" because each record has an associated method named process.
pvaSrv
This is a ChannelProvider for accessing V3 IOC DBRecords. It transforms the data in a V3 DBRecord to a top level PVStructure.

Command Line Utilities

pvAccessCPP provides the following command line utilities:
pvlist, pvinfo, pvget, pvput, and eget.

In order to use these commands a path to the pvAccessCPP bin directory must exists. For example, on my linux workstation .bash_profile includes the statements:

export EPICSV4=/home/epicsv4
export PATH=$PATH:${EPICSV4}/pvAccessCPP/bin/${EPICS_HOST_ARCH}

This document gives a VERY brief explaination if each command but each provides a -help option. For example:

mrk> pvlist -help

Usage: pvlist [options] [server address or GUID starting with '0x']...

  -h: Help: Print this message
options:
  -i                 Print server info (when server address list/GUID is given)
  -w <sec>:          Wait time, specifies timeout, default is 3.000000 second(s)
  -q:                Quiet mode, print only error messages
  -d:                Enable debug output

examples:
	pvlist
	pvlist ioc0001
	pvlist 10.5.1.205:10000
	pvlist 0x83DE3C540000000000BF351F

A longer explanation of the commands is in:

EPICS V4 Developer's Guide

pvlist

Shows all servers avaliable via the pva network protocal and also a list of all channels for a particular server.

pvinfo

Shows the connection status and introspection interface for channels.

pvget

Returns data for a channel via channelGet or monitor.

pvput

Puts data to a channel via channelPut.

eget

pvget on steroids. Also has support for channelRPC and some of the normative types.

Include Files

The following are the include files that are of most interest to clients:

pvAccess.h
This document discusses most of the clases described in pvAccess.h. The following are not discussed in this document:
enum AccessRights {none,read,readWrite};
class Lockable...
class ScopedLock...
clientFactory.h
Static methods to start and stop the pva provider.
rpcClient.h
Code for implementing the client side of a channelRPC request.
caProvider.h
Needed to start the provider for the ca network protocol.

The following are of interest to service code:

serverContext.h
Needed to start pvAccess Server Context.
rpcServer.h
Code for implementing the context for server side of a channelRPC request.
rpcService.h
Each channelRpc service must implement RPCService or RPCServiceAsync interface.
pipelineServer.h
Code for implementing the context for server side pipeline service.
pipelineService.h
Each pipeline service must implement PipelineService interface.

Starting PVAccess Clients

To start both the pva and ca client providers issue the commands:

ClientFactory::start();
CAClientFactory::start();

Starting pvAccess Server Context

To see examples of how to start a pvAccess server look at the examples provided in exampleDatabaseCPP. It shows examples for both a standalone main server and a V4 server that runs as part of a V3 IOC. The following is taken from exampleDatabaseMain.cpp that is in example database:

int main(int argc,char *argv[])
{

...
     
    ChannelProviderLocalPtr channelProvider = getChannelProviderLocal();
    ServerContext::shared_pointer ctx =
        startPVAServer(PVACCESS_ALL_PROVIDERS,0,true,true);

...
    ctx->destroy();
    return 0;
}

class ChannelProviderRegistry

class ChannelProviderRegistry
{
public:
   virtual ~ChannelProviderRegistry();
   virtual ChannelProviderPtr getProvider(string const & providerName);
   virtual ChannelProviderPtr createProvider(string const & providerName);
   virtual std::auto_ptr<vector<string> > getProviderNames();
};
epicsShareExtern ChannelProviderRegistryPtr getChannelProviderRegistry();
epicsShareExtern void registerChannelProviderFactory(ChannelProviderFactoryPtr const & channelProviderFactory);
epicsShareExtern void unregisterChannelProviderFactory(ChannelProviderFactoryPtr const & channelProviderFactor

The global methods are:

getChannelProviderRegistry
Called by both client and services to get the single instance of ChannelProviderRegistry.
registerChannelProviderFactory
Called by a service that implements ChannelProvider. Note that implementing a ChannelProvider is a big task, which is why pvDatabaseCPP exists.
unregisterChannelProviderFactory
Called by a service if it no longer wants the provider to be used.

The methods for ChannelProviderRegistry are:

getProvider
Called by both client and services to get the shared instance of channelProvider.
The providerName must be the name of a registered provider.
Most clients will use either pva or ca.
Most services will use pvDatabaseCPP, which implements provider local. A service that is also a client can also use local or pvaSrv.
createProvider
Same as getProvider just that this call creates a new instance of the provider (i.e. this instance is not shared).
Most clients will use getProvider method.
getProviderNames
Gets the names of all registered providers.

class ChannelProvider

class ChannelProvider
{
public:
    static const short PRIORITY_MIN = 0;
    static const short PRIORITY_MAX = 99;
    static const short PRIORITY_DEFAULT = PRIORITY_MIN;
    static const short PRIORITY_LINKS_DB = PRIORITY_MAX;
    static const short PRIORITY_ARCHIVE = (PRIORITY_MAX + PRIORITY_MIN) / 2;
    static const short PRIORITY_OPI = PRIORITY_MIN;

    virtual destroy() {}
    virtual std::string getProviderName() = 0;
    virtual ChannelFindPtr channelFind(
        std::string const & channelName,
        ChannelFindRequesterPtr const & channelFindRequester) = 0;
    virtual ChannelFindPtr channelList(
        ChannelListRequesterPtr const & channelListRequester) = 0;
    virtual ChannelPtr createChannel(
        std::string const & channelName,
        ChannelRequesterPtr const & channelRequester,
    virtual ChannelPtr createChannel(
        std::string const & channelName,
        ChannelRequesterPtr const & channelRequester,
        short priority,
        std::string const & address);

    /// experimental methods
    virtual void configure(PVStructurePtr /*configuration*/) {};
    virtual void flush() {};
    virtual void poll() {};

};

class ChannelFind
{
public:
    virtual ChannelProviderPtr getChannelProvider();
    virtual void cancel();
};

class ChannelFindRequester
{
public:
    virtual ~ChannelFindRequester() {}
    virtual void channelFindResult(
        const Status& status,
        ChannelFindPtr const & channelFind,
        bool wasFound) = 0;
};

class ChannelListRequester
{
public:
    virtual ~ChannelListRequester() {};
    virtual void channelListResult(
        const Status& status,
        ChannelFindPtr const & channelFind,
        PVStringArray::const_svector const & channelNames,
        bool hasDynamic) = 0;
};

The methods of ChannelProvider are:

getProviderName
Returns the name of the channel provider.
channelFind
Determines if the channel exists. The result is passed by calling the channelFindResult of channelFindRequester. The caller must implement channelFindRequester, which is described below. The return value is ChannelFindPtr, which the caller can use to cancel a request.
channelList
Gets a list of all the channels served by this provider. The result is passed by calling the channelListResult of channelListRequester. The caller must implement channelListRequester, which is described below. The return value is ChannelFindPtr, which the caller can use to cancel a request.
createChannel
Creates a connection to a channel. The result passed by calling methods of ChannelRequester. The caller must implememt ChannelRequester, which is described along with Channel below.

The methods of ChannelFind are:

getChannelProvider
Returns the provider.
cancel
Cancel the current channelFind or channelList request.

The method of ChannelFindRequester are:

channelFindResult
If wasFound is true then status is OK. If not found then status provides reason for failure.

The method of ChannelListRequester are:

channelListResult
If there is a problem with the channelList request status provides the reason. channelNames provides the list of channels the provider is currently providing. hasDynamic indicates that the set of channels is not static, i.e. might change during runtime.

Channel

class ChannelRequester

This must be implemented by a client. It shows the result of a ChannelProvider::createChannel request and also the connection state of the channel.

class ChannelRequester : Requester
{
public:
    virtual void channelCreated(
        const Status& status, ChannelPtr const & channel) = 0;
    virtual void channelStateChange(
        ChannelPtr const & channel,
        Channel::ConnectionState connectionState) = 0;
};

The methods of ChannelRequester are:

channelCreated
This is called as a result of a ChannelProvider::createChannel request. It shows if the request was successful. If not successful then channel is null and status shows why the request failed.
channelStateChange
When the client successfuly connects to a channel this is called with ConnectionState=CONNECTED. After successfuly connecting the client can call the channel methods.
This method is also called whenever the channel disconnects or re-connects. When a reconnect occurs the implementaion automatically reconnects any channelGet, channelPut, etc that the client has created.

class Channel

class Channel : Requester ...
{
public:
    POINTER_DEFINITIONS(Channel);

    enum ConnectionState {
        NEVER_CONNECTED, CONNECTED, DISCONNECTED, DESTROYED
    };

    static const char* ConnectionStateNames[];

    virtual destroy() {}
    virtual ChannelProviderPtr getProvider() = 0;
    virtual std::string getRemoteAddress() = 0;
    virtual ConnectionState getConnectionState() = 0;
    virtual std::string getChannelName() = 0;
    virtual ChannelRequesterPtr getChannelRequester() = 0;
    virtual bool isConnected() = 0;
    virtual void getField(
        GetFieldRequesterPtr const & requester,
        std::string const & subField) = 0;
    virtual AccessRights getAccessRights(PVFieldPtr const & pvField) = 0;
    virtual ChannelProcessPtr createChannelProcess(
            ChannelProcessRequesterPtr const & channelProcessRequester,
            PVStructurePtr const & pvRequest) = 0;
    virtual ChannelGetPtr createChannelGet(
            ChannelGetRequesterPtr const & channelGetRequester,
            PVStructurePtr const & pvRequest) = 0;
    virtual ChannelPutPtr createChannelPut(
            ChannelPutRequesterPtr const & channelPutRequester,
            PVStructurePtr const & pvRequest) = 0;
    virtual ChannelPutGetPtr createChannelPutGet(
            ChannelPutGetRequesterPtr const & channelPutGetRequester,
            PVStructurePtr const & pvRequest) = 0;
    virtual ChannelRPCPtr createChannelRPC(
            ChannelRPCRequesterPtr const & channelRPCRequester,
            PVStructurePtr const & pvRequest) = 0;
    virtual MonitorPtr createMonitor(
            MonitorRequesterPtr const & monitorRequester,
            PVStructurePtr const & pvRequest) = 0;
    virtual ChannelArrayPtr createChannelArray(
            ChannelArrayRequesterPtr const & channelArrayRequester,
            PVStructurePtr const & pvRequest) = 0;
    virtual void printInfo() = 0;
    virtual void printInfo(std::ostream& out) = 0;
};
where:
destroy
Destroy all resources belonging to the channel. This includes all channelPuts, channelGets, etc and any remote connections.
getProvider
Get the name of the provider.
getRemoteAddress
Get the remote address of the channel.
getConnectionState
Get the connection state.
getChannelName
Get the channel name.
getChannelRequester
Get the interface to the code that created the channel.
isConnected
Is the channel connected?
getField
Get the introspection interface for the subfield of the PVStructure attached to the channel. The result is returned via the GetFieldRequester, which must be implemented by the caller.
getAccessRights
Get the access rights for the caller. The access rights are one of none, read , or readWrite.
createChannelProcess
Create a ChannelProcess, which is described below.
createChannelGet
Create a ChannelGet, which is described below.
createChannelPut
Create a ChannelPut, which is described below.
createChannelPutGet
Create a ChannelPutGet, which is described below.
createChannelRPC
Create a ChannelRPC, which is described below.
createMonitor
Create a Monitor, which is described below.
createChannelArray
Create a ChannelArray, which is described below.
printInfo
Print information about the channel.

class GetFieldRequester

class GetFieldRequester : virtual public Requester {
public:
    virtual void getDone(
        const Status& status,
        FieldConstPtr const & field) = 0;
};
where:
getDone
This is called as a result of a call to Channel::getField. status shows the result. if status is OK then field is the introspection interface for the requested field.

class ChannelRequest

This is a base class for ChannelGet, ChannelPut, etc.

class ChannelRequest
{
public:
    virtual ChannelPtr getChannel() = 0;
    virtual void cancel() = 0;
    virtual void lastRequest() = 0;
};
where:
getChannel
Get the Channel interface.
cancel
Cancel any outstanding request
lastRequest
The current request is the last request. Allows the implementation to release resources

ChannelGet

This is used to get data from a server.

class ChannelGet

class ChannelGet : public ChannelRequest {
public:
    virtual void get() = 0;
};
where
get
Issue a get request to the server. The result is returned via a call to ChannelGetRequester::getDone. Only one get request at a time can be outstanding, i. e. a new get can not be issued until the callback for the first is called.

class ChannelGetRequester

class ChannelGetRequester : virtual public Requester {
    public:
    virtual void channelGetConnect(
            const Status& status,
            ChannelGetPtr const & channelGet,
            Structure::const_shared_pointer const & structure) = 0;
    virtual void getDone(
            const Status& status,
            ChannelGetPtr const & channelGet,
            PVStructurePtr const & pvStructure,
            BitSetPtr const & bitSet) = 0;
};
where:
channelGetConnect
This is called as a result of calling Channel::createChannelGet. If status is OK, then channelGet is the interface to ChannelGet and structure is the introspection interface that will be used for the data returned by every call to ChannelGet::get. If status shows a failure then the client should NOT use either channelGet or structure.
getDone
This is called as a result of a call to ChannelGet::get. status shows the result. if status is OK then pvStructure has the data and bitSet shows which fields have changed since the previous call. The data and bitSet "belong" to the client until the next get is issued. After that the data may change.

ChannelPut

This is used to put data to a server.

class ChannelPut

class ChannelPut : public ChannelRequest {
public:
    virtual void put(
            PVStructurePtr const & pvPutStructure,
            BitSetPtr const & putBitSet) = 0;
    virtual void get() = 0;

};
where:
put
Put all changed fields of pvPutStructure to the server. putBitSet shows which fields are to be sent. When the put completes (an ack is received from the server) ChannelPutRequester::putDone is called. Only one put or get request at a time can be outstanding, i. e. a new put or get can not be issued until the callback for the first is called.
get
Get the current data from the server. The result is returned via a call to ChannelPutRequester::getDone.

class ChannelPutRequester

class ChannelPutRequester : virtual public Requester {
public:
    virtual void channelPutConnect(
            const Status& status,
            ChannelPutPtr const & channelPut,
            Structure::const_shared_pointer const & structure) = 0;
    virtual void putDone(
            Status & status,
            ChannelPutPtr const & channelPut) = 0;
    virtual void getDone(
            const Status& status,
            ChannelPutPtr const & channelPut,
            PVStructurePtr const & pvStructure,
            BitSetPtr const & bitSet) = 0;
};
where:
channelPutConnect
This is called as a result of calling Channel::createChannelPut. If status is OK, then channelPut is the interface to ChannelPut and structure is the introspection interface that must be used for the pvStructure passed to each ChannelPut::put and will be used for the data returned by every call to ChannelPut::get. If status shows a failure then the client should NOT use either channelPut or structure.
putDone
Called when ChannelPut::put is acknowledged by the server. status shows the result.
getDone
This is called as a result of a call to ChannelPut::get. status shows the result. if status is OK then pvStructure has the data and bitSet shows which fields have changed since the previous call. The data and bitSet "belong" to the client until the next get is issued. After that the data may change.

ChannelPutGet

This is used to:

put data to a server
process
get data from the server

class ChannelPutGet

class ChannelPutGet : public ChannelRequest {
public:
    virtual void putGet(
            PVStructurePtr const & pvPutStructure,
            BitSetPtr const & putBitSet) = 0;
    virtual void getPut() = 0;
    virtual void getGet() = 0;
};
where:
putGet
Put all changed fields of pvPutStructure to the server. putBitSet shows which fields are to be sent.
The server processes and returns data to the client.
When the putGet completes ChannelPutGetRequester::putDone is called with the result.
Only one putGet or getGet or getPut request at a time can be outstanding, i. e. a new request can not be issued until the callback for the first is called.
getPut
Get the current put data from the server.
The result is returned via a call to ChannelPutGetRequester::getPutDone.
getGet
Get the current get data from the server.
The result is returned via a call to ChannelPutGetRequester::getGet.

class ChannelPutGetRequester

class ChannelPutGetRequester : virtual public Requester
{
    public:
    virtual void channelPutGetConnect(
            const Status& status,
            ChannelPutGetPtr const & channelPutGet,
            Structure::const_shared_pointer const & putStructure,
            Structure::const_shared_pointer const & getStructure) = 0;

    virtual void putGetDone(
            const Status& status,
            ChannelPutGetPtr const & channelPutGet,
            PVStructurePtr const & pvGetStructure,
            BitSetPtr const & getBitSet) = 0;

    virtual void getPutDone(
            const Status& status,
            ChannelPutGetPtr const & channelPutGet,
            PVStructurePtr const & pvPutStructure,
            BitSetPtr const & putBitSet) = 0;

    virtual void getGetDone(
            const Status& status,
            ChannelPutGetPtr const & channelPutGet,
            PVStructurePtr const & pvGetStructure,
            BitSetPtr const & getBitSet) = 0;
};
where:
channelPutGetConnect
This is called as a result of calling Channel::createChannelPutGet.
If status is OK, then putStructure is the introspection interface that 1) must be used for the pvStructure passed to each ChannelPutGet::putGet and 2) will be used for the data returned by every call to ChannelPutGet::getPut.
getStructure is the introspection interface that will be used for the data returned by every call to ChannelPutGet::getGet and ChannelPut::putGet.
If status shows a failure then the client should NOT use either channelPut or putStructure or getStructure.
putGetDone
Called when ChannelPutGet::putGet is acknowledged by the server. status shows the result. If status is OK then pvGetStructure has the data and getBitSet shows which fields have changed since the previous call. The data and bitSet "belong" to the client until the next putGet or getGet is issued. After that the data may change.
getPutDone
This is called as a result of a call to ChannelPutGet::getPut. status shows the result. If status is OK then pvPutStructure has the data and putBitSet shows which fields have changed since the previous call. The data and bitSet "belong" to the client until the next get is issued. After that the data may change.
getGetDone
Called when ChannelPutGet::getGet is acknowledged by the server. status shows the result. If status is OK then pvGetStructure has the data and getBitSet shows which fields have changed since the previous call. The data and bitSet "belong" to the client until the next putGet or getGet is issued. After that the data may change.
getPutDone
This is called as a result of a call to ChannelPutGet::getPut. status shows the result. If status is OK then pvPutStructure has the data and putBitSet shows which fields have changed since the previous call. The data and bitSet "belong" to the client until the next get is issued. After that the data may change.

ChannelArray

class ChannelArray

Get/Put a subset of an array. This works for all of scalarArray, unionArray, and structureArray.

class ChannelArray : public ChannelRequest
{
public:
    virtual void putArray(
            PVArrayPtr const & putArray,
            size_t offset = 0,
            size_t count = 0,
            size_t stride = 1) = 0;
    virtual void getArray(
            size_t offset = 0,
            size_t count = 0,
            size_t stride = 1) = 0;
    virtual void getLength() = 0;
    virtual void setLength(size_t length) = 0;
};
where:
putArray
The putArray is sent to the server, which changes to specified elements of the server array.
getArray
The server selects the specified set of elements in the server array and returns the result to the client.
getLength
Get the current length of the server array.
setLength
Set the length of the server array.

class ChannelArrayRequester

class ChannelArrayRequester : virtual public Requester {
public:
    virtual void channelArrayConnect(
            const Status& status,
            ChannelArrayPtr const & channelArray,
            Array::const_shared_pointer const & array) = 0;
    virtual void putArrayDone(
            const Status& status,
            ChannelArrayPtr const & channelArray) = 0;
    virtual void getArrayDone(
            const Status& status,
            ChannelArrayPtr const & channelArray,
            PVArrayPtr const & pvArray) = 0;
    virtual void getLengthDone(
            const Status& status,
            ChannelArrayPtr const & channelArray,
            size_t length) = 0;
    virtual void setLengthDone(
            const Status& status,
            ChannelArrayPtr const & channelArray) = 0;
};
where:
channelArrayConnect
This is called as a result of calling Channel::createChannelArray.
If status is OK, then array is the introspection interface that 1) must be used for creating the putArray for ChannelArray::putArray, and 2) will be the interface for the result passed to getArrayDone.
putArrayDone
The result of calling ChannelArray::putArray. status shows the result.
getArrayDone
The result of calling ChannelArray::getArray. status shows the result.
If status is OK, pvArray has the result.
getLengthDone
The result of calling ChannelArray::getLength. status shows the result.
If status is OK length is the length of the server array.
setLengthDone
The result of calling ChannelArray::setLength. status shows the result.

Monitor

Described in pvDataCPP. See: EPICS pvDataCPP

For convenience the classes are shown here.

class MonitorElement

class MonitorElement {
public:
    MonitorElement(){}
    MonitorElement(PVStructurePtr const & pvStructurePtr);
    PVStructurePtr pvStructurePtr;
    BitSetPtr changedBitSet;
    BitSetPtr overrunBitSet;
};

class Monitor

class Monitor : public Destroyable{
public:
    virtual ~Monitor(){}
    virtual Status start() = 0;
    virtual Status stop() = 0;
    virtual MonitorElementPtr poll() = 0;
    virtual void release(MonitorElementPtr const & monitorElement) = 0;
};

class MonitorRequester

class MonitorRequester : public virtual Requester {
public:
    virtual ~MonitorRequester(){}
    virtual void monitorConnect(Status const & status,
        MonitorPtr const & monitor, StructureConstPtr const & structure) = 0;
    virtual void monitorEvent(MonitorPtr const & monitor) = 0;
    virtual void unlisten(MonitorPtr const & monitor) = 0;
};

ChannelRPC

class ChannelRPC

class ChannelRPC : public ChannelRequest {
public:
    virtual void request(PVStructurePtr const & pvArgument) = 0;
};
where:
request
Issue a request to the server.
pvArgument is sent to the server. The server processes the request and returns the result by calling ChannelRPCRequester::requestDone.

class ChannelRPCRequester

class ChannelRPCRequester : virtual public Requester {
public:
    virtual void channelRPCConnect(
            const Status& status,
            ChannelRPCPtr const & channelRPC) = 0;

    virtual void requestDone(
            const Status& status,
            ChannelRPCPtr const & channelRPC,
            PVStructurePtr const & pvResponse) = 0;
};
where:
channelRPCConnect
Called as a result of Channel::createChannelRPC.
status shows the result.
requestDone
Called as a result of ChannelRPC::request.
status shows the result.
If status is OK pvResponse is the result.

Client Providers Implemented by pvAccessCPP

ClientFactory

This package provides implementation of the client side of a ChannelProvider that uses the pvAccess network protocol to communicate between client and server. The provider name is pva.

class ClientFactory {
    static void start();
    static void stop();
};

where

start
Start the client side of remote pvAccess.
stop
Stop the client side of remote pvAccess.

CAClientFactory

This provides an implementation of ChannelProvider that uses the Channel Access network protocol. It converts between DBR data and pvData. The provider name is ca.

class CAClientFactory
{
    static void start();
    static void stop();
};

where

start
Start the client side of remote pvAccess.
stop
Stop the client side of remote pvAccess.

Server Context

This implements the server side of the pva network protocal and also provides a context for running remote providers.

class  ServerContext
{
public:
	virtual ~ServerContext() {};
	virtual const GUID& getGUID() = 0;
	virtual const Version& getVersion() = 0;
	virtual void initialize(ChannelProviderRegistryPtr const & channelProviderRegistry) = 0;
	virtual void run(int32 seconds) = 0;
	virtual void shutdown() = 0;
	virtual void destroy() = 0;
	virtual void printInfo() = 0;
	virtual void printInfo(std::ostream& str) = 0;
	virtual void dispose() = 0;
    virtual epicsTimeStamp& getStartTime() = 0;
    virtual void setBeaconServerStatusProvider(BeaconServerStatusProviderPtr const & beaconServerStatusProvider) = 0;

};

ServerContextPtr startPVAServer(
        std::string const & providerNames = PVACCESS_ALL_PROVIDERS,
        int timeToRun = 0,
        bool runInSeparateThread = false,
        bool printInfo = false);
where
getGUID
Returns GUID (12-byte array).
getVersion
Get context implementation version.
initialize
Set ChannelProviderRegistry implementation and initialize server.
run
Run server (process events).
seconds time in seconds the server will process events (method will block), if 0the method would block until destroy() is called.
shutdown
Shutdown (stop executing run() method) of this context. * After shutdown Context cannot be rerun again, destroy() has to be called to clear all used resources.
destroy
Clear all resources attached to this context.
printInfo
Prints detailed information about the context to the standard output stream.
dispose
Dispose (destroy) server context. This calls destroy() and silently handles all exceptions.
getStartTime
Get the time when the context was started.
setBeaconServerStatusProvider
Set beacon server status provider.
startPVAServer
Called by remote providers to start the remote side of the pva network protocol. This includes providing context.

RPC

rpcClient

RPCClient is an interface class that is used by a service client.

class RPCClient
{
    virtual ~RPCClient() {}
    static shared_pointer create(const string & serviceName);
    static PVStructurePtr sendRequest(const string & serviceName,
            PVStructurePtr const & request, double timeOut = RPCCLIENT_DEFAULT_TIMEOUT);
        void issueConnect();
        bool waitConnect(double timeout = RPCCLIENT_DEFAULT_TIMEOUT);
        PVStructurePtr request(
            PVStructurePtr const & pvArgument,
            double timeout = RPCCLIENT_DEFAULT_TIMEOUT,
            bool lastRequest = false);
        void issueRequest(
            PVStructurePtr const & pvArgument,
            bool lastRequest = false);
        PVStructurePtr waitResponse(double timeout = RPCCLIENT_DEFAULT_TIMEOUT);
    };

where
sendRequest
Performs complete blocking RPC call, opening a channel and connecting to the service and sending the request.
create
Given a serviceName create a RCPClient.
issueConnect
Issue a connect request and return immediately.
waitConnect
Wait for the connect request to complete
request
Sends a request and wait for the response or until timeout occurs.
issueRequest
Issue a channelRPC request and return immediately.
waitResponse
Wait for the request to complete.

rpcServer

Provides the context for the server side of channelRPC.

class RPCServer : 
{
    RPCServer();
    virtual ~RPCServer();
    void registerService(string const & serviceName, RPCService::shared_pointer const & service);
    void registerService(string const & serviceName, RPCServiceAsync::shared_pointer const & service);
    void unregisterService(string const & serviceName);
    void run(int seconds = 0);
    void runInNewThread(int seconds = 0);
    void destroy();    
    void printInfo();
};

// private helper method, will (can) be removed in the future
ChannelPtr createRPCChannel(ChannelProviderPtr const & provider,
    string const & channelName,
    ChannelRequesterPtr const & channelRequester,
    ServicePtr const & rpcService);

where
registerService
Register a new service. The server can either be synchronous ot asynchonous.
unregisterService
Unregister the service.
run
Calls server context run.
runInNewThread
Starts a new thread.
destroy
Calls server context destroy.
printInfo
Shows the channel and connection status.

rpcService

Base class for channelRPC services. To implement a rpcService you need to implement RPCService or RPCServiceAsync interface.

class  RPCRequestException
{
    RPCRequestException(Status::StatusType status, string const & message);
    Status::StatusType getStatus() const;
};


class  RPCService
{
    virtual ~RPCService() {};
    virtual PVStructurePtr request(
       PVStructurePtr const & args
    ) = 0;
};



class RPCResponseCallback
{
    virtual ~RPCResponseCallback() {};
    virtual void requestDone(
        Status const & status,
        PVStructurePtr const & result
    ) = 0;
};

class epicsShareClass RPCServiceAsync :
        public virtual Service
{
    virtual ~RPCServiceAsync() {};
    virtual void request(
        PVStructurePtr const & args,
        RPCResponseCallbackPtr const & callback
    ) = 0;
};
where
RPCRequestException
getStatus
Get the status type.
RPCService
request
The client has issued a request.
RPCResponseCallback
requestDone
This is called by service when a request is done.
RPCServiceAsync
request
The client has issued a request. A service must call callback->requestDone() method to notify completion.

pipeLineServer

A pipeline server supports reliable monitor support. This is implemented by allowing the client to make the server delay when the client can not keep up with the server.

The server implememts Channel::createMonitor but none of the other create methods. When the client creates a monitor the following request options can be specified:

"record[pipeline=true,queueSize=size,ackAny=n]" 
where
pipeline
This option must be set true.
queueSize
This option is optional.
ackAny
This option is optional. If not specified the value is queueSize/2.

Each time the client calls Monitor::release the client sends an ack message to the server every ackAny events. The server uses this to delay sending new monitors if the monitor queue is full.

pvAccessCPP/testApp/remote/pipelineServiceExample.cpp Is an example. It has an additional record option record[limit=n] which makes the server call unlisten aften n events.

pipelineServer

This is a class used by a pipeline service. It implements channelProvider for the service and provides a context for running the service.

class PipelineServer 
{
    void registerService(string const & serviceName, PipelineServicePtr const & service);
    void unregisterService(string const & serviceName);
    void run(int seconds = 0);
    /// Method requires usage of std::tr1::shared_ptr&lt;PipelineServer&gt;. This instance must be
    /// owned by a shared_ptr instance.
    void runInNewThread(int seconds = 0);
    void destroy();    
    void printInfo();
};

// private helper method, will (can) be removed in the future
ChannelPtr createPipelineChannel(ChannelProviderPtr const & provider,
    string const & channelName,
    ChannelRequesterPtr const & channelRequester,
    PipelineServicePtr const & pipelineService);
where
registerService
Register a new service.
unregisterService
Unregister the service.
run
Calls server context run.
runInNewThread
Starts a new thread.
destroy
Calls server context destroy.
printInfo
Shows the channel and connection status.

pipelineService

PipelineControl

An instance of PipelineControl is created by PipelineServer and passed to PipelineService::request.

class PipelineControl
{
    virtual size_t getFreeElementCount() = 0;
    virtual size_t getRequestedCount() = 0;
    virtual epics::pvData::MonitorElement::shared_pointer getFreeElement() = 0;
    virtual void putElement(epics::pvData::MonitorElement::shared_pointer const & element) = 0;
    virtual void done() = 0;
};
where
getFreeElementCount
The number of free elements in the local queue.
A service can (should) full up the entire queue.
getRequestedCount
The total count of requested elements.
This is the minimum element count that a service should provide.
getFreeElement
Grab next free element.
A service should take this element, populate it with the data and return it back by calling putElement().
putElement
Put element on the local queue (an element to be sent to a client).
done
Call to notify that there is no more data to pipelined.
This call destroys the pipeline session, i. e. the current monitor. The client will have to create a new monitor in order to access the service again.

PipelineSession

An instance of PipelineSession is created PipelineService for each instance of the service.

class  PipelineSession
{
    virtual size_t getMinQueueSize() const = 0;
    virtual epics::pvData::Structure::const_shared_pointer getStructure() const = 0;
    virtual void request(PipelineControl::shared_pointer const & control, size_t elementCount) = 0;
    virtual void cancel() = 0;
};
where
getMinQueueSize
Returns (minimum) local queue size.
The actual local queue size = max( getMinQueueSize(), client queue size );
getStructure
Description of the structure used by this session.
request
Request for additional (!) elementCount elements
The service should eventually call PipelineControl.getFreeElement() and PipelineControl.putElement() to provide [PipelineControl.getRequestedCount(), PipelineControl.getFreeElementCount()] elements.
cancel
Cancel the session (called by the client).

PipelineService

This is called to create an instance of a service. Note that it returns an instance of PipelineSession, which must be implemented by the service.

class PipelineService
{
    virtual PipelineSessionPtr createPipeline(PVStructurePtr const & pvRequest) = 0;
};
where
createPipeline
Called to create a new instance of the service.