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