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