1 /*---------------------------------------------------------------------\
3 | |__ / \ / / . \ . \ |
8 \---------------------------------------------------------------------*/
9 /** \file zypp/PluginScript.h
12 #ifndef ZYPP_PLUGINSCRIPT_H
13 #define ZYPP_PLUGINSCRIPT_H
19 #include "zypp/base/PtrTypes.h"
20 #include "zypp/Pathname.h"
22 #include "zypp/PluginFrame.h"
23 #include "zypp/PluginScriptException.h"
25 ///////////////////////////////////////////////////////////////////
27 { /////////////////////////////////////////////////////////////////
30 * \brief Interface to plugin scripts using a \c Stomp inspired communication protocol.
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
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).
41 * // Setup comnnection to plugin script
43 * PluginScript::Arguments args;
44 * args.push_back( "-v" );
45 * scr.open( "/soem/testplugin", args );
47 * // send frame to plugin
48 * PluginFrame f( "COMMAND" );
49 * f.setHeader( "key", "value" );
50 * f.setBody( "some\ndata" );
53 * // receive frame from plugin
54 * PluginFrame r( scr.receive() );
56 * // explicitly close or let PluginScript go out of scope
60 * \see http://stomp.codehaus.org/
64 friend std::ostream & operator<<( std::ostream & str, const PluginScript & obj );
67 /** Commandline arguments passed to a script on \ref open. */
68 typedef std::vector<std::string> Arguments;
70 /** \c pid_t(-1) constant indicating no connection. */
71 static const pid_t NotConnected;
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).
80 /** Global default timeout (sec.) when sending data. */
81 static long defaultSendTimeout();
83 /** Global default timeout (sec.) when receiving data. */
84 static long defaultReceiveTimeout();
86 /** Set global default timeout (sec.) when sending data. */
87 static void defaultSendTimeout( long newval_r );
89 /** Set global default timeout (sec.) when receiving data. */
90 static void defaultReceiveTimeout( long newval_r );
92 /** Set global default timeout (sec.) (both: send and receive).*/
93 static void defaultTimeout( long newval_r )
94 { defaultSendTimeout( newval_r ); defaultReceiveTimeout( newval_r ); }
101 /** Ctor taking script path and no arguments. */
102 PluginScript( const Pathname & script_r );
104 /** Ctor taking script path and script arguments. */
105 PluginScript( const Pathname & script_r, const Arguments & args_r );
108 /** Return the script path if set. */
109 const Pathname & script() const;
111 /** Return the script arguments if set. */
112 const Arguments & args() const;
114 /** Whether we are connected to a script. */
117 /** Return a connected scripts pid or \ref NotConnected. */
118 pid_t getPid() const;
120 /** Remembers a scripts return value after \ref close until next \ref open. */
121 int lastReturn() const;
123 /** Remembers a scripts execError string after \ref close until next \ref open.
124 * \see \ref ExternalProgram::execError.
126 const std::string & lastExecError() const;
129 /** \name Get/set local timeout settings. */
131 /** Local default timeout (sec.) when sending data. */
132 long sendTimeout() const;
134 /** Local default timeout (sec.) when receiving data. */
135 long receiveTimeout() const;
137 /** Set local default timeout (sec.) when sending data. */
138 void sendTimeout( long newval_r );
140 /** Set local default timeout (sec.) when receiving data. */
141 void receiveTimeout( long newval_r );
143 /** Set local default timeout (sec.) (both: send and receive).*/
144 void timeout( long newval_r )
145 { sendTimeout( newval_r ); receiveTimeout( newval_r ); }
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
156 /** \overload taking script path and no arguments. */
157 void open( const Pathname & script_r );
159 /** \overload taking script path and script arguments. */
160 void open( const Pathname & script_r, const Arguments & args_r );
162 /** Close any open connection. */
166 /** Send a \ref PluginFrame.
167 * \throw PluginScriptNotConnected
168 * \throw PluginScriptSendTimeout
169 * \throw PluginScriptDiedUnexpectedly (does not \ref close)
170 * \throw PluginScriptException on error
173 void send( const PluginFrame & frame_r ) const;
175 /** Receive a \ref PluginFrame.
176 * \throw PluginScriptNotConnected
177 * \throw PluginScriptReceiveTimeout
178 * \throw PluginScriptDiedUnexpectedly (does not \ref close)
179 * \throw PluginScriptException on error
181 PluginFrame receive() const;
184 /** Implementation. */
187 /** Pointer to implementation. */
188 RW_pointer<Impl> _pimpl;
191 /** \relates PluginScript Stream output */
192 std::ostream & operator<<( std::ostream & str, const PluginScript & obj );
194 /////////////////////////////////////////////////////////////////
196 ///////////////////////////////////////////////////////////////////
197 #endif // ZYPP_PLUGINSCRIPT_H