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