1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
3 * This file is part of the LibreOffice project.
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/.
9 * This file incorporates work covered by the following license notice:
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 .
21 #ifndef INCLUDED_OSL_PROCESS_H
22 #define INCLUDED_OSL_PROCESS_H
24 #include <sal/config.h>
28 #include <osl/security.h>
29 #include <osl/socket.h>
31 #include <rtl/locale.h>
32 #include <rtl/textenc.h>
33 #include <rtl/ustring.h>
34 #include <sal/saldllapi.h>
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 */
51 typedef sal_Int32 oslProcessData
;
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 */
59 typedef sal_uInt32 oslProcessIdentifier
;
60 typedef sal_uInt32 oslProcessExitCode
;
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
73 osl_Process_TypeNone
, /* no descriptor */
74 osl_Process_TypeSocket
, /* socket */
75 osl_Process_TypeFile
, /* file */
76 osl_Process_TypePipe
, /* pipe */
77 osl_Process_FORCE_EQUAL_SIZE
= SAL_MAX_ENUM
80 typedef sal_Int32 oslDescriptorFlag
;
81 #define osl_Process_DFNONE 0x0000
82 #define osl_Process_DFWAIT 0x0001
85 # pragma pack(push, 8)
90 oslProcessData Fields
;
91 oslProcessIdentifier Ident
;
92 oslProcessExitCode Code
;
104 @see osl_executeProcess
105 @see osl_terminateProcess
106 @see osl_freeProcessHandle
107 @see osl_getProcessInfo
110 typedef void* oslProcess
;
112 /** Execute a process.
114 Executes the program image provided in strImageName in a new process.
117 [in] The file URL of the executable to be started.
118 Can be NULL in this case the file URL of the executable must be the first element
122 [in] An array of argument strings. Can be NULL if strImageName is not NULL.
123 If strImageName is NULL it is expected that the first element contains
124 the file URL of the executable to start.
127 [in] The number of arguments provided. If this number is 0 strArguments will be ignored.
130 [in] A combination of int-constants to describe the mode of execution.
133 [in] The user and his rights for which the process is started. May be NULL in which case
134 the process will be started in the context of the current user.
137 [in] The file URL of the working directory of the new proces. If the specified directory
138 does not exist or is inaccessible the working directory of the newly created process
139 is undefined. If this parameter is NULL or the caller provides an empty string the
140 new process will have the same current working directory as the calling process.
142 @param ustrEnvironments
143 [in] An array of strings describing environment variables that should be merged into the
144 environment of the new process. Each string has to be in the form "variable=value".
145 This parameter can be NULL in which case the new process gets the same environment
146 as the parent process.
148 @param nEnvironmentVars
149 [in] The number of environment variables to set.
152 [out] Pointer to a oslProcess variable, which receives the handle of the newly created process.
153 This parameter must not be NULL.
157 <dt>osl_Process_E_None</dt>
159 <dt>osl_Process_E_NotFound</dt>
160 <dd>if the specified executable could not be found</dd>
161 <dt>osl_Process_E_InvalidError</dt>
162 <dd>if invalid parameters will be detected</dd>
163 <dt>osl_Process_E_Unknown</dt>
164 <dd>if arbitrary other errors occur</dd>
167 @see oslProcessOption
168 @see osl_executeProcess_WithRedirectedIO
169 @see osl_freeProcessHandle
172 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_executeProcess(
173 rtl_uString
* ustrImageName
,
174 rtl_uString
* ustrArguments
[],
175 sal_uInt32 nArguments
,
176 oslProcessOption Options
,
177 oslSecurity Security
,
178 rtl_uString
* ustrDirectory
,
179 rtl_uString
* ustrEnvironments
[],
180 sal_uInt32 nEnvironmentVars
,
181 oslProcess
* pProcess
);
184 /** Execute a process and redirect child process standard IO.
187 [in] The file URL of the executable to be started.
188 Can be NULL in this case the file URL of the executable must be the first element
192 [in] An array of argument strings. Can be NULL if strImageName is not NULL.
193 If strImageName is NULL it is expected that the first element contains
194 the file URL of the executable to start.
197 [in] The number of arguments provided. If this number is 0 strArguments will be ignored.
200 [in] A combination of int-constants to describe the mode of execution.
203 [in] The user and his rights for which the process is started. May be NULL in which case
204 the process will be started in the context of the current user.
207 [in] The file URL of the working directory of the new proces. If the specified directory
208 does not exist or is inaccessible the working directory of the newly created process
209 is undefined. If this parameter is NULL or the caller provides an empty string the
210 new process will have the same current working directory as the calling process.
212 @param ustrEnvironments
213 [in] An array of strings describing environment variables that should be merged into the
214 environment of the new process. Each string has to be in the form "variable=value".
215 This parameter can be NULL in which case the new process gets the same environment
216 as the parent process.
218 @param nEnvironmentVars
219 [in] The number of environment variables to set.
222 [out] Pointer to a oslProcess variable, which receives the handle of the newly created process.
223 This parameter must not be NULL.
225 @param pChildInputWrite
226 [in] Pointer to a oslFileHandle variable that receives the handle which can be used to write
227 to the child process standard input device. The returned handle is not random accessible.
228 The handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
230 @param pChildOutputRead
231 [in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from
232 the child process standard output device. The returned handle is not random accessible.
233 The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
235 @param pChildErrorRead
236 [in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from
237 the child process standard error device. The returned handle is not random accessible.
238 The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
242 <dt>osl_Process_E_None</dt>
244 <dt>osl_Process_E_NotFound</dt>
245 <dd>if the specified executable could not be found</dd>
246 <dt>osl_Process_E_InvalidError</dt>
247 <dd>if invalid parameters will be detected</dd>
248 <dt>osl_Process_E_Unknown</dt>
249 <dd>if arbitrary other errors occur</dd>
252 @see oslProcessOption
253 @see osl_executeProcess
254 @see osl_freeProcessHandle
258 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_executeProcess_WithRedirectedIO(
259 rtl_uString
* strImageName
,
260 rtl_uString
* ustrArguments
[],
261 sal_uInt32 nArguments
,
262 oslProcessOption Options
,
263 oslSecurity Security
,
264 rtl_uString
* ustrDirectory
,
265 rtl_uString
* ustrEnvironments
[],
266 sal_uInt32 nEnvironmentVars
,
267 oslProcess
* pProcess
,
268 oslFileHandle
* pChildInputWrite
,
269 oslFileHandle
* pChildOutputRead
,
270 oslFileHandle
* pChildErrorRead
);
272 /** Terminate a process
273 @param Process [in] the handle of the process to be terminated
275 @see osl_executeProcess
279 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_terminateProcess(
284 Retrieve the process handle of a process identifier
285 @param Ident [in] a process identifier
287 @return the process handle on success, NULL in all other cases
289 SAL_DLLPUBLIC oslProcess SAL_CALL
osl_getProcess(
290 oslProcessIdentifier Ident
);
293 /** Free the specified proces-handle.
296 SAL_DLLPUBLIC
void SAL_CALL
osl_freeProcessHandle(
300 /** Wait for completation of the specified childprocess.
302 @return ols_Process_E_None
303 @see osl_executeProcess
305 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_joinProcess(
308 /** Wait with a timeout for the completion of the specified child
312 A process identifier.
315 A timeout value or NULL for infinite waiting.
316 The unit of resolution is second.
319 osl_Process_E_None on success
320 osl_Process_E_TimedOut waiting for the child process timed out
321 osl_Process_E_Unknown an error occurred or the parameter are invalid
323 @see osl_executeProcess
325 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_joinProcessWithTimeout(
326 oslProcess Process
, const TimeValue
* pTimeout
);
328 /** Retrieves information about a Process
329 @param[in] Process the process handle of the process
330 @param[in] Fields the information which is to be retrieved
331 this can be one or more of
332 osl_Process_IDENTIFIER
335 osl_Process_HEAPUSAGE
336 @param[out] pInfo a pointer to a vaid oslProcessInfo structure.
337 the Size field has to be initialized with the size
338 of the oslProcessInfo structure.
339 on success the Field member holds the (or'ed)
340 retrieved valid information fields.
341 @return osl_Process_E_None on success, osl_Process_E_Unknown on failure.
343 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_getProcessInfo(
344 oslProcess Process
, oslProcessData Fields
, oslProcessInfo
* pInfo
);
346 /** Get the filename of the executable.
347 @param strFile [out] the string that receives the executable file path.
348 @return osl_Process_E_None or does not return.
349 @see osl_executeProcess
351 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_getExecutableFile(
352 rtl_uString
**strFile
);
354 /** @return the number of commandline arguments passed to the main-function of
356 @see osl_getCommandArg
358 SAL_DLLPUBLIC sal_uInt32 SAL_CALL
osl_getCommandArgCount(void);
360 /** Get the nArg-th command-line argument passed to the main-function of this process.
361 @param nArg [in] The number of the argument to return.
362 @param strCommandArg [out] The string receives the nArg-th command-line argument.
363 @return osl_Process_E_None or does not return.
364 @see osl_executeProcess
366 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_getCommandArg(
367 sal_uInt32 nArg
, rtl_uString
**strCommandArg
);
369 /** Set the command-line arguments as passed to the main-function of this process.
371 Depricated: This function is only for internal use. Passing the args from main will
372 only work for Unix, on Windows there's no effect, the full command line will automtically
373 be taken. This is due to Windows 9x/ME limitation that don't allow UTF-16 wmain to provide
374 a osl_setCommandArgsU( int argc, sal_Unicode **argv );
376 @param argc [in] The number of elements in the argv array.
377 @param argv [in] The array of command-line arguments.
378 @see osl_getExecutableFile
379 @see osl_getCommandArgCount
380 @see osl_getCommandArg
382 SAL_DLLPUBLIC
void SAL_CALL
osl_setCommandArgs (int argc
, char **argv
);
384 /** Get the value of one enviroment variable.
385 @param strVar [in] denotes the name of the variable to get.
386 @param strValue [out] string that receives the value of environment variable.
388 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_getEnvironment(
389 rtl_uString
*strVar
, rtl_uString
**strValue
);
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.
397 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_setEnvironment(
398 rtl_uString
*strVar
, rtl_uString
*strValue
);
400 /** Unsets the value of one enviroment variable.
401 @param strVar [in] denotes the name of the variable to unset.
405 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_clearEnvironment(
406 rtl_uString
*strVar
);
408 /** Get the working directory of the current process as a file URL.
410 The file URL is encoded as common for the OSL file API.
411 @param pustrWorkingDir [out] string that receives the working directory file URL.
414 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_getProcessWorkingDir(
415 rtl_uString
**pustrWorkingDir
);
417 /** Get the locale the process is currently running in.
419 The unix implementation caches the value it returns, so if you have to change the locale
420 your are running in, you will have to use osl_setProcessLocale therefor.
422 @param ppLocale [out] a pointer that receives the currently selected locale structure
423 @see osl_setProcessLocale
426 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_getProcessLocale(
427 rtl_Locale
** ppLocale
);
429 /** Change the locale of the process.
431 @param pLocale [in] a pointer to the locale to be set
432 @see osl_getProcessLocale
435 SAL_DLLPUBLIC oslProcessError SAL_CALL
osl_setProcessLocale(
436 rtl_Locale
* pLocale
);
439 SAL_DLLPUBLIC sal_Bool SAL_CALL
osl_sendResourcePipe(
440 oslPipe Pipe
, oslSocket Socket
);
442 SAL_DLLPUBLIC oslSocket SAL_CALL
osl_receiveResourcePipe(
449 #endif // INCLUDED_OSL_PROCESS_H
451 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */