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  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_OSL_PROCESS_H
  25 #define INCLUDED_OSL_PROCESS_H
  26
  27 #include "sal/config.h"
  28
  29 #include "osl/file.h"
  30 #include "osl/security.h"
  31 #include "osl/time.h"
  32 #include "rtl/locale.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,             /* timeout 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 _WIN32
  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( _WIN32)
  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[in] ustrImageName
 105     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[in] ustrArguments
 110     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[in] nArguments
 115     The number of arguments provided. If this number is 0 strArguments will be ignored.
 116
 117     @param[in] Options
 118     A combination of int-constants to describe the mode of execution.
 119
 120     @param[in] Security
 121     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[in] ustrDirectory
 125     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[in] ustrEnvironments
 131     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[in] nEnvironmentVars
 137     The number of environment variables to set.
 138
 139     @param[out] pProcess
 140     Pointer to a oslProcess variable, which receives the handle of the newly created process.
 141     This parameter must not be NULL.
 142
 143     @retval osl_Process_E_None on success
 144     @retval osl_Process_E_NotFound if the specified executable could not be found</dd>
 145     @retval osl_Process_E_InvalidError if invalid parameters will be detected</dd>
 146     @retval osl_Process_E_Unknown if arbitrary other errors occur</dd>
 147
 148     @see oslProcessOption
 149     @see osl_executeProcess_WithRedirectedIO
 150     @see osl_freeProcessHandle
 151     @see osl_loginUser
 152 */
 153 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_executeProcess(
 154     rtl_uString* ustrImageName,
 155     rtl_uString* ustrArguments[],
 156     sal_uInt32  nArguments,
 157     oslProcessOption Options,
 158     oslSecurity Security,
 159     rtl_uString* ustrDirectory,
 160     rtl_uString* ustrEnvironments[],
 161     sal_uInt32 nEnvironmentVars,
 162     oslProcess* pProcess);
 163
 164
 165 /** Execute a process and redirect child process standard IO.
 166
 167     @param[in] strImageName
 168     The file URL of the executable to be started.
 169     Can be NULL in this case the file URL of the executable must be the first element
 170     in ustrArguments.
 171
 172     @param[in] ustrArguments
 173     An array of argument strings. Can be NULL if strImageName is not NULL.
 174     If strImageName is NULL it is expected that the first element contains
 175     the file URL of the executable to start.
 176
 177     @param[in] nArguments
 178     The number of arguments provided. If this number is 0 strArguments will be ignored.
 179
 180     @param[in] Options
 181     A combination of int-constants to describe the mode of execution.
 182
 183     @param[in] Security
 184     The user and his rights for which the process is started. May be NULL in which case
 185     the process will be started in the context of the current user.
 186
 187     @param[in] ustrDirectory
 188     The file URL of the working directory of the new process. If the specified directory
 189     does not exist or is inaccessible the working directory of the newly created process
 190     is undefined. If this parameter is NULL or the caller provides an empty string the
 191     new process will have the same current working directory as the calling process.
 192
 193     @param[in] ustrEnvironments
 194     An array of strings describing environment variables that should be merged into the
 195     environment of the new process. Each string has to be in the form "variable=value".
 196     This parameter can be NULL in which case the new process gets the same environment
 197     as the parent process.
 198
 199     @param[in] nEnvironmentVars
 200     The number of environment variables to set.
 201
 202     @param[out] pProcess
 203     Pointer to a oslProcess variable, which receives the handle of the newly created process.
 204     This parameter must not be NULL.
 205
 206     @param[out] pChildInputWrite
 207     Pointer to a oslFileHandle variable that receives the handle which can be used to write
 208     to the child process standard input device. The returned handle is not random accessible.
 209     The handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
 210
 211     @param[out] pChildOutputRead
 212     Pointer to a oslFileHandle variable that receives the handle which can be used to read from
 213     the child process standard output device. The returned handle is not random accessible.
 214     The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
 215
 216     @param[out] pChildErrorRead
 217     Pointer to a oslFileHandle variable that receives the handle which can be used to read from
 218     the child process standard error device. The returned handle is not random accessible.
 219     The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
 220
 221     @retval osl_Process_E_None on success
 222     @retval osl_Process_E_NotFound if the specified executable could not be found
 223     @retval osl_Process_E_InvalidError if invalid parameters will be detected
 224     @retval osl_Process_E_Unknown if arbitrary other errors occur
 225
 226     @see oslProcessOption
 227     @see osl_executeProcess
 228     @see osl_freeProcessHandle
 229     @see osl_loginUser
 230     @see osl_closeFile
 231 */
 232 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_executeProcess_WithRedirectedIO(
 233     rtl_uString* strImageName,
 234     rtl_uString* ustrArguments[],
 235     sal_uInt32 nArguments,
 236     oslProcessOption Options,
 237     oslSecurity Security,
 238     rtl_uString* ustrDirectory,
 239     rtl_uString* ustrEnvironments[],
 240     sal_uInt32 nEnvironmentVars,
 241     oslProcess* pProcess,
 242     oslFileHandle* pChildInputWrite,
 243     oslFileHandle* pChildOutputRead,
 244     oslFileHandle* pChildErrorRead);
 245
 246 /** Terminate a process
 247
 248     @param[in] Process the handle of the process to be terminated
 249
 250     @see osl_executeProcess
 251     @see osl_getProcess
 252     @see osl_joinProcess
 253  */
 254 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_terminateProcess(
 255         oslProcess Process);
 256
 257
 258 /** @deprecated
 259
 260     Retrieve the process handle of a process identifier
 261
 262     @param[in] Ident a process identifier
 263
 264     @return the process handle on success, NULL in all other cases
 265  */
 266 SAL_DLLPUBLIC oslProcess SAL_CALL osl_getProcess(
 267         oslProcessIdentifier Ident) SAL_COLD;
 268
 269
 270 /** Free the specified process-handle.
 271
 272     @param[in] Process
 273 */
 274 SAL_DLLPUBLIC void SAL_CALL osl_freeProcessHandle(
 275         oslProcess Process);
 276
 277
 278 /** Wait for completion of the specified childprocess.
 279     @param[in] Process
 280
 281     @retval ols_Process_E_None
 282
 283     @see osl_executeProcess
 284 */
 285 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcess(
 286         oslProcess Process);
 287
 288 /** Wait with a timeout for the completion of the specified child
 289     process.
 290
 291     @param[in] Process A process identifier.
 292     @param[in] pTimeout A timeout value or NULL for infinite waiting.
 293         The unit of resolution is second.
 294
 295     @retval osl_Process_E_None on success
 296     @retval osl_Process_E_TimedOut waiting for the child process timed out
 297     @retval osl_Process_E_Unknown an error occurred or the parameter are invalid
 298
 299     @see osl_executeProcess
 300 */
 301 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcessWithTimeout(
 302         oslProcess Process, const TimeValue* pTimeout);
 303
 304 /** Retrieves information about a Process
 305     @param[in] Process  the process handle of the process
 306     @param[in] Fields   the information which is to be retrieved
 307                         this can be one or more of
 308                         osl_Process_IDENTIFIER
 309                         osl_Process_EXITCODE
 310                         osl_Process_CPUTIMES
 311                         osl_Process_HEAPUSAGE
 312     @param[out] pInfo   a pointer to a valid oslProcessInfo structure.
 313                         the Size field has to be initialized with the size
 314                         of the oslProcessInfo structure.
 315                         on success the Field member holds the (or'ed)
 316                         retrieved valid information fields.
 317     @retval osl_Process_E_None on success
 318     @retval osl_Process_E_Unknown on failure
 319  */
 320 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessInfo(
 321         oslProcess Process, oslProcessData Fields, oslProcessInfo* pInfo);
 322
 323 /** Get the filename of the executable.
 324     @param[out] strFile the string that receives the executable file path.
 325     @return osl_Process_E_None or does not return.
 326     @see osl_executeProcess
 327
 328     Ideally this will return the true executable file path as a file:
 329     URL, but actually in case something else happens to have been
 330     passed as argv[0] to osl_setCommandArgs(), it will return that
 331     either as a file URL, or as such in case it doesn't look like an
 332     absolute pathname.
 333 */
 334 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getExecutableFile(
 335         rtl_uString **strFile);
 336
 337 /** @return the number of commandline arguments passed to the main-function of
 338     this process
 339     @see osl_getCommandArg
 340 */
 341 SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getCommandArgCount(void);
 342
 343 /** Get the nArg-th command-line argument passed to the main-function of this process.
 344     @param[in] nArg  The number of the argument to return.
 345     @param[out] strCommandArg The string receives the nArg-th command-line argument.
 346     @return osl_Process_E_None or does not return.
 347     @see osl_executeProcess
 348 */
 349 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getCommandArg(
 350         sal_uInt32 nArg, rtl_uString **strCommandArg);
 351
 352 /** Set the command-line arguments as passed to the main-function of this process.
 353
 354     Deprecated: This function is only for internal use. Passing the args from main will
 355     only work for Unix, on Windows there's no effect, the full command line will automatically
 356     be taken. This is due to Windows 9x/ME limitation that don't allow UTF-16 wmain to provide
 357     a osl_setCommandArgsU( int argc, sal_Unicode **argv );
 358
 359     @param[in] argc  The number of elements in the argv array.
 360     @param[in] argv  The array of command-line arguments.
 361     @see osl_getExecutableFile
 362     @see osl_getCommandArgCount
 363     @see osl_getCommandArg
 364 */
 365 SAL_DLLPUBLIC void SAL_CALL osl_setCommandArgs (int argc, char **argv);
 366
 367 /** Get the value of one environment variable.
 368     @param[in] strVar  denotes the name of the variable to get.
 369     @param[out] strValue string that receives the value of environment variable.
 370 */
 371 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getEnvironment(
 372         rtl_uString *strVar, rtl_uString **strValue);
 373
 374 /** Set the value of one environment variable.
 375     @param[in] strVar  denotes the name of the variable to set.
 376     @param[in] strValue  string of the new value of environment variable.
 377
 378     @since UDK 3.2.13
 379 */
 380 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_setEnvironment(
 381         rtl_uString *strVar, rtl_uString *strValue);
 382
 383 /** Unsets the value of one environment variable.
 384     @param[in] strVar  denotes the name of the variable to unset.
 385
 386     @since UDK 3.2.13
 387 */
 388 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_clearEnvironment(
 389         rtl_uString *strVar);
 390
 391 /** Get the working directory of the current process as a file URL.
 392
 393     The file URL is encoded as common for the OSL file API.
 394     @param[out] pustrWorkingDir string that receives the working directory file URL.
 395 */
 396
 397 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessWorkingDir(
 398         rtl_uString **pustrWorkingDir );
 399
 400 /** Get the locale the process is currently running in.
 401
 402     @param[out] ppLocale a pointer that receives the currently selected locale structure
 403 */
 404
 405 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessLocale(
 406         rtl_Locale ** ppLocale );
 407
 408 /** Change the locale of the process.
 409
 410     @param[in] pLocale  a pointer to the locale to be set
 411
 412     @deprecated  LibreOffice itself does not use this, and client code should
 413         not have good use for it either.  It may eventually be removed.
 414 */
 415
 416 SAL_DLLPUBLIC oslProcessError SAL_CALL osl_setProcessLocale(
 417         rtl_Locale * pLocale );
 418
 419 #ifdef __cplusplus
 420 }
 421 #endif
 422
 423 #endif // INCLUDED_OSL_PROCESS_H
 424
 425 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */