le_appProc_interface.h

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