Exec.hpp

Go to the documentation of this file.
00001 /*******************************************************************************
00002 * Copyright (C) 2004 Vintela, Inc. All rights reserved.
00003 * Copyright (C) 2005 Novell, Inc. All rights reserved.
00004 *
00005 * Redistribution and use in source and binary forms, with or without
00006 * modification, are permitted provided that the following conditions are met:
00007 *
00008 *  - Redistributions of source code must retain the above copyright notice,
00009 *    this list of conditions and the following disclaimer.
00010 *
00011 *  - Redistributions in binary form must reproduce the above copyright notice,
00012 *    this list of conditions and the following disclaimer in the documentation
00013 *    and/or other materials provided with the distribution.
00014 *
00015 *  - Neither the name of Vintela, Inc., Novell, Inc., nor the names of its
00016 *    contributors may be used to endorse or promote products derived from this
00017 *    software without specific prior written permission.
00018 *
00019 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS''
00020 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00021 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00022 * ARE DISCLAIMED. IN NO EVENT SHALL Vintela, Inc., Novell, Inc., OR THE 
00023 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
00024 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
00025 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 
00026 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
00027 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
00028 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
00029 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030 *******************************************************************************/
00031 
00036 #ifndef BLOCXX_EXEC_HPP_
00037 #define BLOCXX_EXEC_HPP_
00038 #include "blocxx/BLOCXX_config.h"
00039 #include "blocxx/Types.hpp"
00040 #include "blocxx/IntrusiveReference.hpp"
00041 #include "blocxx/String.hpp"
00042 #include "blocxx/ArrayFwd.hpp"
00043 #include "blocxx/CommonFwd.hpp"
00044 #include "blocxx/EnvVars.hpp"
00045 
00046 namespace BLOCXX_NAMESPACE
00047 {
00048 
00049 BLOCXX_DECLARE_APIEXCEPTION(ExecTimeout, BLOCXX_COMMON_API);
00050 BLOCXX_DECLARE_APIEXCEPTION(ExecBufferFull, BLOCXX_COMMON_API);
00051 BLOCXX_DECLARE_APIEXCEPTION(ExecError, BLOCXX_COMMON_API);
00052 
00053 class PopenStreamsImpl;
00057 class BLOCXX_COMMON_API PopenStreams
00058 {
00059 public:
00060    PopenStreams();
00061    ~PopenStreams();
00062    PopenStreams(const PopenStreams& src);
00063    PopenStreams& operator=(const PopenStreams& src);
00067    UnnamedPipeRef in() const;
00068    
00072    void in(const UnnamedPipeRef& pipe);
00076    UnnamedPipeRef out() const;
00080    void out(const UnnamedPipeRef& pipe);
00084    UnnamedPipeRef err() const;
00088    void err(const UnnamedPipeRef& pipe);
00089 
00093    Array<UnnamedPipeRef> extraPipes() const;
00094 
00098    void setExtraPipes(const Array<UnnamedPipeRef>& pipes);
00099 
00104    ProcId pid() const;
00108    void pid(ProcId newPid);
00109 
00141    int getExitStatus(UInt32 wait_initial, UInt32 wait_close, UInt32 wait_term);
00142 
00146    int getExitStatus();
00147 
00152    void setProcessStatus(int ps);
00153 private:
00154    IntrusiveReference<PopenStreamsImpl> m_impl;
00155 
00156    friend bool operator==(const PopenStreams& x, const PopenStreams& y);
00157 };
00158 
00160 namespace Exec
00161 {
00187    BLOCXX_COMMON_API int safeSystem(const Array<String>& command,
00188       const char* const envp[] = 0);
00189 
00190    // TODO: Add a timeout to this and rewrite the impl to use safePopen()
00216    BLOCXX_COMMON_API int safeSystem(const Array<String>& command,
00217       const EnvVars& envVars);
00218    
00248    BLOCXX_COMMON_API PopenStreams safePopen(const Array<String>& command, const char* const envp[] = 0);
00249 
00279    BLOCXX_COMMON_API PopenStreams safePopen(const Array<String>& command, const EnvVars& envVars);
00280 
00281    // TODO: Create a version of safePopen that allows the caller to specify the number of extra pipes to be opened.
00282 
00288    BLOCXX_COMMON_API PopenStreams safePopen(const Array<String>& command,
00289          const String& initialInput) BLOCXX_DEPRECATED;
00290 
00291    const int INFINITE_TIMEOUT = -1;
00292 
00321    BLOCXX_COMMON_API void gatherOutput(String& output, PopenStreams& streams, int& processstatus, int timeoutsecs = INFINITE_TIMEOUT, int outputlimit = -1);
00322    
00323    enum EOutputSource
00324    {
00325       E_STDOUT,
00326       E_STDERR
00327    };
00328 
00329    class OutputCallback
00330    {
00331    public:
00332       virtual ~OutputCallback();
00333       void handleData(const char* data, size_t dataLen, EOutputSource outputSource, PopenStreams& theStream, size_t streamIndex, Array<char>& inputBuffer);
00334    private:
00339       virtual void doHandleData(const char* data, size_t dataLen, EOutputSource outputSource, PopenStreams& theStream, size_t streamIndex, Array<char>& inputBuffer) = 0;
00340    };
00341 
00342    class InputCallback
00343    {
00344    public:
00345       virtual ~InputCallback();
00346       void getData(Array<char>& inputBuffer, PopenStreams& theStream, size_t streamIndex);
00347    private:
00348       virtual void doGetData(Array<char>& inputBuffer, PopenStreams& theStream, size_t streamIndex) = 0;
00349    };
00350 
00351    enum EProcessRunning
00352    {
00353       E_PROCESS_RUNNING,
00354       E_PROCESS_EXITED
00355    };
00356 
00357    // class invariant: if m_running == E_PROCESS_RUNNING, then m_status == 0.
00358    class ProcessStatus
00359    {
00360    public:
00361       ProcessStatus()
00362       : m_running(E_PROCESS_RUNNING)
00363       , m_status(0)
00364       {
00365       }
00366 
00367       explicit ProcessStatus(int status)
00368       : m_running(E_PROCESS_EXITED)
00369       , m_status(status)
00370       {
00371       }
00372 
00373       bool hasExited() const
00374       {
00375          return m_running == E_PROCESS_EXITED;
00376       }
00377 
00378       const int& getStatus() const
00379       {
00380          return m_status;
00381       }
00382    private:
00383       EProcessRunning m_running;
00384       int m_status;
00385    };
00386 
00423    BLOCXX_COMMON_API void processInputOutput(OutputCallback& output, Array<PopenStreams>& streams, Array<ProcessStatus>& processStatuses,
00424       InputCallback& input, int timeoutSecs = INFINITE_TIMEOUT);
00425    
00485    BLOCXX_COMMON_API void executeProcessAndGatherOutput(
00486       const Array<String>& command,
00487       String& output, int& processstatus,
00488       int timeoutsecs = INFINITE_TIMEOUT, int outputlimit = -1, const String& input = String());
00489 
00552    BLOCXX_COMMON_API void executeProcessAndGatherOutput(
00553       const Array<String>& command,
00554       String& output, int& processstatus, const EnvVars& envVars,
00555       int timeoutsecs = INFINITE_TIMEOUT, int outputlimit = -1, const String& input = String());
00556 
00622    BLOCXX_COMMON_API void executeProcessAndGatherOutput(
00623       const Array<String>& command,
00624       String& stdOutput, String& errOutput, int& processstatus, const EnvVars& envVars,
00625       int timeoutsecs = INFINITE_TIMEOUT, int outputlimit = -1, const String& input = String());
00626 
00627 } // end namespace Exec
00628 
00629 } // end namespace BLOCXX_NAMESPACE
00630 
00631 #endif

Generated on Fri Jun 16 15:39:08 2006 for blocxx by  doxygen 1.4.6