1 /*****************************************************************************/ 2 /* Software Testing Automation Framework (STAF) */ 3 /* (C) Copyright IBM Corp. 2001 */ 4 /* */ 5 /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ 6 /*****************************************************************************/ 7 8 #ifndef STAF_Process 9 #define STAF_Process 10 11 #include "STAFOSTypes.h" 12 #include "STAFError.h" 13 #include <map> 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 /* Begin C language definitions */ 20 21 typedef enum STAFProcessConsoleMode_e 22 { 23 kSTAFProcessNewConsole = 0, 24 kSTAFProcessSameConsole = 1 25 } STAFProcessConsoleMode_t; 26 27 typedef enum STAFProcessConsoleFocus_e 28 { 29 kSTAFProcessBackground = 0, 30 kSTAFProcessForeground = 1, 31 kSTAFProcessMinimized = 2 32 } STAFProcessConsoleFocus_t; 33 34 typedef enum STAFProcessAuthenticationMode_e 35 { 36 kSTAFProcessAuthDisabled = 0, 37 kSTAFProcessAuthNone = 1, 38 kSTAFProcessAuthWindows = 2, 39 kSTAFProcessAuthPasswd = 3, 40 kSTAFProcessAuthShadow = 4, 41 kSTAFProcessAuthPam = 5 42 } STAFProcessAuthenticationMode_t; 43 44 typedef enum STAFProcessDisabledAuthAction_e 45 { 46 kSTAFProcessDisabledAuthIgnore = 0, 47 kSTAFProcessDisabledAuthError = 1 48 } STAFProcessDisabledAuthAction_t; 49 50 typedef enum STAFProcessCommandType_e 51 { 52 kSTAFProcessCommand = 0, 53 kSTAFProcessShell = 1 54 } STAFProcessCommandType_t; 55 56 typedef enum STAFProcessRedirectedIOMode_e 57 { 58 kSTAFProcessIONoRedirect = 0, 59 kSTAFProcessIOReadFile = 1, 60 kSTAFProcessIOReplaceFile = 2, 61 kSTAFProcessIOAppendFile = 3, 62 kSTAFProcessIOStdout = 4 63 } STAFProcessRedirectedIOMode_t; 64 65 typedef void (*STAFProcessEndCallback_t)(STAFProcessID_t pid, 66 STAFProcessHandle_t processHandle, 67 unsigned int returnCode, 68 void *data); 69 70 struct STAFProcessEndCallbackLevel1 71 { 72 STAFProcessEndCallback_t callback; 73 void *data; 74 }; 75 76 struct STAFProcessStartInfoLevel1 77 { 78 STAFStringConst_t command; 79 STAFStringConst_t parms; 80 STAFStringConst_t workdir; 81 STAFStringConst_t title; 82 STAFStringConst_t username; 83 STAFStringConst_t password; 84 STAFProcessRedirectedIOMode_t stdinMode; 85 STAFStringConst_t stdinRedirect; 86 STAFProcessRedirectedIOMode_t stdoutMode; 87 STAFStringConst_t stdoutRedirect; 88 STAFProcessRedirectedIOMode_t stderrMode; 89 STAFStringConst_t stderrRedirect; 90 STAFProcessConsoleFocus_t consoleFocus; 91 STAFProcessConsoleMode_t consoleMode; 92 STAFProcessDisabledAuthAction_t disabledAuthAction; 93 STAFProcessAuthenticationMode_t authMode; 94 STAFProcessCommandType_t commandType; 95 STAFStringConst_t shellCommand; 96 STAFStringConst_t workload; 97 char *environment; 98 unsigned int userEnvCount; 99 STAFStringConst_t *userEnvList; 100 STAFProcessEndCallbackLevel1 *callback; 101 }; 102 103 typedef enum STAFProcessStopMethod_e 104 { 105 kSTAFProcessStopWithSigKill = 0, 106 kSTAFProcessStopWithSigTerm = 1, 107 kSTAFProcessStopWithSigInt = 2, 108 kSTAFProcessStopWithSigKillAll = 3, 109 kSTAFProcessStopWithWM_CLOSE = 4, 110 kSTAFProcessStopWithSigTermAll = 5, 111 kSTAFProcessStopWithSigIntAll = 6 112 } STAFProcessStopMethod_t; 113 114 typedef enum STAFProcessStopFlag_e 115 { 116 // kSTAFProcessStopRequest means only processes started by STAF can be 117 // stopped (e.g. used by a PROCESS STOP request) 118 kSTAFProcessStopRequest = 0, 119 120 // kSTAFProcessKillRequest means any process (not just those started by 121 // STAF) can be killed (e.g. used by a PROCESS KILL request). 122 kSTAFProcessKillRequest = 1 123 124 } STAFProcessStopFlag_t; 125 126 127 struct STAFProcessEnvData 128 { STAFProcessEnvDataSTAFProcessEnvData129 STAFProcessEnvData() { /* Do Nothing */ } 130 STAFProcessEnvDataSTAFProcessEnvData131 STAFProcessEnvData(STAFString aEnvName, STAFString aEnvValue) 132 : envName(aEnvName), envValue(aEnvValue) 133 { /* Do Nothing */ } 134 135 STAFString envName; 136 STAFString envValue; 137 }; 138 139 typedef std::map<STAFString, STAFProcessEnvData> STAFProcessEnvMap; 140 141 142 /****************************************************************************/ 143 /* STAFProcessStart - Starts a process */ 144 /* */ 145 /* Accepts: (OUT) Pointer to process identifier */ 146 /* (OUT) Pointer to process handle */ 147 /* (IN) Pointer to process start data structure */ 148 /* (IN) The level of the processs start data structure */ 149 /* (IN) Process termination callback */ 150 /* (OUT) Pointer to operating system return code */ 151 /* */ 152 /* Returns: kSTAFOk, on success */ 153 /* other on error */ 154 /* */ 155 /* Notes: 1) The process identifier is only guaranteed to be unique while */ 156 /* the process is running. The process handle is guaranteed to */ 157 /* be unique so long as the handle is "open". */ 158 /****************************************************************************/ 159 STAFRC_t STAFProcessStart(STAFProcessID_t *processID, 160 STAFProcessHandle_t *processHandle, 161 void *startData, 162 unsigned int startDataLevel, 163 unsigned int *osRC); 164 165 STAFRC_t STAFProcessStart2(STAFProcessID_t *processID, 166 STAFProcessHandle_t *processHandle, 167 void *startData, 168 unsigned int startDataLevel, 169 unsigned int *osRC, 170 STAFString_t *errorBuffer); 171 172 173 /****************************************************************************/ 174 /* STAFProcessGetHandleFromID - Obtains a process handle given a process ID */ 175 /* */ 176 /* Accepts: (IN) Process identifier */ 177 /* (OUT) Pointer to process handle */ 178 /* (OUT) Pointer to operating system return code */ 179 /* */ 180 /* Returns: kSTAFOk, on success */ 181 /* other on error */ 182 /****************************************************************************/ 183 STAFRC_t STAFProcessGetHandleFromID(STAFProcessID_t processID, 184 STAFProcessHandle_t *processHandle, 185 unsigned int *osRC); 186 187 /****************************************************************************/ 188 /* STAFProcessGetHandleFromID2 - Obtains a process handle given a process ID */ 189 /* */ 190 /* Accepts: (IN) Process identifier */ 191 /* (OUT) Pointer to process handle */ 192 /* (IN) Stop flag (indicates if should "stop" a STAF process or */ 193 /* "kill" any process) */ 194 /* (OUT) Pointer to operating system return code */ 195 /* */ 196 /* Returns: kSTAFOk, on success */ 197 /* other on error */ 198 /****************************************************************************/ 199 STAFRC_t STAFProcessGetHandleFromID2(STAFProcessID_t processID, 200 STAFProcessHandle_t *processHandle, 201 STAFProcessStopFlag_t stopFlag, 202 unsigned int *osRC); 203 204 205 /****************************************************************************/ 206 /* STAFProcessIsRunning - Determines if a given process is still running */ 207 /* */ 208 /* Accepts: (IN) Process handle */ 209 /* (OUT) Pointer to running indicator */ 210 /* (0 = Not running, 1 = Running) */ 211 /* (OUT) Pointer to operating system return code */ 212 /* */ 213 /* Returns: kSTAFOk, on success */ 214 /* other on error */ 215 /****************************************************************************/ 216 STAFRC_t STAFProcessIsRunning(STAFProcessHandle_t processHandle, 217 unsigned int *isRunning, 218 unsigned int *osRC); 219 220 221 /****************************************************************************/ 222 /* STAFProcessStop - Stops a currently running process that was previously */ 223 /* started via STAF */ 224 /* */ 225 /* Accepts: (IN) Process identifier */ 226 /* (IN) Stop method */ 227 /* (OUT) Pointer to operating system return code */ 228 /* */ 229 /* Returns: kSTAFOk, on success */ 230 /* other on error */ 231 /****************************************************************************/ 232 STAFRC_t STAFProcessStop(STAFProcessID_t processID, 233 STAFProcessStopMethod_t method, 234 unsigned int *osRC); 235 236 /****************************************************************************/ 237 /* STAFProcessStop2 - Stops a currently running process. */ 238 /* Use STAFProcessStop2 if want to kill any running process (not just */ 239 /* processes started by STAF) by passing stopFlag kSTAFProcessKillRequest. */ 240 /* Has equivalent function as STAFProcessStop if pass stopFlag */ 241 /* kSTAFProcessStopRequest. */ 242 /* */ 243 /* Accepts: (IN) Process identifier */ 244 /* (IN) Stop method */ 245 /* (IN) Stop flag (indicates if should "stop" a STAF process or */ 246 /* "kill" any process) */ 247 /* (OUT) Pointer to operating system return code */ 248 /* */ 249 /* Returns: kSTAFOk, on success */ 250 /* other on error */ 251 /****************************************************************************/ 252 STAFRC_t STAFProcessStop2(STAFProcessID_t processID, 253 STAFProcessStopMethod_t method, 254 STAFProcessStopFlag_t flag, 255 unsigned int *osRC); 256 257 258 /****************************************************************************/ 259 /* STAFProcessRegisterEndCallback - Registers for a process ending callback */ 260 /* */ 261 /* Accepts: (IN) Process identifier */ 262 /* (IN) Process handle */ 263 /* (IN) Callback data */ 264 /* (IN) Callback data level */ 265 /* */ 266 /* Returns: kSTAFOk, on success */ 267 /* other on error */ 268 /****************************************************************************/ 269 STAFRC_t STAFProcessRegisterEndCallback(STAFProcessID_t processID, 270 STAFProcessHandle_t processHandle, 271 void *callback, 272 unsigned int callbackLevel); 273 274 275 /****************************************************************************/ 276 /* STAFProcessIsValidAuthMode - Determines if authentication mode is valid */ 277 /* */ 278 /* Accepts: (IN) Process authentication mode */ 279 /* */ 280 /* Returns: kSTAFOk if valid */ 281 /* other if invalid */ 282 /****************************************************************************/ 283 STAFRC_t STAFProcessIsValidAuthMode(STAFProcessAuthenticationMode_t authMode); 284 285 286 /****************************************************************************/ 287 /* STAFProcessIsValidStopMethod - Determines if stop method is valid */ 288 /* */ 289 /* Accepts: (IN) Process stop using method */ 290 /* */ 291 /* Returns: kSTAFOk if valid */ 292 /* other if invalid */ 293 /****************************************************************************/ 294 STAFRC_t STAFProcessIsValidStopMethod(STAFProcessStopMethod_t stopMethod); 295 296 297 /* End C language definitions */ 298 299 #ifdef __cplusplus 300 } 301 302 // Begin C++ language definitions 303 304 // STAFProcess - This class provides a C++ wrapper around the STAF Process 305 // C APIs. 306 307 class STAFProcess 308 { 309 public: 310 311 // Retrieves the per-process-specific handle for a given process ID 312 static STAFRC_t getProcessHandleFromID(STAFProcessID_t processID, 313 STAFProcessHandle_t &procHandle, 314 unsigned int &osRC); 315 316 // Determines if a given process is still running 317 static bool isRunning(STAFProcessHandle_t processHandle); 318 319 // Determines if a given process authentication mode is valid 320 static STAFRC_t isValidAuthMode(STAFProcessAuthenticationMode_t authMode); 321 322 // Determines if a given process stop method is valid 323 static STAFRC_t isValidStopMethod(STAFProcessStopMethod_t stopMethod); 324 325 // Register for a callback when an arbitrary process terminates 326 static STAFRC_t registerForProcessTermination( 327 STAFProcessID_t pid, 328 STAFProcessHandle_t procHandle, 329 STAFProcessEndCallbackLevel1 &callback); 330 331 // Starts a process and registers callback routine that gets 332 // invoked when process terminates 333 334 static STAFRC_t startProcess(STAFProcessStartInfoLevel1 &startInfo, 335 STAFProcessID_t &pid, 336 STAFProcessHandle_t &procHandle, 337 unsigned int &osRC); 338 339 // Use startProcess2 instead of startProcess to get more information 340 // when an error occurs assigned to the errorBuffer. 341 342 static STAFRC_t startProcess2(STAFProcessStartInfoLevel1 &startInfo, 343 STAFProcessID_t &pid, 344 STAFProcessHandle_t &procHandle, 345 unsigned int &osRC, STAFString &errorBuffer); 346 347 // Stops a process that was previously started by STAF 348 static STAFRC_t stopProcess(STAFProcessID_t pid, 349 STAFProcessStopMethod_t stopType, 350 unsigned int &osRC); 351 352 // Use stopProcess2 if want to kill any running process (not just 353 // processes started by STAF) by passing stopFlag kSTAFProcessKillRequest. 354 // Has equivalent function as stopProcess if pass stopFlag 355 // kSTAFProcessStopRequest. 356 static STAFRC_t stopProcess2(STAFProcessID_t pid, 357 STAFProcessStopMethod_t stopType, 358 STAFProcessStopFlag_t stopFlag, 359 unsigned int &osRC); 360 361 private: 362 363 // Don't allow default construction, copy construction, or assignment 364 STAFProcess(); 365 STAFProcess (const STAFProcess& ); 366 STAFProcess& operator= (const STAFProcess& ); 367 }; 368 369 370 // Now include inline definitions 371 372 #ifndef STAF_NATIVE_COMPILER 373 #include "STAFProcessInlImpl.cpp" 374 #endif 375 376 // End C++ language definitions 377 378 // End #ifdef __cplusplus 379 #endif 380 381 #endif 382