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 25 #ifndef _OSL_PROCESS_H_ 26 #define _OSL_PROCESS_H_ 27 28 #include <rtl/ustring.h> 29 #include <rtl/textenc.h> 30 #include <rtl/locale.h> 31 32 #include <osl/time.h> 33 #include <osl/file.h> 34 #include <osl/pipe.h> 35 #include <osl/socket.h> 36 #include <osl/security.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 43 typedef sal_Int32 oslProcessOption; 44 #define osl_Process_WAIT 0x0001 /* wait for completion */ 45 #define osl_Process_SEARCHPATH 0x0002 /* search path for executable */ 46 #define osl_Process_DETACHED 0x0004 /* run detached */ 47 #define osl_Process_NORMAL 0x0000 /* run in normal window */ 48 #define osl_Process_HIDDEN 0x0010 /* run hidden */ 49 #define osl_Process_MINIMIZED 0x0020 /* run in minimized window */ 50 #define osl_Process_MAXIMIZED 0x0040 /* run in maximized window */ 51 #define osl_Process_FULLSCREEN 0x0080 /* run in fullscreen window */ 52 53 typedef sal_Int32 oslProcessData; 54 55 /* defines for osl_getProcessInfo , can be OR'ed */ 56 #define osl_Process_IDENTIFIER 0x0001 /* retrieves the process identifier */ 57 #define osl_Process_EXITCODE 0x0002 /* retrieves exit code of the process */ 58 #define osl_Process_CPUTIMES 0x0004 /* retrieves used cpu time */ 59 #define osl_Process_HEAPUSAGE 0x0008 /* retrieves the used size of heap */ 60 61 typedef sal_uInt32 oslProcessIdentifier; 62 typedef sal_uInt32 oslProcessExitCode; 63 64 typedef enum { 65 osl_Process_E_None, /* no error */ 66 osl_Process_E_NotFound, /* image not found */ 67 osl_Process_E_TimedOut, /* timout occurred */ 68 osl_Process_E_NoPermission, /* permission denied */ 69 osl_Process_E_Unknown, /* unknown error */ 70 osl_Process_E_InvalidError, /* unmapped error */ 71 osl_Process_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM 72 } oslProcessError; 73 74 typedef enum { 75 osl_Process_TypeNone, /* no descriptor */ 76 osl_Process_TypeSocket, /* socket */ 77 osl_Process_TypeFile, /* file */ 78 osl_Process_TypePipe, /* pipe */ 79 osl_Process_FORCE_EQUAL_SIZE = SAL_MAX_ENUM 80 } oslDescriptorType; 81 82 typedef sal_Int32 oslDescriptorFlag; 83 #define osl_Process_DFNONE 0x0000 84 #define osl_Process_DFWAIT 0x0001 85 86 #ifdef SAL_W32 87 # pragma pack(push, 8) 88 #elif defined(SAL_OS2) 89 # pragma pack(push, 4) 90 #endif 91 92 typedef struct { 93 sal_uInt32 Size; 94 oslProcessData Fields; 95 oslProcessIdentifier Ident; 96 oslProcessExitCode Code; 97 TimeValue UserTime; 98 TimeValue SystemTime; 99 sal_uInt32 HeapUsage; 100 } oslProcessInfo; 101 102 #if defined( SAL_W32) || defined(SAL_OS2) 103 # pragma pack(pop) 104 #endif 105 106 /** Process handle 107 108 @see osl_executeProcess 109 @see osl_terminateProcess 110 @see osl_freeProcessHandle 111 @see osl_getProcessInfo 112 @see osl_joinProcess 113 */ 114 typedef void* oslProcess; 115 116 /** Execute a process. 117 118 Executes the program image provided in strImageName in a new process. 119 120 @param ustrImageName 121 [in] The file URL of the executable to be started. 122 Can be NULL in this case the file URL of the executable must be the first element 123 in ustrArguments. 124 125 @param ustrArguments 126 [in] An array of argument strings. Can be NULL if strImageName is not NULL. 127 If strImageName is NULL it is expected that the first element contains 128 the file URL of the executable to start. 129 130 @param nArguments 131 [in] The number of arguments provided. If this number is 0 strArguments will be ignored. 132 133 @param Options 134 [in] A combination of int-constants to describe the mode of execution. 135 136 @param Security 137 [in] The user and his rights for which the process is started. May be NULL in which case 138 the process will be started in the context of the current user. 139 140 @param ustrDirectory 141 [in] The file URL of the working directory of the new process. If the specified directory 142 does not exist or is inaccessible the working directory of the newly created process 143 is undefined. If this parameter is NULL or the caller provides an empty string the 144 new process will have the same current working directory as the calling process. 145 146 @param ustrEnviroments 147 [in] An array of strings describing environment variables that should be merged into the 148 environment of the new process. Each string has to be in the form "variable=value". 149 This parameter can be NULL in which case the new process gets the same environment 150 as the parent process. 151 152 @param nEnvironmentVars 153 [in] The number of environment variables to set. 154 155 @param pProcess 156 [out] Pointer to a oslProcess variable, which receives the handle of the newly created process. 157 This parameter must not be NULL. 158 159 @return 160 <dl> 161 <dt>osl_Process_E_None</dt> 162 <dd>on success</dd> 163 <dt>osl_Process_E_NotFound</dt> 164 <dd>if the specified executable could not be found</dd> 165 <dt>osl_Process_E_InvalidError</dt> 166 <dd>if invalid parameters will be detected</dd> 167 <dt>osl_Process_E_Unknown</dt> 168 <dd>if arbitrary other errors occur</dd> 169 </dl> 170 171 @see oslProcessOption 172 @see osl_executeProcess_WithRedirectedIO 173 @see osl_freeProcessHandle 174 @see osl_loginUser 175 */ 176 oslProcessError SAL_CALL osl_executeProcess( 177 rtl_uString* ustrImageName, 178 rtl_uString* ustrArguments[], 179 sal_uInt32 nArguments, 180 oslProcessOption Options, 181 oslSecurity Security, 182 rtl_uString* ustrDirectory, 183 rtl_uString* ustrEnvironments[], 184 sal_uInt32 nEnvironmentVars, 185 oslProcess* pProcess); 186 187 188 /** Execute a process and redirect child process standard IO. 189 190 @param ustrImageName 191 [in] The file URL of the executable to be started. 192 Can be NULL in this case the file URL of the executable must be the first element 193 in ustrArguments. 194 195 @param ustrArguments 196 [in] An array of argument strings. Can be NULL if strImageName is not NULL. 197 If strImageName is NULL it is expected that the first element contains 198 the file URL of the executable to start. 199 200 @param nArguments 201 [in] The number of arguments provided. If this number is 0 strArguments will be ignored. 202 203 @param Options 204 [in] A combination of int-constants to describe the mode of execution. 205 206 @param Security 207 [in] The user and his rights for which the process is started. May be NULL in which case 208 the process will be started in the context of the current user. 209 210 @param ustrDirectory 211 [in] The file URL of the working directory of the new process. If the specified directory 212 does not exist or is inaccessible the working directory of the newly created process 213 is undefined. If this parameter is NULL or the caller provides an empty string the 214 new process will have the same current working directory as the calling process. 215 216 @param ustrEnviroments 217 [in] An array of strings describing environment variables that should be merged into the 218 environment of the new process. Each string has to be in the form "variable=value". 219 This parameter can be NULL in which case the new process gets the same environment 220 as the parent process. 221 222 @param nEnvironmentVars 223 [in] The number of environment variables to set. 224 225 @param pProcess 226 [out] Pointer to a oslProcess variable, which receives the handle of the newly created process. 227 This parameter must not be NULL. 228 229 @param pChildInputWrite 230 [in] Pointer to a oslFileHandle variable that receives the handle which can be used to write 231 to the child process standard input device. The returned handle is not random accessible. 232 The handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL. 233 234 @param pChildOutputRead 235 [in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from 236 the child process standard output device. The returned handle is not random accessible. 237 The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL. 238 239 @param pChildErrorRead 240 [in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from 241 the child process standard error device. The returned handle is not random accessible. 242 The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL. 243 244 @return 245 <dl> 246 <dt>osl_Process_E_None</dt> 247 <dd>on success</dd> 248 <dt>osl_Process_E_NotFound</dt> 249 <dd>if the specified executable could not be found</dd> 250 <dt>osl_Process_E_InvalidError</dt> 251 <dd>if invalid parameters will be detected</dd> 252 <dt>osl_Process_E_Unknown</dt> 253 <dd>if arbitrary other errors occur</dd> 254 </dl> 255 256 @see oslProcessOption 257 @see osl_executeProcess 258 @see osl_freeProcessHandle 259 @see osl_loginUser 260 @see osl_closeFile 261 */ 262 oslProcessError SAL_CALL osl_executeProcess_WithRedirectedIO( 263 rtl_uString* strImageName, 264 rtl_uString* ustrArguments[], 265 sal_uInt32 nArguments, 266 oslProcessOption Options, 267 oslSecurity Security, 268 rtl_uString* ustrDirectory, 269 rtl_uString* ustrEnvironments[], 270 sal_uInt32 nEnvironmentVars, 271 oslProcess* pProcess, 272 oslFileHandle* pChildInputWrite, 273 oslFileHandle* pChildOutputRead, 274 oslFileHandle* pChildErrorRead); 275 276 /** Terminate a process 277 @param Process [in] the handle of the process to be terminated 278 279 @see osl_executeProcess 280 @see osl_getProcess 281 @see osl_joinProcess 282 */ 283 oslProcessError SAL_CALL osl_terminateProcess(oslProcess Process); 284 285 286 /** @deprecated 287 Retrieve the process handle of a process identifier 288 @param Ident [in] a process identifier 289 290 @return the process handle on success, NULL in all other cases 291 */ 292 oslProcess SAL_CALL osl_getProcess(oslProcessIdentifier Ident); 293 294 295 /** Free the specified proces-handle. 296 @param Process [in] 297 */ 298 void SAL_CALL osl_freeProcessHandle(oslProcess Process); 299 300 301 /** Wait for completation of the specified childprocess. 302 @param Process [in] 303 @return ols_Process_E_None 304 @see osl_executeProcess 305 */ 306 oslProcessError SAL_CALL osl_joinProcess(oslProcess Process); 307 308 /** Wait with a timeout for the completion of the specified child 309 process. 310 311 @param Process [in] 312 A process identifier. 313 314 @param pTimeout [in] 315 A timeout value or NULL for infinite waiting. 316 The unit of resolution is second. 317 318 @return 319 osl_Process_E_None on success 320 osl_Process_E_TimedOut waiting for the child process timed out 321 osl_Process_E_Unknown an error occurred or the parameter are invalid 322 323 @see osl_executeProcess 324 */ 325 oslProcessError SAL_CALL osl_joinProcessWithTimeout(oslProcess Process, const TimeValue* pTimeout); 326 327 /** Retrieves information about a Process 328 @param Process [in] the process handle of the process 329 @param Field [in] the information which is to be retrieved 330 this can be one or more of 331 osl_Process_IDENTIFIER 332 osl_Process_EXITCODE 333 osl_Process_CPUTIMES 334 osl_Process_HEAPUSAGE 335 @param pInfo [out] a pointer to a vaid oslProcessInfo structure. 336 the Size field has to be initialized with the size 337 of the oslProcessInfo structure. 338 on success the Field member holds the (or'ed) 339 retrieved valid information fields. 340 @return osl_Process_E_None on success, osl_Process_E_Unknown on failure. 341 */ 342 oslProcessError SAL_CALL osl_getProcessInfo(oslProcess Process, oslProcessData Fields, 343 oslProcessInfo* pInfo); 344 345 /** Get the filename of the executable. 346 @param strFile [out] the string that receives the executable file path. 347 @return osl_Process_E_None or does not return. 348 @see osl_executeProcess 349 */ 350 oslProcessError SAL_CALL osl_getExecutableFile(rtl_uString **strFile); 351 352 /** @return the number of commandline arguments passed to the main-function of 353 this process 354 @see osl_getCommandArg 355 */ 356 sal_uInt32 SAL_CALL osl_getCommandArgCount(void); 357 358 /** Get the nArg-th command-line argument passed to the main-function of this process. 359 @param nArg [in] The number of the argument to return. 360 @param strCommandArg [out] The string receives the nArg-th command-line argument. 361 @return osl_Process_E_None or does not return. 362 @see osl_executeProcess 363 */ 364 oslProcessError SAL_CALL osl_getCommandArg(sal_uInt32 nArg, rtl_uString **strCommandArg); 365 366 /** Set the command-line arguments as passed to the main-function of this process. 367 368 Depricated: This function is only for internal use. Passing the args from main will 369 only work for Unix, on Windows there's no effect, the full command line will automtically 370 be taken. This is due to Windows 9x/ME limitation that don't allow UTF-16 wmain to provide 371 a osl_setCommandArgsU( int argc, sal_Unicode **argv ); 372 373 @param argc [in] The number of elements in the argv array. 374 @param argv [in] The array of command-line arguments. 375 @see osl_getExecutableFile 376 @see osl_getCommandArgCount 377 @see osl_getCommandArg 378 */ 379 void SAL_CALL osl_setCommandArgs (int argc, char **argv); 380 381 /** Get the value of one environment variable. 382 @param strVar [in] denotes the name of the variable to get. 383 @param strValue [out] string that receives the value of environment variable. 384 */ 385 oslProcessError SAL_CALL osl_getEnvironment(rtl_uString *strVar, rtl_uString **strValue); 386 387 /** Set the value of one environment variable. 388 @param strVar [in] denotes the name of the variable to set. 389 @param strValue [in] string of the new value of environment variable. 390 391 @since UDK 3.2.13 392 */ 393 oslProcessError SAL_CALL osl_setEnvironment(rtl_uString *strVar, rtl_uString *strValue); 394 395 /** Unsets the value of one environment variable. 396 @param strVar [in] denotes the name of the variable to unset. 397 398 @since UDK 3.2.13 399 */ 400 oslProcessError SAL_CALL osl_clearEnvironment(rtl_uString *strVar); 401 402 /** Get the working directory of the current process as a file URL. 403 404 The file URL is encoded as common for the OSL file API. 405 @param pustrWorkingDir [out] string that receives the working directory file URL. 406 */ 407 408 oslProcessError SAL_CALL osl_getProcessWorkingDir( rtl_uString **pustrWorkingDir ); 409 410 /** Get the locale the process is currently running in. 411 412 The unix implementation caches the value it returns, so if you have to change the locale 413 your are running in, you will have to use osl_setProcessLocale therefor. 414 415 @param ppLocale [out] a pointer that receives the currently selected locale structure 416 @see osl_setProcessLocale 417 */ 418 419 oslProcessError SAL_CALL osl_getProcessLocale( rtl_Locale ** ppLocale ); 420 421 /** Change the locale of the process. 422 423 @param pLocale [in] a pointer to the locale to be set 424 @see osl_getProcessLocale 425 */ 426 427 oslProcessError SAL_CALL osl_setProcessLocale( rtl_Locale * pLocale ); 428 429 430 sal_Bool SAL_CALL osl_sendResourcePipe(oslPipe Pipe, oslSocket Socket); 431 432 oslSocket SAL_CALL osl_receiveResourcePipe(oslPipe Pipe); 433 434 #ifdef __cplusplus 435 } 436 #endif 437 438 #endif /* _OSL_PROCESS_H_ */ 439 440