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   //
  31   //    CLASS NAME : PluginScript
  32   //
  33   /**
  34    * \brief Interface to pluigin scripts using a \c Stomp inspired communication protocol
  35    *
  36    * \note \ref PluginScript is copyable and assignable, but the connection is shared
  37    * among multiple copies. It gets automatically closed if the last copy goes out of
  38    * scope.
  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 = -1;
  72
  73     public:
  74       /** Default ctor */
  75       PluginScript();
  76
  77       /** Ctor taking script path and no arguments */
  78       PluginScript( const Pathname & script_r );
  79
  80       /** Ctor taking script path and script arguments */
  81       PluginScript( const Pathname & script_r, const Arguments & args_r );
  82
  83     public:
  84       /** Return the script path if set */
  85       const Pathname & script() const;
  86
  87       /** Return the script arguments if set */
  88       const Arguments & args() const;
  89
  90       /** Whether we are connected to a script */
  91       bool isOpen() const;
  92
  93       /** Return a connected scripts pid or \ref NotConnected */
  94       pid_t getPid() const;
  95
  96     public:
  97       /** Setup connection and execute script
  98        * \throw PluginScriptException if already connected to a script
  99        * \throw PluginScriptException if script does not exist or is not executable
 100        * \throw PluginScriptException on error
 101        */
 102       void open();
 103
 104       /** \overload taking script path and no arguments */
 105       void open( const Pathname & script_r );
 106
 107       /** \overload taking script path and script arguments */
 108       void open( const Pathname & script_r, const Arguments & args_r );
 109
 110       /** Close any open connection. */
 111       void close();
 112
 113     public:
 114       /** Send a \ref PluginFrame
 115        * \throw PluginScriptException on error
 116        */
 117       void send( const PluginFrame & frame_r ) const;
 118
 119       /** Receive a \ref PluginFrame
 120        * \throw PluginScriptException on error
 121        */
 122       PluginFrame receive() const;
 123
 124     public:
 125       /** Implementation  */
 126       class Impl;
 127     private:
 128       /** Pointer to implementation */
 129       RW_pointer<Impl> _pimpl;
 130   };
 131   ///////////////////////////////////////////////////////////////////
 132
 133   /** \relates PluginScript Stream output */
 134   std::ostream & operator<<( std::ostream & str, const PluginScript & obj );
 135
 136   /////////////////////////////////////////////////////////////////
 137 } // namespace zypp
 138 ///////////////////////////////////////////////////////////////////
 139 #endif // ZYPP_PLUGINSCRIPT_H