zypp/PluginScript.h

   1 /*---------------------------------------------------------------------\
   2 |                          ____ _   __ __ ___                          |
   3 |                         |__  / \ / / . \ . \                         |
   4 |                           / / \ V /|  _/  _/                         |
   5 |                          / /__ | | | | | |                           |
   6 |                         /_____||_| |_| |_|                           |
   7 |                                                                      |
   8 \---------------------------------------------------------------------*/
   9 /** \file       zypp/PluginScript.h
  10  *
  11 */
  12 #ifndef ZYPP_PLUGINSCRIPT_H
  13 #define ZYPP_PLUGINSCRIPT_H
  14
  15 #include <iosfwd>
  16 #include <string>
  17 #include <vector>
  18
  19 #include "zypp/base/PtrTypes.h"
  20 #include "zypp/Pathname.h"
  21
  22 #include "zypp/PluginFrame.h"
  23 #include "zypp/PluginScriptException.h"
  24
  25 ///////////////////////////////////////////////////////////////////
  26 namespace zypp
  27 { /////////////////////////////////////////////////////////////////
  28
  29   /**
  30    * \brief Interface to plugin scripts using a \c Stomp inspired communication protocol.
  31    *
  32    * \note \ref PluginScript is copyable and assignable, but the connection is shared
  33    * among multiple copies. It gets automatically closed if the last copy goes out of
  34    * scope.
  35    *
  36    * Timeout when sending/receiving data to/from a plugin default to 30 sec. The value
  37    * (in seconds) my be changed via the environment variables \c ZYPP_PLUGIN_SEND_TIMEOUT,
  38    * \c ZYPP_PLUGIN_RECEIVE_TIMEOUT or \c ZYPP_PLUGIN_TIMEOUT (both: send and receive).
  39    *
  40    * \code
  41    *  // Setup comnnection to plugin script
  42    *  PluginScript scr;
  43    *  PluginScript::Arguments args;
  44    *  args.push_back( "-v" );
  45    *  scr.open( "/soem/testplugin", args );
  46    *
  47    *  // send frame to plugin
  48    *  PluginFrame f( "COMMAND" );
  49    *  f.setHeader( "key", "value" );
  50    *  f.setBody( "some\ndata" );
  51    *  scr.send( f );
  52    *
  53    *  // receive frame from plugin
  54    *  PluginFrame r( scr.receive() );
  55    *
  56    *  // explicitly close or let PluginScript go out of scope
  57    *  scr.close();
  58    * \endcode
  59    *
  60    * \see http://stomp.codehaus.org/
  61    */
  62   class PluginScript
  63   {
  64     friend std::ostream & operator<<( std::ostream & str, const PluginScript & obj );
  65
  66     public:
  67       /** Commandline arguments passed to a script on \ref open. */
  68       typedef std::vector<std::string> Arguments;
  69
  70       /** \c pid_t(-1) constant indicating no connection. */
  71       static const pid_t NotConnected;
  72
  73     public:
  74       /** \name Get/set the global timeout settings.
  75        * Timeout when sending/receiving data to/from a plugin default to 30 sec. The value
  76        * (in seconds) my be changed via the environment variables \c ZYPP_PLUGIN_SEND_TIMEOUT,
  77        * \c ZYPP_PLUGIN_RECEIVE_TIMEOUT or \c ZYPP_PLUGIN_TIMEOUT (both: send and receive).
  78        */
  79       //@{
  80         /** Global default timeout (sec.) when sending data. */
  81         static long defaultSendTimeout();
  82
  83         /** Global default timeout (sec.) when receiving data. */
  84         static long defaultReceiveTimeout();
  85
  86         /** Set global default timeout (sec.) when sending data. */
  87         static void defaultSendTimeout( long newval_r );
  88
  89         /** Set global default timeout (sec.) when receiving data. */
  90         static void defaultReceiveTimeout( long newval_r );
  91
  92         /** Set global default timeout (sec.) (both: send and receive).*/
  93         static void defaultTimeout( long newval_r )
  94         { defaultSendTimeout( newval_r ); defaultReceiveTimeout( newval_r ); }
  95       //@}
  96
  97     public:
  98       /** Default ctor. */
  99       PluginScript();
 100
 101       /** Ctor taking script path and no arguments. */
 102       PluginScript( const Pathname & script_r );
 103
 104       /** Ctor taking script path and script arguments. */
 105       PluginScript( const Pathname & script_r, const Arguments & args_r );
 106
 107     public:
 108       /** Return the script path if set. */
 109       const Pathname & script() const;
 110
 111       /** Return the script arguments if set. */
 112       const Arguments & args() const;
 113
 114       /** Whether we are connected to a script. */
 115       bool isOpen() const;
 116
 117       /** Return a connected scripts pid or \ref NotConnected. */
 118       pid_t getPid() const;
 119
 120       /** Remembers a scripts return value after \ref close until next \ref open. */
 121       int lastReturn() const;
 122
 123       /** Remembers a scripts execError string after \ref close until next \ref open.
 124        * \see \ref ExternalProgram::execError.
 125        */
 126       const std::string & lastExecError() const;
 127
 128      public:
 129       /** \name Get/set local timeout settings. */
 130       //@{
 131         /** Local default timeout (sec.) when sending data. */
 132         long sendTimeout() const;
 133
 134         /** Local default timeout (sec.) when receiving data. */
 135         long receiveTimeout() const;
 136
 137         /** Set local default timeout (sec.) when sending data. */
 138         void sendTimeout( long newval_r );
 139
 140         /** Set local default timeout (sec.) when receiving data. */
 141         void receiveTimeout( long newval_r );
 142
 143         /** Set local default timeout (sec.) (both: send and receive).*/
 144         void timeout( long newval_r )
 145         { sendTimeout( newval_r ); receiveTimeout( newval_r ); }
 146       //@}
 147
 148    public:
 149       /** Setup connection and execute script.
 150        * \throw PluginScriptException if already connected to a script
 151        * \throw PluginScriptException if script does not exist or is not executable
 152        * \throw PluginScriptException on error
 153        */
 154       void open();
 155
 156       /** \overload taking script path and no arguments. */
 157       void open( const Pathname & script_r );
 158
 159       /** \overload taking script path and script arguments. */
 160       void open( const Pathname & script_r, const Arguments & args_r );
 161
 162       /** Close any open connection. */
 163       int close();
 164
 165     public:
 166       /** Send a \ref PluginFrame.
 167        * \throw PluginScriptNotConnected
 168        * \throw PluginScriptSendTimeout
 169        * \throw PluginScriptDiedUnexpectedly (does not \ref close)
 170        * \throw PluginScriptException on error
 171        *
 172        */
 173       void send( const PluginFrame & frame_r ) const;
 174
 175       /** Receive a \ref PluginFrame.
 176        * \throw PluginScriptNotConnected
 177        * \throw PluginScriptReceiveTimeout
 178        * \throw PluginScriptDiedUnexpectedly (does not \ref close)
 179        * \throw PluginScriptException on error
 180        */
 181       PluginFrame receive() const;
 182
 183     public:
 184       /** Implementation. */
 185       struct Impl;
 186     private:
 187       /** Pointer to implementation. */
 188       RW_pointer<Impl> _pimpl;
 189   };
 190
 191   /** \relates PluginScript Stream output */
 192   std::ostream & operator<<( std::ostream & str, const PluginScript & obj );
 193
 194   /////////////////////////////////////////////////////////////////
 195 } // namespace zypp
 196 ///////////////////////////////////////////////////////////////////
 197 #endif // ZYPP_PLUGINSCRIPT_H