le_appProc_interface.h

    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 //--------------------------------------------------------------------------------------------------
   65 void le_appProc_ConnectService
   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 //--------------------------------------------------------------------------------------------------
   90 le_result_t le_appProc_TryConnectService
   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 //--------------------------------------------------------------------------------------------------
  103 void le_appProc_SetServerDisconnectHandler
  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 //--------------------------------------------------------------------------------------------------
  121 void le_appProc_DisconnectService
  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 {
  142     LE_APPPROC_FAULT_ACTION_IGNORE = 0,
  143         ///< A fault occured but no further action is required.
  144     LE_APPPROC_FAULT_ACTION_RESTART_PROC = 1,
  145         ///< The process should be restarted.
  146     LE_APPPROC_FAULT_ACTION_RESTART_APP = 2,
  147         ///< The application should be restarted.
  148     LE_APPPROC_FAULT_ACTION_STOP_APP = 3,
  149         ///< The application should be terminated.
  150     LE_APPPROC_FAULT_ACTION_REBOOT = 4
  151         ///< The system should be rebooted.
  152 }
  153 le_appProc_FaultAction_t;
  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 //--------------------------------------------------------------------------------------------------
  205 le_appProc_RefRef_t le_appProc_Create
  206 (
  207     const char* LE_NONNULL appName,
  208         ///< [IN] Name of the app.
  209     const char* LE_NONNULL procName,
  210         ///< [IN] Name of the process.
  211     const char* LE_NONNULL execPath
  212         ///< [IN] Path to the executable file.
  213 );
  214 
  215 //--------------------------------------------------------------------------------------------------
  216 /**
  217  * Sets the file descriptor that the application process's standard in should be attached to.
  218  *
  219  * By default the standard in is directed to /dev/null.
  220  *
  221  * If there is an error this function will kill the calling process
  222  */
  223 //--------------------------------------------------------------------------------------------------
  224 void le_appProc_SetStdIn
  225 (
  226     le_appProc_RefRef_t appProcRef,
  227         ///< [IN] Application process to start.
  228     int stdInFd
  229         ///< [IN] File descriptor to use as the app proc's standard in.
  230         ///< -1 means direct to /dev/null.
  231 );
  232 
  233 //--------------------------------------------------------------------------------------------------
  234 /**
  235  * Sets the file descriptor that the application process's standard out should be attached to.
  236  *
  237  * By default the standard out is directed to the logs.
  238  *
  239  * If there is an error this function will kill the calling process
  240  */
  241 //--------------------------------------------------------------------------------------------------
  242 void le_appProc_SetStdOut
  243 (
  244     le_appProc_RefRef_t appProcRef,
  245         ///< [IN] Application process to start.
  246     int stdOutFd
  247         ///< [IN] File descriptor to use as the app proc's standard out.
  248         ///<  -1 means direct to logs.
  249 );
  250 
  251 //--------------------------------------------------------------------------------------------------
  252 /**
  253  * Sets the file descriptor that the application process's standard err should be attached to.
  254  *
  255  * By default the standard err is directed to the logs.
  256  *
  257  * If there is an error this function will kill the calling process
  258  */
  259 //--------------------------------------------------------------------------------------------------
  260 void le_appProc_SetStdErr
  261 (
  262     le_appProc_RefRef_t appProcRef,
  263         ///< [IN] Application process to start.
  264     int stdErrFd
  265         ///< [IN] File descriptor to use as the app proc's standard error.
  266         ///< -1 means direct to logs.
  267 );
  268 
  269 //--------------------------------------------------------------------------------------------------
  270 /**
  271  * Add handler function for EVENT 'le_appProc_Stop'
  272  *
  273  * Process stopped event.
  274  */
  275 //--------------------------------------------------------------------------------------------------
  276 le_appProc_StopHandlerRef_t le_appProc_AddStopHandler
  277 (
  278     le_appProc_RefRef_t appProcRef,
  279         ///< [IN] Application process to start.
  280     le_appProc_StopHandlerFunc_t handlerPtr,
  281         ///< [IN] Handler for the event.
  282     void* contextPtr
  283         ///< [IN]
  284 );
  285 
  286 //--------------------------------------------------------------------------------------------------
  287 /**
  288  * Remove handler function for EVENT 'le_appProc_Stop'
  289  */
  290 //--------------------------------------------------------------------------------------------------
  291 void le_appProc_RemoveStopHandler
  292 (
  293     le_appProc_StopHandlerRef_t handlerRef
  294         ///< [IN]
  295 );
  296 
  297 //--------------------------------------------------------------------------------------------------
  298 /**
  299  * Adds a command line argument to the application process.
  300  *
  301  * If the application process is a configured process adding any argument means no arguments from
  302  * the configuration database will be used.
  303  *
  304  * Adding an empty argument validates the argument list but does not acutally add an argument. This
  305  * is useful for overriding the configured arguments list with an empty argument list.
  306  *
  307  * If there is an error this function will kill the calling client.
  308  */
  309 //--------------------------------------------------------------------------------------------------
  310 void le_appProc_AddArg
  311 (
  312     le_appProc_RefRef_t appProcRef,
  313         ///< [IN] Application process to start.
  314     const char* LE_NONNULL arg
  315         ///< [IN] Argument to add.
  316 );
  317 
  318 //--------------------------------------------------------------------------------------------------
  319 /**
  320  * Deletes and invalidates the cmd-line arguments to a process and use the configured arguments if
  321  * available.
  322  *
  323  * @note If the caller is passing an invalid reference to the application process, it is a fatal
  324  *       error, the function will not return.
  325  */
  326 //--------------------------------------------------------------------------------------------------
  327 void le_appProc_ClearArgs
  328 (
  329     le_appProc_RefRef_t appProcRef
  330         ///< [IN] Application process to start.
  331 );
  332 
  333 //--------------------------------------------------------------------------------------------------
  334 /**
  335  * Sets the application process's priority.
  336  *
  337  * The priority string must be either 'idle','low', 'medium', 'high', 'rt1', 'rt2'...'rt32'.
  338  *
  339  * If there is an error this function will kill the client.
  340  */
  341 //--------------------------------------------------------------------------------------------------
  342 void le_appProc_SetPriority
  343 (
  344     le_appProc_RefRef_t appProcRef,
  345         ///< [IN] Application process to start.
  346     const char* LE_NONNULL priority
  347         ///< [IN] Priority for the application process.
  348 );
  349 
  350 //--------------------------------------------------------------------------------------------------
  351 /**
  352  * Clears the application process's priority and use either the configured priority or the default.
  353  *
  354  * @note If the caller is passing an invalid reference to the application process, it is a fatal
  355  *       error, the function will not return.
  356  */
  357 //--------------------------------------------------------------------------------------------------
  358 void le_appProc_ClearPriority
  359 (
  360     le_appProc_RefRef_t appProcRef
  361         ///< [IN] Application process to start.
  362 );
  363 
  364 //--------------------------------------------------------------------------------------------------
  365 /**
  366  * Sets the application process's fault action.
  367  *
  368  * @note If the caller is passing an invalid reference to the application process, it is a fatal
  369  *       error, the function will not return.
  370  */
  371 //--------------------------------------------------------------------------------------------------
  372 void le_appProc_SetFaultAction
  373 (
  374     le_appProc_RefRef_t appProcRef,
  375         ///< [IN] Application process to start.
  376     le_appProc_FaultAction_t action
  377         ///< [IN] Fault action for the application process.
  378 );
  379 
  380 //--------------------------------------------------------------------------------------------------
  381 /**
  382  * Clears the application process's fault action and use either the configured fault action or the
  383  * default.
  384  *
  385  * @note If the caller is passing an invalid reference to the application process, it is a fatal
  386  *       error, the function will not return.
  387  */
  388 //--------------------------------------------------------------------------------------------------
  389 void le_appProc_ClearFaultAction
  390 (
  391     le_appProc_RefRef_t appProcRef
  392         ///< [IN] Application process to start.
  393 );
  394 
  395 //--------------------------------------------------------------------------------------------------
  396 /**
  397  * Starts the application process.  If the application was not running this function will start it
  398  * first.
  399  *
  400  * @return
  401  *      LE_OK if successful.
  402  *      LE_FAULT if there was some other error.
  403  *
  404  * @note If the caller is passing an invalid reference to the application process, it is a fatal
  405  *       error, the function will not return.
  406  */
  407 //--------------------------------------------------------------------------------------------------
  408 le_result_t le_appProc_Start
  409 (
  410     le_appProc_RefRef_t appProcRef
  411         ///< [IN] Application process to start.
  412 );
  413 
  414 //--------------------------------------------------------------------------------------------------
  415 /**
  416  * Deletes the application process object.
  417  *
  418  * @note If the caller is passing an invalid reference to the application process, it is a fatal
  419  *       error, the function will not return.
  420  */
  421 //--------------------------------------------------------------------------------------------------
  422 void le_appProc_Delete
  423 (
  424     le_appProc_RefRef_t appProcRef
  425         ///< [IN] Application process to start.
  426 );
  427 
  428 #endif // LE_APPPROC_INTERFACE_H_INCLUDE_GUARD
