pvxs/documentation/client.rst

Client

pvxs::client::Context represents a PVA protocol client. :

#include <pvxs/client.h>
namespace pvxs { namespace client { ... } }

Configuration

The recommended starting point is creating new context configured from $PVA_* environment variables. Use pvxs::server::Config::from_env and then pvxs::server::Config::build.

EPICS_PVA_ADDR_LIST

A list of destination addresses to which UDP search messages will be sent. May contain unicast and/or broadcast addresses.

EPICS_PVA_AUTO_ADDR_LIST

If "YES" then all local broadcast addresses will be implicitly appended to $EPICS_PVA_ADDR_LIST "YES" if unset.

EPICS_PVA_BROADCAST_PORT

Default UDP port to which UDP searches will be sent. 5076 if unset.

using namespace pvxs;
client::Context ctxt = client::Config::from_env().build();

Programatic configuration can be accomplished by explicitly filling in a pvxs::server::Config.

Making Requests

The basic form of pvxs::client::Context usage is to invoke one of the info(), get(), put(), rpc(), or monitor() methods. Each of these methods returns a *Builder object which can be used to provide additional configuration in what are in effected named arguments.

pvxs::client::detail::CommonBuilder provides the arguments/methods common to all network operation types.

Get/Info

pvxs::client::Context::info and pvxs::client::Context::get return a pvxs::client::GetBuilder to prepare either a get() or info() (GET_FIELD) operation. The practical difference being that info() yields a Value which will never have any fields marked.

Put

pvxs::client::Context::put returns a pvxs::client::PutBuilder to prepare a put() operation. In the generic form of put(), the field values to sent have to be passed to the builder callback. This is necessary as the server mandated PV type definition is not known when an Put operation is initiated.

Additionally, a put operation will by default first fetch the present value of the PV and provide it to the builder callback. This allows eg. to perform string to index lookup when writing to an NTEnum.

RPC

pvxs::client::Context::rpc returns a pvxs::client::RPCBuilder to prepare an rpc() operation. rpc() differs from put() in that the call determines the type definition by providing a Value directly, so no builder callback is needed.

Operation and Result

The exec() method of the *Builder objects returns a shared_ptr to an pvxs::client::Operation handle, which represents the in-progress network operation. The caller must retain this handle until completion, or the operation will be implicitly cancelled.

When an Operation completes, a pvxs::client::Result is passed to the result() callback. This object holds either a pvxs::Value if the operation succeeded, or an exception.

pvxs::client::Context

pvxs::client::detail::CommonBuilder

pvxs::client::GetBuilder

pvxs::client::PutBuilder

pvxs::client::RPCBuilder

pvxs::client::Operation

pvxs::client::Result

As an alternative to pvxs::server::Config::from_env a Config may be created and filled in programatically.

pvxs::client::Config

pvxs::client::Disconnect

pvxs::client::RemoteError