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* 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 //--------------------------------------------------------------------------------------------------
  225 void le_appProc_SetStdIn
  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 //--------------------------------------------------------------------------------------------------
  243 void le_appProc_SetStdOut
  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 //--------------------------------------------------------------------------------------------------
  261 void le_appProc_SetStdErr
  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 //--------------------------------------------------------------------------------------------------
  277 le_appProc_StopHandlerRef_t le_appProc_AddStopHandler
  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 //--------------------------------------------------------------------------------------------------
  292 void le_appProc_RemoveStopHandler
  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 //--------------------------------------------------------------------------------------------------
  311 void le_appProc_AddArg
  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 //--------------------------------------------------------------------------------------------------
  329 void le_appProc_ClearArgs
  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 //--------------------------------------------------------------------------------------------------
  344 void le_appProc_SetPriority
  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 //--------------------------------------------------------------------------------------------------
  361 void le_appProc_ClearPriority
  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 //--------------------------------------------------------------------------------------------------
  375 void le_appProc_SetFaultAction
  376 (
  377     le_appProc_RefRef_t appProcRef,
  378         ///< [IN] Application process to start.
  379     le_appProc_FaultAction_t action
  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 //--------------------------------------------------------------------------------------------------
  392 void le_appProc_ClearFaultAction
  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 //--------------------------------------------------------------------------------------------------
  411 le_result_t le_appProc_Start
  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 //--------------------------------------------------------------------------------------------------
  425 void le_appProc_Delete
  426 (
  427     le_appProc_RefRef_t appProcRef
  428         ///< [IN] Application process to start.
  429 );
  430 
  431 #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_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:150
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_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_limit_interface.h
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_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:144
le_appProc_DisconnectHandler_t
void(* le_appProc_DisconnectHandler_t)(void *)
Definition: le_appProc_interface.h:50