le_appProc_SetServerDisconnectHandler
void le_appProc_SetServerDisconnectHandler(le_appProc_DisconnectHandler_t disconnectHandler, void *contextPtr)
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_StopHandlerFunc_t
void(* le_appProc_StopHandlerFunc_t)(int32_t exitCode, void *contextPtr)
Definition: le_appProc_interface.h:170
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:140
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:146
le_appProc_AddArg
void le_appProc_AddArg(le_appProc_RefRef_t appProcRef, const char *LE_NONNULL arg)
LE_APPPROC_FAULT_ACTION_REBOOT
The system should be rebooted. 
Definition: le_appProc_interface.h:150
le_appProc_DisconnectService
void le_appProc_DisconnectService(void)
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:142
le_appProc_SetStdErr
void le_appProc_SetStdErr(le_appProc_RefRef_t appProcRef, int stdErrFd)
le_appProc_SetPriority
void le_appProc_SetPriority(le_appProc_RefRef_t appProcRef, const char *LE_NONNULL priority)
le_limit_interface.h
le_appProc_Create
le_appProc_RefRef_t le_appProc_Create(const char *LE_NONNULL appName, const char *LE_NONNULL procName, const char *LE_NONNULL execPath)
le_appProc_StopHandlerRef_t
struct le_appProc_StopHandler * le_appProc_StopHandlerRef_t
Definition: le_appProc_interface.h:161
LE_APPPROC_FAULT_ACTION_STOP_APP
The application should be terminated. 
Definition: le_appProc_interface.h:148
legato.h
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_RemoveStopHandler
void le_appProc_RemoveStopHandler(le_appProc_StopHandlerRef_t handlerRef)
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:132
LE_APPPROC_FAULT_ACTION_RESTART_PROC
The process should be restarted. 
Definition: le_appProc_interface.h:144
le_appProc_DisconnectHandler_t
void(* le_appProc_DisconnectHandler_t)(void *)
Definition: le_appProc_interface.h:50