/* * Copyright information and license terms for this software can be * found in the file LICENSE that is included with the distribution */ #ifndef PVATESTCLIENT_H #define PVATESTCLIENT_H #include #include #include #include #include #include class epicsEvent; namespace epics {namespace pvAccess { class ChannelProvider; class Channel; class Monitor; class Configuration; }}//namespace epics::pvAccess //! See @ref pvac API namespace pvac { /** @defgroup pvac Client API * * PVAccess network client (or other epics::pvAccess::ChannelProvider) * * Usage: * * 1. Construct a ClientProvider * 2. Use the ClientProvider to obtain a ClientChannel * 3. Use the ClientChannel to begin an get, put, rpc, or monitor operation * * Code examples * * - @ref examples_getme * - @ref examples_putme * - @ref examples_monitorme * @{ */ class ClientProvider; //! Handle for in-progress get/put/rpc operation struct epicsShareClass Operation { struct Impl { virtual ~Impl() {} virtual std::string name() const =0; virtual void cancel() =0; virtual void show(std::ostream&) const =0; }; Operation() {} Operation(const std::tr1::shared_ptr&); ~Operation(); //! Channel name std::string name() const; //! Immediate cancellation. //! Does not wait for remote confirmation. void cancel(); bool valid() const { return !!impl; } #if __cplusplus>=201103L explicit operator bool() const { return valid(); } #else private: typedef bool (Operation::*bool_type)() const; public: operator bool_type() const { return valid() ? &Operation::valid : 0; } #endif void reset() { impl.reset(); } protected: friend epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const Operation& op); std::tr1::shared_ptr impl; }; //! Information on put completion struct epicsShareClass PutEvent { enum event_t { Fail, //!< request ends in failure. Check message Cancel, //!< request cancelled before completion Success, //!< It worked! } event; std::string message; //!< Check when event==Fail }; //! Information on get/rpc completion struct epicsShareClass GetEvent : public PutEvent { //! New data. NULL unless event==Success epics::pvData::PVStructure::const_shared_pointer value; //! Mask of fields in value which have been initialized by the server //! @since 6.1.0 epics::pvData::BitSet::const_shared_pointer valid; }; struct epicsShareClass InfoEvent : public PutEvent { //! Type description resulting from getField operation. NULL unless event==Success epics::pvData::FieldConstPtr type; }; struct MonitorSync; //! Handle for monitor subscription struct epicsShareClass Monitor { struct Impl; Monitor() {} Monitor(const std::tr1::shared_ptr&); ~Monitor(); //! Channel name std::string name() const; //! Immediate cancellation. /** Does not wait for remote confirmation. * @since Up to 7.0.0 also cleared root, changed, and overrun. After 7.0.0, these data members are left unchanged. **/ void cancel(); /** updates root, changed, overrun * * @return true if a new update was extracted from the queue. * @note This method does not block. * @note MonitorEvent::Data will not be repeated until poll()==false. * @post root!=NULL (after version 6.0.0) * @post root!=NULL iff poll()==true (In version 6.0.0) */ bool poll(); //! true if all events received. //! Check after poll()==false bool complete() const; /** Monitor update data. * * After version 6.0.0 * * Initially NULL, becomes !NULL the first time poll()==true. * The PVStructure pointed to be root will presist until * Monitor reconnect w/ type change. This can be detected * by comparing `root.get()`. references to root may be cached * subject to this test. * * In version 6.0.0 * * NULL except after poll()==true. poll()==false sets root=NULL. * references to root should not be stored between calls to poll(). */ epics::pvData::PVStructure::const_shared_pointer root; epics::pvData::BitSet changed, overrun; bool valid() const { return !!impl; } #if __cplusplus>=201103L explicit operator bool() const { return valid(); } #else private: typedef bool (Monitor::*bool_type)() const; public: operator bool_type() const { return valid() ? &Monitor::valid : 0; } #endif void reset() { impl.reset(); } private: std::tr1::shared_ptr impl; friend epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const Monitor& op); friend struct MonitorSync; }; //! Information on monitor subscription/queue change struct MonitorEvent { enum event_t { Fail=1, //!< subscription ends in an error Cancel=2, //!< subscription ends in cancellation Disconnect=4,//!< subscription interrupted due to loss of communication Data=8, //!< Data queue not empty. Call Monitor::poll() } event; std::string message; //!< set for event=Fail }; /** Subscription usable w/o callbacks * * Basic usage is to call wait() or test(). * If true is returned, then the 'event', 'root', 'changed', and 'overrun' * members have been updated with a new event. * Test 'event.event' first to find out which kind of event has occured. * * Note that wait()/test() methods are distinct from base class poll(). * wait()/test() check for the arrival of MonitorEvent * while poll() checks for the availability of data (eg. following a Data event). */ struct epicsShareClass MonitorSync : public Monitor { struct SImpl; MonitorSync() {} MonitorSync(const Monitor&, const std::tr1::shared_ptr&); ~MonitorSync(); //! wait for new event //! @returns true when a new event was received. //! false if wake() was called. bool wait(); //! wait for new event //! @return false on timeout bool wait(double timeout); //! check if new event is immediately available. //! Does not block. bool test(); //! Abort one call to wait(), either concurrent or future. //! Calls are queued. //! wait() will return with MonitorEvent::Fail. void wake(); //! most recent event //! updated only during wait() or poll() MonitorEvent event; private: std::tr1::shared_ptr simpl; }; //! information on connect/disconnect struct ConnectEvent { //! Is this a connection, or disconnection, event. bool connected; //! For connection events. This is the name provided by the peer (cf. epics::pvAccess::Channel::getRemoteAddress() ). //! @since >6.1.0 std::string peerName; }; //! Thrown by blocking methods of ClientChannel on operation timeout struct Timeout : public std::runtime_error { Timeout(); }; namespace detail { class PutBuilder; void registerRefTrack(); } /** Represents a single channel * * This class has two sets of methods, those which block for completion, and * those which use callbacks to signal completion. * * Those which block accept a 'timeout' argument (in seconds). * * Those which use callbacks accept a 'cb' argument and return an Operation or Monitor handle object. */ class epicsShareClass ClientChannel { #if defined(__GNUC__) && (__GNUC__ * 100 + __GNUC_MINOR__ < 305) public: // Impl is public only as a workaround on older GCC #endif struct Impl; private: std::tr1::shared_ptr impl; friend class ClientProvider; friend void detail::registerRefTrack(); friend epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const ClientChannel& op); ClientChannel(const std::tr1::shared_ptr& i) :impl(i) {} public: //! Channel creation options struct epicsShareClass Options { short priority; std::string address; Options(); bool operator<(const Options&) const; }; //! Construct a null channel. All methods throw. May later be assigned from a valid ClientChannel ClientChannel() {} /** Construct a ClientChannel using epics::pvAccess::ChannelProvider::createChannel() * * Does not block. * @throw std::logic_error if the provider is NULL or name is an empty string * @throw std::runtime_error if the ChannelProvider can't provide */ ClientChannel(const std::tr1::shared_ptr& provider, const std::string& name, const Options& opt = Options()); ~ClientChannel(); //! Channel name or an empty string std::string name() const; bool valid() const { return !!impl; } #if __cplusplus>=201103L explicit operator bool() const { return valid(); } #else private: typedef bool (ClientChannel::*bool_type)() const; public: operator bool_type() const { return valid() ? &ClientChannel::valid : 0; } #endif void reset() { impl.reset(); } //! callback for get() and rpc() struct GetCallback { virtual ~GetCallback() {} //! get or rpc operation is complete virtual void getDone(const GetEvent& evt)=0; }; //! Issue request to retrieve current PV value //! @param cb Completion notification callback. Must outlive Operation (call Operation::cancel() to force release) //! @param pvRequest if NULL defaults to "field()". Operation get(GetCallback* cb, epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer()); //! Block and retrieve current PV value //! @param timeout in seconds //! @param pvRequest if NULL defaults to "field()". //! @throws Timeout or std::runtime_error epics::pvData::PVStructure::const_shared_pointer get(double timeout = 3.0, epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer()); //! Start an RPC call //! @param cb Completion notification callback. Must outlive Operation (call Operation::cancel() to force release) //! @param arguments encoded call arguments //! @param pvRequest if NULL defaults to "field()". Operation rpc(GetCallback* cb, const epics::pvData::PVStructure::const_shared_pointer& arguments, epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer()); //! Block and execute remote call //! @param timeout in seconds //! @param arguments encoded call arguments //! @param pvRequest if NULL defaults to "field()". epics::pvData::PVStructure::const_shared_pointer rpc(double timeout, const epics::pvData::PVStructure::const_shared_pointer& arguments, epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer()); //! callbacks for put() struct PutCallback { virtual ~PutCallback() {} struct Args { Args(epics::pvData::BitSet& tosend, epics::pvData::BitSet& previousmask) :tosend(tosend), previousmask(previousmask) {} //! Callee must fill this in with an instance of the Structure passed as the 'build' argument. epics::pvData::PVStructure::const_shared_pointer root; //! Callee must set bits corresponding to the fields of 'root' which will actually be sent. epics::pvData::BitSet& tosend; //! A previous value of the PV being "put" when put(..., getprevious=true). eg. use to find enumeration value. //! Otherwise NULL. //! @note The value of the PV may change between the point where "previous" is fetched, //! and when this Put operation completes. //! @since 6.1.0 Added after 6.0.0 epics::pvData::PVStructure::const_shared_pointer previous; //! Bit mask indicating those fields of 'previous' which have been set by the server. (others have local defaults) //! Unused if previous==NULL. const epics::pvData::BitSet& previousmask; }; /** Server provides expected structure. * * Implementation must instanciate (or re-use) a PVStructure into args.root, * then initialize any necessary fields and set bits in args.tosend as approprate. * * If this method throws, then putDone() is called with PutEvent::Fail */ virtual void putBuild(const epics::pvData::StructureConstPtr& build, Args& args) =0; //! Put operation is complete virtual void putDone(const PutEvent& evt)=0; }; //! Initiate request to change PV //! @param cb Completion notification callback. Must outlive Operation (call Operation::cancel() to force release) //! @param pvRequest if NULL defaults to "field()". //! @param getprevious If true, fetch a previous value of the PV and make //! this available as PutCallback::Args::previous and previousmask. //! If false, then previous=NULL Operation put(PutCallback* cb, epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer(), bool getprevious = false); //! Synchronious put operation inline detail::PutBuilder put(const epics::pvData::PVStructure::const_shared_pointer &pvRequest = epics::pvData::PVStructure::const_shared_pointer()); //! Monitor event notification struct MonitorCallback { virtual ~MonitorCallback() {} /** New monitor event * * - MonitorEvent::Fail - An Error occurred. Check evt.message * - MonitorEvent::Cancel - Monitor::cancel() called * - MonitorEvent::Disconnect - Underlying ClientChannel becomes disconnected * - MonitorEvent::Data - FIFO becomes not empty.Call Monitor::poll() */ virtual void monitorEvent(const MonitorEvent& evt)=0; }; //! Begin subscription //! @param cb Completion notification callback. Must outlive Monitor (call Monitor::cancel() to force release) Monitor monitor(MonitorCallback *cb, epics::pvData::PVStructure::const_shared_pointer pvRequest = epics::pvData::PVStructure::const_shared_pointer()); /** Begin subscription w/o callbacks * * @param event If not NULL, then subscription events are signaled to this epicsEvent. * Use MonitorSync::test() to see if a subscription has an event waiting. * Otherwise an internal epicsEvent is allocated for use with MonitorSync::wait() * * @note For simple usage with a single MonitorSync, pass event=NULL and call MonitorSync::wait(). * If more than one MonitorSync is being created, then pass a custom epicsEvent and use MonitorSync::test() to find * which subscriptions have events pending. */ MonitorSync monitor(const epics::pvData::PVStructure::const_shared_pointer& pvRequest = epics::pvData::PVStructure::const_shared_pointer(), epicsEvent *event =0); struct InfoCallback { virtual ~InfoCallback() {} //! getField operation is complete virtual void infoDone(const InfoEvent& evt) =0; }; //! Request PV type info. //! @note This type may not be the same as the types used in the get/put/monitor operations. Operation info(InfoCallback *cb, const std::string& subfld = std::string()); //! Synchronious getField opreation epics::pvData::FieldConstPtr info(double timeout = 3.0, const std::string& subfld = std::string()); //! Connection state change CB struct ConnectCallback { virtual ~ConnectCallback() {} virtual void connectEvent(const ConnectEvent& evt)=0; }; //! Append to list of listeners //! @param cb Channel dis/connect notification callback. Must outlive ClientChannel or call to removeConnectListener() void addConnectListener(ConnectCallback*); //! Remove from list of listeners void removeConnectListener(ConnectCallback*); void show(std::ostream& strm) const; private: std::tr1::shared_ptr getChannel(); }; namespace detail { //! Helper to accumulate values to for a Put operation. //! Make sure to call exec() to begin operation. class epicsShareClass PutBuilder { ClientChannel& channel; epics::pvData::PVStructure::const_shared_pointer request; template struct triple { std::string name; bool required; V value; triple(const std::string& name, const V& value, bool required =true) :name(name), required(required), value(value) {} }; typedef std::list > scalars_t; scalars_t scalars; typedef std::list > > arrays_t; arrays_t arrays; struct Exec; friend class pvac::ClientChannel; PutBuilder(ClientChannel& channel, const epics::pvData::PVStructure::const_shared_pointer& request) :channel(channel), request(request) {} public: PutBuilder& set(const std::string& name, const epics::pvData::AnyScalar& value, bool required=true) { scalars.push_back(scalars_t::value_type(name, value, required)); return *this; } template PutBuilder& set(const std::string& name, T value, bool required=true) { return set(name, epics::pvData::AnyScalar(value), required); } PutBuilder& set(const std::string& name, const epics::pvData::shared_vector& value, bool required=true) { arrays.push_back(arrays_t::value_type(name, value, required)); return *this; } template PutBuilder& set(const std::string& name, const epics::pvData::shared_vector& value, bool required=true) { return set(name, epics::pvData::static_shared_vector_cast(value), required); } void exec(double timeout=3.0); }; }// namespace detail //! Central client context. class epicsShareClass ClientProvider { struct Impl; std::tr1::shared_ptr impl; friend void detail::registerRefTrack(); friend epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const ClientProvider& op); public: //! Construct a null provider. All methods throw. May later be assigned from a valid ClientProvider ClientProvider() {} /** Use named provider. * * @param providerName ChannelProvider name, may be prefixed with "clients:" or "servers:" to query * epics::pvAccess::ChannelProviderRegistry::clients() or * epics::pvAccess::ChannelProviderRegistry::servers(). * No prefix implies "clients:". */ ClientProvider(const std::string& providerName, const std::tr1::shared_ptr& conf = std::tr1::shared_ptr()); explicit ClientProvider(const std::tr1::shared_ptr& provider); ~ClientProvider(); std::string name() const; /** Get a new Channel * * Does not block. * Never returns NULL. * Uses internal Channel cache. */ ClientChannel connect(const std::string& name, const ClientChannel::Options& conf = ClientChannel::Options()); //! Remove from channel cache bool disconnect(const std::string& name, const ClientChannel::Options& conf = ClientChannel::Options()); //! Clear channel cache void disconnect(); bool valid() const { return !!impl; } #if __cplusplus>=201103L explicit operator bool() const { return valid(); } #else private: typedef bool (ClientProvider::*bool_type)() const; public: operator bool_type() const { return valid() ? &ClientProvider::valid : 0; } #endif void reset() { impl.reset(); } }; detail::PutBuilder ClientChannel::put(const epics::pvData::PVStructure::const_shared_pointer& pvRequest) { return detail::PutBuilder(*this, pvRequest); } epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const Operation& op); epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const Monitor& op); epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const ClientChannel& op); epicsShareFunc ::std::ostream& operator<<(::std::ostream& strm, const ClientProvider& op); //! @} }//namespace pvac #endif // PVATESTCLIENT_H