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