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