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
37extern "C" {
38#endif
39
40
41typedef 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
51typedef 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
59typedef sal_uInt32 oslProcessIdentifier;
60typedef sal_uInt32 oslProcessExitCode;
61
62typedef 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
72typedef 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
78} oslDescriptorType;
79
80typedef sal_Int32 oslDescriptorFlag;
81#define osl_Process_DFNONE 0x0000
82#define osl_Process_DFWAIT 0x0001
83
84#ifdef SAL_W32
85# pragma pack(push, 8)
86#endif
87
88typedef struct {
89 sal_uInt32 Size;
90 oslProcessData Fields;
91 oslProcessIdentifier Ident;
92 oslProcessExitCode Code;
93 TimeValue UserTime;
94 TimeValue SystemTime;
95 sal_uInt32 HeapUsage;
96} oslProcessInfo;
97
98#if defined( SAL_W32)
99# pragma pack(pop)
100#endif
101
102/** Process handle
103
104 @see osl_executeProcess
105 @see osl_terminateProcess
106 @see osl_freeProcessHandle
107 @see osl_getProcessInfo
108 @see osl_joinProcess
109*/
110typedef void* oslProcess;
111
112/** Execute a process.
113
114 Executes the program image provided in strImageName in a new process.
115
116 @param ustrImageName
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
119 in ustrArguments.
120
121 @param ustrArguments
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.
125
126 @param nArguments
127 [in] The number of arguments provided. If this number is 0 strArguments will be ignored.
128
129 @param Options
130 [in] A combination of int-constants to describe the mode of execution.
131
132 @param Security
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.
135
136 @param ustrDirectory
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.
141
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.
147
148 @param nEnvironmentVars
149 [in] The number of environment variables to set.
150
151 @param pProcess
152 [out] Pointer to a oslProcess variable, which receives the handle of the newly created process.
153 This parameter must not be NULL.
154
155 @return
156 <dl>
157 <dt>osl_Process_E_None</dt>
158 <dd>on success</dd>
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>
165 </dl>
166
167 @see oslProcessOption
168 @see osl_executeProcess_WithRedirectedIO
169 @see osl_freeProcessHandle
170 @see osl_loginUser
171*/
172SAL_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);
182
183
184/** Execute a process and redirect child process standard IO.
185
186 @param strImageName
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
189 in ustrArguments.
190
191 @param ustrArguments
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.
195
196 @param nArguments
197 [in] The number of arguments provided. If this number is 0 strArguments will be ignored.
198
199 @param Options
200 [in] A combination of int-constants to describe the mode of execution.
201
202 @param Security
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.
205
206 @param ustrDirectory
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.
211
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.
217
218 @param nEnvironmentVars
219 [in] The number of environment variables to set.
220
221 @param pProcess
222 [out] Pointer to a oslProcess variable, which receives the handle of the newly created process.
223 This parameter must not be NULL.
224
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.
229
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.
234
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.
239
240 @return
241 <dl>
242 <dt>osl_Process_E_None</dt>
243 <dd>on success</dd>
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>
250 </dl>
251
252 @see oslProcessOption
253 @see osl_executeProcess
254 @see osl_freeProcessHandle
255 @see osl_loginUser
256 @see osl_closeFile
257*/
258SAL_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);
271
272/** Terminate a process
273 @param Process [in] the handle of the process to be terminated
274
275 @see osl_executeProcess
276 @see osl_getProcess
277 @see osl_joinProcess
278 */
279SAL_DLLPUBLIC oslProcessError SAL_CALL osl_terminateProcess(
280 oslProcess Process);
281
282
283/** @deprecated
284 Retrieve the process handle of a process identifier
285 @param Ident [in] a process identifier
286
287 @return the process handle on success, NULL in all other cases
288 */
289SAL_DLLPUBLIC oslProcess SAL_CALL osl_getProcess(
290 oslProcessIdentifier Ident);
291
292
293/** Free the specified proces-handle.
294 @param Process [in]
295*/
296SAL_DLLPUBLIC void SAL_CALL osl_freeProcessHandle(
297 oslProcess Process);
298
299
300/** Wait for completation of the specified childprocess.
301 @param Process [in]
302 @return ols_Process_E_None
303 @see osl_executeProcess
304*/
305SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcess(
306 oslProcess Process);
307
308/** Wait with a timeout for the completion of the specified child
309 process.
310
311 @param Process [in]
312 A process identifier.
313
314 @param pTimeout [in]
315 A timeout value or NULL for infinite waiting.
316 The unit of resolution is second.
317
318 @return
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
322
323 @see osl_executeProcess
324*/
325SAL_DLLPUBLIC oslProcessError SAL_CALL osl_joinProcessWithTimeout(
326 oslProcess Process, const TimeValue* pTimeout);
327
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
333 osl_Process_EXITCODE
334 osl_Process_CPUTIMES
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.
342 */
343SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessInfo(
344 oslProcess Process, oslProcessData Fields, oslProcessInfo* pInfo);
345
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
350*/
351SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getExecutableFile(
352 rtl_uString **strFile);
353
354/** @return the number of commandline arguments passed to the main-function of
355 this process
356 @see osl_getCommandArg
357*/
358SAL_DLLPUBLIC sal_uInt32 SAL_CALL osl_getCommandArgCount(void);
359
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
365*/
366SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getCommandArg(
367 sal_uInt32 nArg, rtl_uString **strCommandArg);
368
369/** Set the command-line arguments as passed to the main-function of this process.
370
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 );
375
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
381*/
382SAL_DLLPUBLIC void SAL_CALL osl_setCommandArgs (int argc, char **argv);
383
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.
387*/
388SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getEnvironment(
389 rtl_uString *strVar, rtl_uString **strValue);
390
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.
394
395 @since UDK 3.2.13
396*/
397SAL_DLLPUBLIC oslProcessError SAL_CALL osl_setEnvironment(
398 rtl_uString *strVar, rtl_uString *strValue);
399
400/** Unsets the value of one enviroment variable.
401 @param strVar [in] denotes the name of the variable to unset.
402
403 @since UDK 3.2.13
404*/
405SAL_DLLPUBLIC oslProcessError SAL_CALL osl_clearEnvironment(
406 rtl_uString *strVar);
407
408/** Get the working directory of the current process as a file URL.
409
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.
412*/
413
414SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessWorkingDir(
415 rtl_uString **pustrWorkingDir );
416
417/** Get the locale the process is currently running in.
418
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.
421
422 @param ppLocale [out] a pointer that receives the currently selected locale structure
423 @see osl_setProcessLocale
424*/
425
426SAL_DLLPUBLIC oslProcessError SAL_CALL osl_getProcessLocale(
427 rtl_Locale ** ppLocale );
428
429/** Change the locale of the process.
430
431 @param pLocale [in] a pointer to the locale to be set
432 @see osl_getProcessLocale
433*/
434
435SAL_DLLPUBLIC oslProcessError SAL_CALL osl_setProcessLocale(
436 rtl_Locale * pLocale );
437
438
439SAL_DLLPUBLIC sal_Bool SAL_CALL osl_sendResourcePipe(
440 oslPipe Pipe, oslSocket Socket );
441
442SAL_DLLPUBLIC oslSocket SAL_CALL osl_receiveResourcePipe(
443 oslPipe Pipe );
444
445#ifdef __cplusplus
446}
447#endif
448
449#endif // INCLUDED_OSL_PROCESS_H
450
451/* vim:set shiftwidth=4 softtabstop=4 expandtab: */
452