/*
 * SPDX-FileCopyrightText: 2004 Copyright contributors to the cppTango project
 *
 * SPDX-License-Identifier: LGPL-3.0-or-later
 */
//+=============================================================================
//
// project :      TANGO Utility
// file :         DeviceProxyHelper.h:
//
//
//   description :  This utility class helps to use command_inout,read_attributes and write_attribute(s)
//                on a DeviceProxy , from a Tango C++ Client.
//                Its role is :
//                  - to provide syntactic sugar to avoid the heavy manipulation of DeviceData objects
//                            used to exchange data between a C++ client and a server
//                  - to handle exception in an uniform way using the TangoExceptionHelper.h file
//
// Usage examples :
//
//    Step 1)  create a DeviceProxyHelper object (in your client init_device for instance)
//
//    tangoCA = new DeviceProxyHelper("lucia/sls/tangoca",this);
//      ==>  A DeviceProxy is internally created by DeviceProxyHelper ( note : the this pointer is used for logging
//      purpose)
//
//    Step 2)  USE your remote Device !!
//
//     FOR COMMANDS (Note that  DEVVAR<X>STRINGARRAY argin or argout types are not supported)

//          There are 4 methods:
//            -command (no argin,no argout)
//            -command_in (only argin)
//            -command_out (only argout)
//            -command_inout (argin and argout)

//  Note :  the methods are Templates so you don't care about type (while they are supported by DeviceData!!!)
//
//  COMMAND EXAMPLES :
//                      a) execute Command Reset on the deviceProxy : No argin nor argout required
//                      tangoCA->command("Reset");
//
//                      b) execute Command GotoPosition on the deviceProxy with argin= 12.3
//                      tangoCA->command_in("GotoPosition", 12.3);
//
//                      c) execute Command ReadPosition on the deviceProxy : argout will be put in read_value
//                      tangoCA->command_out("ReadPosition", read_value);
//
//                      d) execute Command ReadDoublePv on the deviceProxy : verticalGapPV.c_str() is the argin and
//                      *attr_VerticalGap_read is the argout.
//                      tangoCA->command_inout("ReadDoublePV",verticalGapPV.c_str(),
//                                            *attr_VerticalGap_read)
//                          ==> Automatically  the CommandInOutHelper has done all the DeviceData encapsulation
//                             and transfers the result of the command_inout in your argout
//
//
//        Handling of composite type like DEVVAR<X>STRINGARRAY in argin and/or argout (with <X> = LONG or DOUBLE):
//           The <X> part and the STRING part must be seperated by user in two vectors, std::vector<X> and
//           std::vector<std::string>. The following must be called:
//
//        - command with argin only:
//               void command_in (
//                      const std::string& cmd_name,
//                      const std::vector<_IN>& _nv_in,           // numerical part of the input DEVVAR<X>STRINGARRAY
//                      const std::vector<std::string>& _sv_in    // string part of the input DEVVAR<X>STRINGARRAY
//                    )
//
//        - command with argout only:
//              void command_out (
//                       const std::string& cmd_name,
//                       std::vector<_OUT>& _nv_out,              // numerical part of the ouput DEVVAR<X>STRINGARRAY
//                       std::vector<std::string>& _sv_out        // string part of the ouput DEVVAR<X>STRINGARRAY
//                     )
//
//        - command with argin and argout:
//              void command_inout (
//                        const std::string& cmd_name,
//                        const std::vector<_IN>& _nv_in,         // numerical part of the input DEVVAR<X>STRINGARRAY
//                        const std::vector<std::string>& _sv_in, // string part of the input DEVVAR<X>STRINGARRAY
//                        std::vector<_OUT>& _nv_out,             // numerical part of the ouput DEVVAR<X>STRINGARRAY
//                        std::vector<std::string>& _sv_out       // string part of the ouput DEVVAR<X>STRINGARRAY
//                       )
//
//
//  ATTRIBUTES EXAMPLES :
//                      a) execute  read_attribute  on the deviceProxy and store value in omega_on_axis variable
//                             _omegaProxy_helper        ->read_attribute("AxisCurrentPosition" , omega_on_axis);
//
//                      b) execute  write_attribute  on the deviceProxy and with argin = 12.3
//                                    _omegaProxy_helper        ->    write_attribute("AxisCurrentPosition", 12.3);

//

#ifndef TANGO_CLIENT_HELPERS_DEVICEPROXYHELPER_H
#define TANGO_CLIENT_HELPERS_DEVICEPROXYHELPER_H

//=============================================================================
// DEPENDENCIES
//=============================================================================
#include <tango/client/DeviceProxy.h>
#include <tango/client/helpers/AttributeHelper.h>
#include <tango/client/helpers/CommandInOutHelper.h>
#include <tango/client/helpers/TangoExceptionsHelper.h>
#include <tango/server/LogAdapter.h>

namespace Tango
{
//=============================================================================
// CLASS: DeviceProxyHelper
//=============================================================================
class DeviceProxyHelper : public CommandInOutHelper, public AttributeHelper
{
  public:
    //---------------------------------------------------------------------------
    //  DeviceProxyHelper::DeviceProxyHelper  (ctor)
    //  device_name : name of the target device
    //  client_device : reference to the client device (for logging purpose)
    //---------------------------------------------------------------------------
    DeviceProxyHelper(const std::string &device_name, DeviceImpl *client_device = 0) :
        HelperBase(device_name, client_device),
        CommandInOutHelper(device_name, client_device),
        AttributeHelper(device_name, client_device)
    {
        //- noop ctor
    }

    //---------------------------------------------------------------------------
    //  DeviceProxyHelper::~DeviceProxyHelper (dtor)
    //---------------------------------------------------------------------------
    virtual ~DeviceProxyHelper()
    {
        //- noop dtor
    }
};

} // namespace Tango

#endif // TANGO_CLIENT_HELPERS_DEVICEPROXYHELPER_H
