1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef _VOS_PROCESS_HXX_ 25 #define _VOS_PROCESS_HXX_ 26 27 # include <rtl/ustring.hxx> 28 # include <vos/mutex.hxx> 29 # include <vos/security.hxx> 30 # include <vos/object.hxx> 31 # include <vos/socket.hxx> 32 # include <osl/process.h> 33 34 namespace vos 35 { 36 37 class OProcess; 38 39 /** helper class to fill a vector of command line arguments 40 */ 41 class OArgumentList 42 { 43 sal_uInt32 n_Args; 44 rtl_uString** m_aVec; 45 46 public: 47 48 OArgumentList(); 49 OArgumentList( sal_uInt32 nArgs, const ::rtl::OUString* aArgument1, ... ); 50 // switched argument list to avoid ambiguity with previous constructor. 51 OArgumentList( const ::rtl::OUString aArgumentList[], sal_uInt32 nArgs ); 52 53 OArgumentList( const OArgumentList& rOther); 54 55 OArgumentList& operator=( const OArgumentList& rOther); 56 57 virtual ~OArgumentList(); 58 59 friend class OProcess; 60 }; 61 62 /** helper class to fill a vector of environment settings 63 */ 64 class OEnvironment 65 { 66 sal_Int32 n_Vars; 67 rtl_uString** m_aVec; 68 69 public: 70 71 OEnvironment(); 72 OEnvironment( sal_Int32 nVars, const ::rtl::OUString* aVariable1, ... ); 73 // switched argument list to avoid ambiguity with previous constructor. 74 OEnvironment( const ::rtl::OUString aVariableList[], sal_Int32 nVars ); 75 76 OEnvironment( const OEnvironment& rOther ); 77 78 OEnvironment& operator=( const OEnvironment& rOther ); 79 80 virtual ~OEnvironment(); 81 82 friend class OProcess; 83 }; 84 85 86 /** startup child processes. 87 @see OStartupInfo 88 Used for starting an monitoring child processes with special features: 89 <ul><li>setting enviroments, 90 <li>setting working directories, 91 <li>setting user rights and security, 92 <li>providing ioresources like file descriptors and sockets.</ul> 93 */ 94 class OProcess : public OObject 95 { 96 VOS_DECLARE_CLASSINFO(VOS_NAMESPACE(OProcess, vos)); 97 98 public: 99 100 /** Options for execution mode: 101 */ 102 enum TProcessOption 103 { 104 TOption_Wait = osl_Process_WAIT, // wait for completion 105 TOption_SearchPath = osl_Process_SEARCHPATH, // search path for executable 106 TOption_Detached = osl_Process_DETACHED, // run detached 107 TOption_Normal = osl_Process_NORMAL, // run in normal window 108 TOption_Hidden = osl_Process_HIDDEN, // run hidden 109 TOption_Minimized = osl_Process_MINIMIZED, // run in minimized window 110 TOption_Maximized = osl_Process_MAXIMIZED, // run in maximized window 111 TOption_FullScreen = osl_Process_FULLSCREEN // run in fullscreen window 112 }; 113 114 /** Errorcodes: 115 */ 116 enum TProcessError { 117 E_None = osl_Process_E_None, /* no error */ 118 E_NotFound = osl_Process_E_NotFound, /* image not found */ 119 E_TimedOut = osl_Process_E_TimedOut, /* timout occured */ 120 E_NoPermission = osl_Process_E_NoPermission, /* permission denied */ 121 E_Unknown = osl_Process_E_Unknown, /* unknown error */ 122 E_InvalidError = osl_Process_E_InvalidError /* unmapped error */ 123 }; 124 125 enum TDescriptorFlags 126 { 127 TFlags_None = osl_Process_DFNONE, 128 TFlags_Wait = osl_Process_DFWAIT 129 }; 130 131 enum TProcessData 132 { 133 TData_Identifier = osl_Process_IDENTIFIER, 134 TData_ExitCode = osl_Process_EXITCODE, 135 TData_CpuTimes = osl_Process_CPUTIMES, 136 TData_HeapUsage = osl_Process_HEAPUSAGE 137 }; 138 139 struct TProcessInfo : public oslProcessInfo 140 { TProcessInfovos::OProcess::TProcessInfo141 TProcessInfo() { Size = sizeof(*this); } 142 }; 143 144 typedef oslProcessIdentifier TProcessIdentifier; 145 146 /** Creating a process object by naming the executable. 147 Does not yet start the process. 148 @see execute 149 */ 150 151 OProcess( ); 152 153 OProcess(const ::rtl::OUString& strImageName); 154 155 OProcess(const ::rtl::OUString& strImageName, 156 const ::rtl::OUString& strWorkingDirectory); 157 158 /// destroying a process object 159 virtual ~OProcess(); 160 operator oslProcess()161 SAL_CALL operator oslProcess() 162 { return m_Process; } 163 operator oslProcess() const164 SAL_CALL operator oslProcess() const 165 { return m_Process; } 166 167 static OProcess* SAL_CALL getProcess(TProcessIdentifier Identifier); 168 169 /** execute the given process. 170 This process becomes a child of the caller. 171 If there are any ioresources provided from the calling process, this 172 function returns only, if the child process calls OStartupInfo::acceptIOResource(). 173 @param Options [in] describes the execution mode. 174 @return only not eNONE, if too much enviroments are added. 175 @see OStartupInfo::acceptIOResource 176 */ 177 TProcessError SAL_CALL execute(TProcessOption Options, 178 const OArgumentList& aArgumentList = OArgumentList(), 179 const OEnvironment& aEnvironment = OEnvironment() 180 ); 181 182 /** execute the given process with the specified security. 183 This process becomes a child of the caller. 184 The process is executed with the rights of the user, for whom the security object is created. 185 If there are any ioresources provided from the calling process, this 186 function returns only, if the child process calls OStartupInfo::acceptIOResource(). 187 @param Options [in] describes the execution mode. 188 @param Security [in] is a given security object for one logged in user. 189 @return eNONE, if the proccess could be executed, otherwise an errorcode. 190 @see OStartupInfo::acceptIOResource 191 */ 192 TProcessError SAL_CALL execute(TProcessOption Options, 193 const OSecurity &Security, 194 const OArgumentList& aArgumentList = OArgumentList(), 195 const OEnvironment& aEnvironment = OEnvironment() 196 ); 197 198 TProcessError SAL_CALL terminate(); 199 200 TProcessError SAL_CALL getInfo(TProcessData Data, TProcessInfo* pInfo) const; 201 202 static TProcessError SAL_CALL getCurrentInfo(TProcessData Data, TProcessInfo* pInfo); 203 204 /** wait for the completation of this child process 205 @return eNONE if child process exits, otherwise nothing. 206 */ 207 TProcessError SAL_CALL join(); 208 209 protected: 210 const ::rtl::OUString m_strImageName; 211 const ::rtl::OUString m_strDirectory; 212 213 oslProcess m_Process; 214 }; 215 216 /** informations for client processes provided by the parent. 217 @see OProcess 218 */ 219 220 221 class OStartupInfo : public OObject 222 { 223 VOS_DECLARE_CLASSINFO(VOS_NAMESPACE(OStartupInfo, vos)); 224 225 public: 226 /** Errorcodes: 227 */ 228 enum TStartupError { 229 E_None = osl_Process_E_None, /* no error */ 230 E_NotFound = osl_Process_E_NotFound, /* image not found */ 231 E_TimedOut = osl_Process_E_TimedOut, /* timout occured */ 232 E_NoPermission = osl_Process_E_NoPermission, /* permission denied */ 233 E_Unknown = osl_Process_E_Unknown, /* unknown error */ 234 E_InvalidError = osl_Process_E_InvalidError /* unmapped error */ 235 }; 236 237 /** Constructor. 238 */ 239 OStartupInfo(); 240 241 /** Destructor 242 */ 243 ~OStartupInfo(); 244 245 /** @return the number of command line arguments. 246 */ 247 sal_uInt32 SAL_CALL getCommandArgCount(); 248 249 /** get the nArg-th command argument passed to the main-function of this process. 250 @param nArg [in] the number of arguments to return. 251 @param strCommandArg [out] the string that receives the argument. 252 @return eNONE 253 */ 254 TStartupError SAL_CALL getCommandArg(sal_uInt32 nArg, ::rtl::OUString& strCommandArg); 255 256 TStartupError SAL_CALL getExecutableFile(::rtl::OUString& strImageName) 257 const; 258 259 /** Get the value of one enviroment variable. 260 @param Name [in] denotes the name of the variable to get. 261 @param Buffer [out] is the buffer where the value of this variable is returned. 262 @param Max [in] is the size of this buffer. 263 @return eNONE, if the variable exist in the enviroment, otherwise False. 264 */ 265 TStartupError SAL_CALL getEnvironment(const ::rtl::OUString& strVar, ::rtl::OUString& strValue); 266 }; 267 268 269 270 /** get extended arguments from command line and an argument file 271 the file name is given on the command line as "@filename" 272 (filename must be in our UNC notation!) 273 enumeration starts with 0 (i.e. argv[1]) 274 each line in the file will be treated as one argument 275 @see also OProcess and OStartupInfo 276 */ 277 278 class OExtCommandLineImpl; 279 280 class OExtCommandLine : public OObject 281 { 282 VOS_DECLARE_CLASSINFO(VOS_NAMESPACE(OExtCommandLine, vos)); 283 static vos::OExtCommandLineImpl* pExtImpl; 284 285 public: 286 287 /** Constructor. 288 */ 289 OExtCommandLine(); 290 291 /** Destructor 292 */ 293 virtual ~OExtCommandLine(); 294 295 /** @return the number of extended command line arguments. 296 */ 297 sal_uInt32 SAL_CALL getCommandArgCount(); 298 299 300 /** get the nArg-th extended command argument 301 @param nArg [in] the number of extended argument to return. 302 @param strCommandArg [out] the string that receives the argument. 303 @return sal_True if the nArg-th argument has been retriveded successfully 304 @return sal_False on all other cases 305 */ 306 sal_Bool SAL_CALL getCommandArg(sal_uInt32 nArg, ::rtl::OUString& strCommandArg); 307 308 309 }; 310 311 } 312 313 #endif // _VOS_PROCESS_HXX_ 314 315 316