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 | typedef 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 | |
80 | typedef 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 | |
88 | typedef 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 | */ |
110 | typedef 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 | */ |
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); |
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 | */ |
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); |
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 | */ |
279 | SAL_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 | */ |
289 | SAL_DLLPUBLIC oslProcess SAL_CALL osl_getProcess( |
290 | oslProcessIdentifier Ident); |
291 | |
292 | |
293 | /** Free the specified proces-handle. |
294 | @param Process [in] |
295 | */ |
296 | SAL_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 | */ |
305 | SAL_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 | */ |
325 | SAL_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 | */ |
343 | SAL_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 | */ |
351 | SAL_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 | */ |
358 | SAL_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 | */ |
366 | SAL_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 | */ |
382 | SAL_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 | */ |
388 | SAL_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 | */ |
397 | SAL_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 | */ |
405 | SAL_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 | |
414 | SAL_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 | |
426 | SAL_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 | |
435 | SAL_DLLPUBLIC oslProcessError SAL_CALL osl_setProcessLocale( |
436 | rtl_Locale * pLocale ); |
437 | |
438 | |
439 | SAL_DLLPUBLIC sal_Bool SAL_CALL osl_sendResourcePipe( |
440 | oslPipe Pipe, oslSocket Socket ); |
441 | |
442 | SAL_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 | |