sal/inc/osl/process.h

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