le_appProc_interface.h

Go to the documentation of this file.
1 
2 
3 /*
4  * ====================== WARNING ======================
5  *
6  * THE CONTENTS OF THIS FILE HAVE BEEN AUTO-GENERATED.
7  * DO NOT MODIFY IN ANY WAY.
8  *
9  * ====================== WARNING ======================
10  */
11 
12 /**
13  * @page c_appProc Application Process Execution API
14  *
15  * @ref le_appProc_interface.h "API Reference"
16  *
17  * API for creating and running processes within an application that the app would not normally
18  * start on its own.
19  *
20  * This API can be used for testing and debugging purposes and should only be made available to
21  * trusted applications/tools.
22  *
23  * <HR>
24  *
25  * Copyright (C) Sierra Wireless Inc.
26  */
27 /**
28  * @file le_appProc_interface.h
29  *
30  * Legato @ref c_appProc include file.
31  *
32  * Copyright (C) Sierra Wireless Inc.
33  */
34 
35 #ifndef LE_APPPROC_INTERFACE_H_INCLUDE_GUARD
36 #define LE_APPPROC_INTERFACE_H_INCLUDE_GUARD
37 
38 
39 #include "legato.h"
40 
41 // Interface specific includes
42 #include "le_limit_interface.h"
43 
44 
45 //--------------------------------------------------------------------------------------------------
46 /**
47  * Type for handler called when a server disconnects.
48  */
49 //--------------------------------------------------------------------------------------------------
50 typedef void (*le_appProc_DisconnectHandler_t)(void *);
51 
52 //--------------------------------------------------------------------------------------------------
53 /**
54  *
55  * Connect the current client thread to the service providing this API. Block until the service is
56  * available.
57  *
58  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
59  * called before any other functions in this API. Normally, ConnectService is automatically called
60  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
61  *
62  * This function is created automatically.
63  */
64 //--------------------------------------------------------------------------------------------------
66 (
67  void
68 );
69 
70 //--------------------------------------------------------------------------------------------------
71 /**
72  *
73  * Try to connect the current client thread to the service providing this API. Return with an error
74  * if the service is not available.
75  *
76  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
77  * called before any other functions in this API. Normally, ConnectService is automatically called
78  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
79  *
80  * This function is created automatically.
81  *
82  * @return
83  * - LE_OK if the client connected successfully to the service.
84  * - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
85  * bound.
86  * - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
87  * - LE_COMM_ERROR if the Service Directory cannot be reached.
88  */
89 //--------------------------------------------------------------------------------------------------
91 (
92  void
93 );
94 
95 //--------------------------------------------------------------------------------------------------
96 /**
97  * Set handler called when server disconnection is detected.
98  *
99  * When a server connection is lost, call this handler then exit with LE_FATAL. If a program wants
100  * to continue without exiting, it should call longjmp() from inside the handler.
101  */
102 //--------------------------------------------------------------------------------------------------
104 (
105  le_appProc_DisconnectHandler_t disconnectHandler,
106  void *contextPtr
107 );
108 
109 //--------------------------------------------------------------------------------------------------
110 /**
111  *
112  * Disconnect the current client thread from the service providing this API.
113  *
114  * Normally, this function doesn't need to be called. After this function is called, there's no
115  * longer a connection to the service, and the functions in this API can't be used. For details, see
116  * @ref apiFilesC_client.
117  *
118  * This function is created automatically.
119  */
120 //--------------------------------------------------------------------------------------------------
122 (
123  void
124 );
125 
126 
127 //--------------------------------------------------------------------------------------------------
128 /**
129  * Reference to application process objects.
130  */
131 //--------------------------------------------------------------------------------------------------
132 typedef struct le_appProc_Ref* le_appProc_RefRef_t;
133 
134 
135 //--------------------------------------------------------------------------------------------------
136 /**
137  * Fault action for a process.
138  */
139 //--------------------------------------------------------------------------------------------------
140 typedef enum
141 {
143  ///< A fault occured but no further action is required.
145  ///< The process should be restarted.
147  ///< The application should be restarted.
149  ///< The application should be terminated.
151  ///< The system should be rebooted.
152 }
154 
155 
156 //--------------------------------------------------------------------------------------------------
157 /**
158  * Reference type used by Add/Remove functions for EVENT 'le_appProc_Stop'
159  */
160 //--------------------------------------------------------------------------------------------------
161 typedef struct le_appProc_StopHandler* le_appProc_StopHandlerRef_t;
162 
163 
164 //--------------------------------------------------------------------------------------------------
165 /**
166  * A handler that is called when the application process exits.
167  */
168 //--------------------------------------------------------------------------------------------------
169 typedef void (*le_appProc_StopHandlerFunc_t)
170 (
171  int32_t exitCode,
172  ///< Exit code of the process.
173  void* contextPtr
174  ///<
175 );
176 
177 //--------------------------------------------------------------------------------------------------
178 /**
179  * Creates a process in an app. This function can be used to create and subsequently start a
180  * process in an application that the application normally would not start on its own. This
181  * function does not actually start the process, use Start() to start the process.
182  *
183  * If the specified process name matches a name in the app's list of configured processes then
184  * runtime parameters such as environment variables, priority, etc. will be taken from the
185  * configuration database. Otherwise default parameters will be used.
186  *
187  * Parameters can be overridden by the other functions in this API such as AddArg(), SetPriority(),
188  * etc.
189  *
190  * If the executable path is empty and the process name matches a configured process then the
191  * configured executable is used. Otherwise the specified executable path is used.
192  *
193  * Either the process name or the executable path may be empty but not both.
194  *
195  * It is an error to call this function on a configured process that is already running.
196  *
197  * @return
198  * Reference to the application process object if successful.
199  * NULL if there was an error.
200  *
201  * @note If the application or process names pointers are null or if their strings are empty or of
202  * bad format it is a fatal error, the function will not return.
203  */
204 //--------------------------------------------------------------------------------------------------
206 (
207  const char* appName,
208  ///< [IN] Name of the app.
209  const char* procName,
210  ///< [IN] Name of the process.
211  const char* execPath
212  ///< [IN] Path to the executable file.
213 )
214 __attribute__(( nonnull(1,2,3) ));
215 
216 //--------------------------------------------------------------------------------------------------
217 /**
218  * Sets the file descriptor that the application process's standard in should be attached to.
219  *
220  * By default the standard in is directed to /dev/null.
221  *
222  * If there is an error this function will kill the calling process
223  */
224 //--------------------------------------------------------------------------------------------------
226 (
227  le_appProc_RefRef_t appProcRef,
228  ///< [IN] Application process to start.
229  int stdInFd
230  ///< [IN] File descriptor to use as the app proc's standard in.
231  ///< -1 means direct to /dev/null.
232 );
233 
234 //--------------------------------------------------------------------------------------------------
235 /**
236  * Sets the file descriptor that the application process's standard out should be attached to.
237  *
238  * By default the standard out is directed to the logs.
239  *
240  * If there is an error this function will kill the calling process
241  */
242 //--------------------------------------------------------------------------------------------------
244 (
245  le_appProc_RefRef_t appProcRef,
246  ///< [IN] Application process to start.
247  int stdOutFd
248  ///< [IN] File descriptor to use as the app proc's standard out.
249  ///< -1 means direct to logs.
250 );
251 
252 //--------------------------------------------------------------------------------------------------
253 /**
254  * Sets the file descriptor that the application process's standard err should be attached to.
255  *
256  * By default the standard err is directed to the logs.
257  *
258  * If there is an error this function will kill the calling process
259  */
260 //--------------------------------------------------------------------------------------------------
262 (
263  le_appProc_RefRef_t appProcRef,
264  ///< [IN] Application process to start.
265  int stdErrFd
266  ///< [IN] File descriptor to use as the app proc's standard error.
267  ///< -1 means direct to logs.
268 );
269 
270 //--------------------------------------------------------------------------------------------------
271 /**
272  * Add handler function for EVENT 'le_appProc_Stop'
273  *
274  * Process stopped event.
275  */
276 //--------------------------------------------------------------------------------------------------
278 (
279  le_appProc_RefRef_t appProcRef,
280  ///< [IN] Application process to start.
281  le_appProc_StopHandlerFunc_t handlerPtr,
282  ///< [IN] Handler for the event.
283  void* contextPtr
284  ///< [IN]
285 );
286 
287 //--------------------------------------------------------------------------------------------------
288 /**
289  * Remove handler function for EVENT 'le_appProc_Stop'
290  */
291 //--------------------------------------------------------------------------------------------------
293 (
294  le_appProc_StopHandlerRef_t handlerRef
295  ///< [IN]
296 );
297 
298 //--------------------------------------------------------------------------------------------------
299 /**
300  * Adds a command line argument to the application process.
301  *
302  * If the application process is a configured process adding any argument means no arguments from
303  * the configuration database will be used.
304  *
305  * Adding an empty argument validates the argument list but does not acutally add an argument. This
306  * is useful for overriding the configured arguments list with an empty argument list.
307  *
308  * If there is an error this function will kill the calling client.
309  */
310 //--------------------------------------------------------------------------------------------------
312 (
313  le_appProc_RefRef_t appProcRef,
314  ///< [IN] Application process to start.
315  const char* arg
316  ///< [IN] Argument to add.
317 )
318 __attribute__(( nonnull(2) ));
319 
320 //--------------------------------------------------------------------------------------------------
321 /**
322  * Deletes and invalidates the cmd-line arguments to a process and use the configured arguments if
323  * available.
324  *
325  * @note If the caller is passing an invalid reference to the application process, it is a fatal
326  * error, the function will not return.
327  */
328 //--------------------------------------------------------------------------------------------------
330 (
331  le_appProc_RefRef_t appProcRef
332  ///< [IN] Application process to start.
333 );
334 
335 //--------------------------------------------------------------------------------------------------
336 /**
337  * Sets the application process's priority.
338  *
339  * The priority string must be either 'idle','low', 'medium', 'high', 'rt1', 'rt2'...'rt32'.
340  *
341  * If there is an error this function will kill the client.
342  */
343 //--------------------------------------------------------------------------------------------------
345 (
346  le_appProc_RefRef_t appProcRef,
347  ///< [IN] Application process to start.
348  const char* priority
349  ///< [IN] Priority for the application process.
350 )
351 __attribute__(( nonnull(2) ));
352 
353 //--------------------------------------------------------------------------------------------------
354 /**
355  * Clears the application process's priority and use either the configured priority or the default.
356  *
357  * @note If the caller is passing an invalid reference to the application process, it is a fatal
358  * error, the function will not return.
359  */
360 //--------------------------------------------------------------------------------------------------
362 (
363  le_appProc_RefRef_t appProcRef
364  ///< [IN] Application process to start.
365 );
366 
367 //--------------------------------------------------------------------------------------------------
368 /**
369  * Sets the application process's fault action.
370  *
371  * @note If the caller is passing an invalid reference to the application process, it is a fatal
372  * error, the function will not return.
373  */
374 //--------------------------------------------------------------------------------------------------
376 (
377  le_appProc_RefRef_t appProcRef,
378  ///< [IN] Application process to start.
380  ///< [IN] Fault action for the application process.
381 );
382 
383 //--------------------------------------------------------------------------------------------------
384 /**
385  * Clears the application process's fault action and use either the configured fault action or the
386  * default.
387  *
388  * @note If the caller is passing an invalid reference to the application process, it is a fatal
389  * error, the function will not return.
390  */
391 //--------------------------------------------------------------------------------------------------
393 (
394  le_appProc_RefRef_t appProcRef
395  ///< [IN] Application process to start.
396 );
397 
398 //--------------------------------------------------------------------------------------------------
399 /**
400  * Starts the application process. If the application was not running this function will start it
401  * first.
402  *
403  * @return
404  * LE_OK if successful.
405  * LE_FAULT if there was some other error.
406  *
407  * @note If the caller is passing an invalid reference to the application process, it is a fatal
408  * error, the function will not return.
409  */
410 //--------------------------------------------------------------------------------------------------
412 (
413  le_appProc_RefRef_t appProcRef
414  ///< [IN] Application process to start.
415 );
416 
417 //--------------------------------------------------------------------------------------------------
418 /**
419  * Deletes the application process object.
420  *
421  * @note If the caller is passing an invalid reference to the application process, it is a fatal
422  * error, the function will not return.
423  */
424 //--------------------------------------------------------------------------------------------------
426 (
427  le_appProc_RefRef_t appProcRef
428  ///< [IN] Application process to start.
429 );
430 
431 #endif // LE_APPPROC_INTERFACE_H_INCLUDE_GUARD
void le_appProc_SetServerDisconnectHandler(le_appProc_DisconnectHandler_t disconnectHandler, void *contextPtr)
void le_appProc_ClearPriority(le_appProc_RefRef_t appProcRef)
void le_appProc_SetStdOut(le_appProc_RefRef_t appProcRef, int stdOutFd)
void(* le_appProc_StopHandlerFunc_t)(int32_t exitCode, void *contextPtr)
Definition: le_appProc_interface.h:170
void le_appProc_ClearFaultAction(le_appProc_RefRef_t appProcRef)
void le_appProc_SetFaultAction(le_appProc_RefRef_t appProcRef, le_appProc_FaultAction_t action)
le_result_t
Definition: le_basics.h:35
void le_appProc_ConnectService(void)
le_appProc_FaultAction_t
Definition: le_appProc_interface.h:140
le_result_t le_appProc_TryConnectService(void)
The application should be restarted.
Definition: le_appProc_interface.h:146
void le_appProc_SetPriority(le_appProc_RefRef_t appProcRef, const char *priority)
The system should be rebooted.
Definition: le_appProc_interface.h:150
void le_appProc_AddArg(le_appProc_RefRef_t appProcRef, const char *arg)
void le_appProc_DisconnectService(void)
void le_appProc_Delete(le_appProc_RefRef_t appProcRef)
A fault occured but no further action is required.
Definition: le_appProc_interface.h:142
void le_appProc_SetStdErr(le_appProc_RefRef_t appProcRef, int stdErrFd)
struct le_appProc_StopHandler * le_appProc_StopHandlerRef_t
Definition: le_appProc_interface.h:161
The application should be terminated.
Definition: le_appProc_interface.h:148
void le_appProc_SetStdIn(le_appProc_RefRef_t appProcRef, int stdInFd)
le_result_t le_appProc_Start(le_appProc_RefRef_t appProcRef)
le_appProc_StopHandlerRef_t le_appProc_AddStopHandler(le_appProc_RefRef_t appProcRef, le_appProc_StopHandlerFunc_t handlerPtr, void *contextPtr)
void le_appProc_RemoveStopHandler(le_appProc_StopHandlerRef_t handlerRef)
void le_appProc_ClearArgs(le_appProc_RefRef_t appProcRef)
struct le_appProc_Ref * le_appProc_RefRef_t
Definition: le_appProc_interface.h:132
le_appProc_RefRef_t le_appProc_Create(const char *appName, const char *procName, const char *execPath)
The process should be restarted.
Definition: le_appProc_interface.h:144
void(* le_appProc_DisconnectHandler_t)(void *)
Definition: le_appProc_interface.h:50