xref: /aoo42x/main/sal/inc/osl/process.h (revision fb0b81f5)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 
24 
25 #ifndef _OSL_PROCESS_H_
26 #define _OSL_PROCESS_H_
27 
28 #include <rtl/ustring.h>
29 #include <rtl/textenc.h>
30 #include <rtl/locale.h>
31 
32 #include <osl/time.h>
33 #include <osl/file.h>
34 #include <osl/pipe.h>
35 #include <osl/socket.h>
36 #include <osl/security.h>
37 
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41 
42 
43 typedef sal_Int32 oslProcessOption;
44 #define		osl_Process_WAIT       0x0001    /* wait for completion */
45 #define		osl_Process_SEARCHPATH 0x0002    /* search path for executable */
46 #define		osl_Process_DETACHED   0x0004    /* run detached */
47 #define		osl_Process_NORMAL     0x0000    /* run in normal window */
48 #define		osl_Process_HIDDEN     0x0010    /* run hidden */
49 #define		osl_Process_MINIMIZED  0x0020    /* run in minimized window */
50 #define		osl_Process_MAXIMIZED  0x0040    /* run in maximized window */
51 #define		osl_Process_FULLSCREEN 0x0080    /* run in fullscreen window */
52 
53 typedef sal_Int32 oslProcessData;
54 
55 /* defines for osl_getProcessInfo , can be OR'ed */
56 #define		osl_Process_IDENTIFIER  0x0001   /* retrieves the process identifier   */
57 #define		osl_Process_EXITCODE	0x0002   /* retrieves exit code of the process */
58 #define		osl_Process_CPUTIMES  	0x0004   /* retrieves used cpu time            */
59 #define		osl_Process_HEAPUSAGE	0x0008   /* retrieves the used size of heap    */
60 
61 typedef	sal_uInt32 oslProcessIdentifier;
62 typedef	sal_uInt32 oslProcessExitCode;
63 
64 typedef enum {
65     osl_Process_E_None,					/* no error */
66     osl_Process_E_NotFound,				/* image not found */
67     osl_Process_E_TimedOut,				/* timout occurred */
68     osl_Process_E_NoPermission,	  	  	/* permission denied */
69     osl_Process_E_Unknown,			  	/* unknown error */
70     osl_Process_E_InvalidError,			/* unmapped error */
71 	osl_Process_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
72 } oslProcessError;
73 
74 typedef enum {
75     osl_Process_TypeNone,	  	/* no descriptor */
76     osl_Process_TypeSocket,		/* socket */
77     osl_Process_TypeFile,		/* file   */
78 	osl_Process_TypePipe,       /* pipe   */
79 	osl_Process_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
80 } oslDescriptorType;
81 
82 typedef sal_Int32 oslDescriptorFlag;
83 #define	osl_Process_DFNONE       0x0000
84 #define	osl_Process_DFWAIT       0x0001
85 
86 #ifdef SAL_W32
87 #	pragma pack(push, 8)
88 #elif defined(SAL_OS2)
89 #	pragma pack(push, 4)
90 #endif
91 
92 typedef struct {
93     sal_uInt32				Size;
94     oslProcessData			Fields;
95     oslProcessIdentifier	Ident;
96     oslProcessExitCode		Code;
97     TimeValue				UserTime;
98     TimeValue				SystemTime;
99     sal_uInt32				HeapUsage;
100 } oslProcessInfo;
101 
102 #if defined( SAL_W32) ||  defined(SAL_OS2)
103 #	pragma pack(pop)
104 #endif
105 
106 /** Process handle
107 
108 	@see osl_executeProcess
109 	@see osl_terminateProcess
110 	@see osl_freeProcessHandle
111     @see osl_getProcessInfo
112 	@see osl_joinProcess
113 */
114 typedef void* oslProcess;
115 
116 /** Execute a process.
117 
118     Executes the program image provided in strImageName in a new process.
119 
120     @param ustrImageName
121     [in] The file URL of the executable to be started.
122     Can be NULL in this case the file URL of the executable must be the first element
123     in ustrArguments.
124 
125 	@param ustrArguments
126 	[in] An array of argument strings. Can be NULL if strImageName is not NULL.
127 	If strImageName is NULL it is expected that the first element contains
128 	the file URL of the executable to start.
129 
130     @param nArguments
131     [in] The number of arguments provided. If this number is 0 strArguments will be ignored.
132 
133 	@param Options
134 	[in] A combination of int-constants to describe the mode of execution.
135 
136 	@param Security
137 	[in] The user and his rights for which the process is started. May be NULL in which case
138 	the process will be started in the context of the current user.
139 
140 	@param ustrDirectory
141 	[in] The file URL of the working directory of the new process. If the specified directory
142 	does not exist or is inaccessible the working directory of the newly created process
143 	is undefined. If this parameter is NULL or the caller provides an empty string the
144 	new process will have the same current working directory as the calling process.
145 
146 	@param ustrEnviroments
147 	[in] An array of strings describing environment variables that should be merged into the
148 	environment of the new process. Each string has to be in the form "variable=value".
149 	This parameter can be NULL in which case the new process gets the same environment
150 	as the parent process.
151 
152     @param nEnvironmentVars
153     [in] The number of environment variables to set.
154 
155 	@param pProcess
156 	[out] Pointer to a oslProcess variable, which receives the handle of the newly created process.
157 	This parameter must not be NULL.
158 
159 	@return
160 	<dl>
161 	<dt>osl_Process_E_None</dt>
162 	<dd>on success</dd>
163 	<dt>osl_Process_E_NotFound</dt>
164 	<dd>if the specified executable could not be found</dd>
165 	<dt>osl_Process_E_InvalidError</dt>
166 	<dd>if invalid parameters will be detected</dd>
167 	<dt>osl_Process_E_Unknown</dt>
168 	<dd>if arbitrary other errors occur</dd>
169 	</dl>
170 
171 	@see oslProcessOption
172 	@see osl_executeProcess_WithRedirectedIO
173 	@see osl_freeProcessHandle
174 	@see osl_loginUser
175 */
176 oslProcessError SAL_CALL osl_executeProcess(
177     rtl_uString* ustrImageName,
178 	rtl_uString* ustrArguments[],
179     sal_uInt32  nArguments,
180 	oslProcessOption Options,
181 	oslSecurity Security,
182 	rtl_uString* ustrDirectory,
183 	rtl_uString* ustrEnvironments[],
184     sal_uInt32 nEnvironmentVars,
185 	oslProcess* pProcess);
186 
187 
188 /** Execute a process and redirect child process standard IO.
189 
190 	@param ustrImageName
191     [in] The file URL of the executable to be started.
192     Can be NULL in this case the file URL of the executable must be the first element
193     in ustrArguments.
194 
195 	@param ustrArguments
196 	[in] An array of argument strings. Can be NULL if strImageName is not NULL.
197 	If strImageName is NULL it is expected that the first element contains
198 	the file URL of the executable to start.
199 
200     @param nArguments
201     [in] The number of arguments provided. If this number is 0 strArguments will be ignored.
202 
203 	@param Options
204 	[in] A combination of int-constants to describe the mode of execution.
205 
206 	@param Security
207 	[in] The user and his rights for which the process is started. May be NULL in which case
208 	the process will be started in the context of the current user.
209 
210 	@param ustrDirectory
211 	[in] The file URL of the working directory of the new process. If the specified directory
212 	does not exist or is inaccessible the working directory of the newly created process
213 	is undefined. If this parameter is NULL or the caller provides an empty string the
214 	new process will have the same current working directory as the calling process.
215 
216 	@param ustrEnviroments
217 	[in] An array of strings describing environment variables that should be merged into the
218 	environment of the new process. Each string has to be in the form "variable=value".
219 	This parameter can be NULL in which case the new process gets the same environment
220 	as the parent process.
221 
222     @param nEnvironmentVars
223     [in] The number of environment variables to set.
224 
225 	@param pProcess
226 	[out] Pointer to a oslProcess variable, which receives the handle of the newly created process.
227 	This parameter must not be NULL.
228 
229 	@param pChildInputWrite
230 	[in] Pointer to a oslFileHandle variable that receives the handle which can be used to write
231 	to the child process standard input device. The returned handle is not random accessible.
232 	The handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
233 
234 	@param pChildOutputRead
235 	[in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from
236 	the child process standard output device. The returned handle is not random accessible.
237 	The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
238 
239 	@param pChildErrorRead
240 	[in] Pointer to a oslFileHandle variable that receives the handle which can be used to read from
241 	the child process standard error device. The returned handle is not random accessible.
242 	The Handle has to be closed with osl_closeFile if no longer used. This parameter can be NULL.
243 
244 	@return
245 	<dl>
246 	<dt>osl_Process_E_None</dt>
247 	<dd>on success</dd>
248 	<dt>osl_Process_E_NotFound</dt>
249 	<dd>if the specified executable could not be found</dd>
250 	<dt>osl_Process_E_InvalidError</dt>
251 	<dd>if invalid parameters will be detected</dd>
252 	<dt>osl_Process_E_Unknown</dt>
253 	<dd>if arbitrary other errors occur</dd>
254 	</dl>
255 
256 	@see oslProcessOption
257 	@see osl_executeProcess
258 	@see osl_freeProcessHandle
259 	@see osl_loginUser
260 	@see osl_closeFile
261 */
262 oslProcessError SAL_CALL osl_executeProcess_WithRedirectedIO(
263     rtl_uString* strImageName,
264 	rtl_uString* ustrArguments[],
265     sal_uInt32 nArguments,
266 	oslProcessOption Options,
267 	oslSecurity Security,
268 	rtl_uString* ustrDirectory,
269 	rtl_uString* ustrEnvironments[],
270     sal_uInt32 nEnvironmentVars,
271 	oslProcess* pProcess,
272 	oslFileHandle* pChildInputWrite,
273 	oslFileHandle* pChildOutputRead,
274 	oslFileHandle* pChildErrorRead);
275 
276 /** Terminate a process
277     @param Process [in] the handle of the process to be terminated
278 
279     @see osl_executeProcess
280     @see osl_getProcess
281     @see osl_joinProcess
282  */
283 oslProcessError SAL_CALL osl_terminateProcess(oslProcess Process);
284 
285 
286 /** @deprecated
287     Retrieve the process handle of a process identifier
288     @param Ident [in] a process identifier
289 
290     @return the process handle on success, NULL in all other cases
291  */
292 oslProcess SAL_CALL osl_getProcess(oslProcessIdentifier Ident);
293 
294 
295 /** Free the specified proces-handle.
296 	@param Process [in]
297 */
298 void SAL_CALL osl_freeProcessHandle(oslProcess Process);
299 
300 
301 /** Wait for completation of the specified childprocess.
302 	@param Process [in]
303 	@return ols_Process_E_None
304 	@see osl_executeProcess
305 */
306 oslProcessError SAL_CALL osl_joinProcess(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 oslProcessError SAL_CALL osl_joinProcessWithTimeout(oslProcess Process, const TimeValue* pTimeout);
326 
327 /** Retrieves information about a Process
328     @param Process [in] the process handle of the process
329     @param Field   [in] the information which is to be retrieved
330                         this can be one or more of
331                         osl_Process_IDENTIFIER
332                         osl_Process_EXITCODE
333                         osl_Process_CPUTIMES
334                         osl_Process_HEAPUSAGE
335     @param pInfo  [out] a pointer to a vaid oslProcessInfo structure.
336                         the Size field has to be initialized with the size
337                         of the oslProcessInfo structure.
338                         on success the Field member holds the (or'ed)
339                         retrieved valid information fields.
340     @return osl_Process_E_None on success, osl_Process_E_Unknown on failure.
341  */
342 oslProcessError SAL_CALL osl_getProcessInfo(oslProcess Process, oslProcessData Fields,
343                                    oslProcessInfo* pInfo);
344 
345 /** Get the filename of the executable.
346 	@param strFile [out] the string that receives the executable file path.
347 	@return osl_Process_E_None or does not return.
348 	@see osl_executeProcess
349 */
350 oslProcessError SAL_CALL osl_getExecutableFile(rtl_uString **strFile);
351 
352 /** @return the number of commandline arguments passed to the main-function of
353     this process
354     @see osl_getCommandArg
355 */
356 sal_uInt32 SAL_CALL osl_getCommandArgCount(void);
357 
358 /** Get the nArg-th command-line argument passed to the main-function of this process.
359     @param nArg [in] The number of the argument to return.
360 	@param strCommandArg [out] The string receives the nArg-th command-line argument.
361 	@return osl_Process_E_None or does not return.
362 	@see osl_executeProcess
363 */
364 oslProcessError SAL_CALL osl_getCommandArg(sal_uInt32 nArg, rtl_uString **strCommandArg);
365 
366 /** Set the command-line arguments as passed to the main-function of this process.
367 
368     Depricated: This function is only for internal use. Passing the args from main will
369 	only work for Unix, on Windows there's no effect, the full command line will automtically
370 	be taken. This is due to Windows 9x/ME limitation that don't allow UTF-16 wmain to provide
371 	a osl_setCommandArgsU( int argc, sal_Unicode **argv );
372 
373 	@param argc [in] The number of elements in the argv array.
374 	@param argv [in] The array of command-line arguments.
375 	@see osl_getExecutableFile
376 	@see osl_getCommandArgCount
377 	@see osl_getCommandArg
378 */
379 void SAL_CALL osl_setCommandArgs (int argc, char **argv);
380 
381 /** Get the value of one environment variable.
382 	@param strVar [in] denotes the name of the variable to get.
383 	@param strValue [out] string that receives the value of environment variable.
384 */
385 oslProcessError SAL_CALL osl_getEnvironment(rtl_uString *strVar, rtl_uString **strValue);
386 
387 /** Set the value of one environment variable.
388 	@param strVar [in] denotes the name of the variable to set.
389 	@param strValue [in] string of the new value of environment variable.
390 
391 	@since UDK 3.2.13
392 */
393 oslProcessError SAL_CALL osl_setEnvironment(rtl_uString *strVar, rtl_uString *strValue);
394 
395 /** Unsets the value of one environment variable.
396 	@param strVar [in] denotes the name of the variable to unset.
397 
398 	@since UDK 3.2.13
399 */
400 oslProcessError SAL_CALL osl_clearEnvironment(rtl_uString *strVar);
401 
402 /** Get the working directory of the current process as a file URL.
403 
404 	The file URL is encoded as common for the OSL file API.
405 	@param	pustrWorkingDir [out] string that receives the working directory file URL.
406 */
407 
408 oslProcessError SAL_CALL osl_getProcessWorkingDir( rtl_uString **pustrWorkingDir );
409 
410 /** Get the locale the process is currently running in.
411 
412 	The unix implementation caches the value it returns, so if you have to change the locale
413     your are running in, you will have to use osl_setProcessLocale therefor.
414 
415 	@param	ppLocale [out] a pointer that receives the currently selected locale structure
416     @see osl_setProcessLocale
417 */
418 
419 oslProcessError SAL_CALL osl_getProcessLocale( rtl_Locale ** ppLocale );
420 
421 /** Change the locale of the process.
422 
423 	@param	pLocale [in] a pointer to the locale to be set
424     @see osl_getProcessLocale
425 */
426 
427 oslProcessError SAL_CALL osl_setProcessLocale( rtl_Locale * pLocale );
428 
429 
430 sal_Bool SAL_CALL osl_sendResourcePipe(oslPipe Pipe, oslSocket Socket);
431 
432 oslSocket SAL_CALL osl_receiveResourcePipe(oslPipe Pipe);
433 
434 #ifdef __cplusplus
435 }
436 #endif
437 
438 #endif    /* _OSL_PROCESS_H_ */
439 
440