include/osl/process.h

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