le_appCtrl_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_appCtrl App Control API
   14  *
   15  * @ref le_appCtrl_interface.h "API Reference"
   16  *
   17  * API for controlling the applications. This API should only be made available to privileged users.
   18  *
   19  * @section legatoServicesSupervisor_binding Binding
   20  *
   21  * You can use a definition @c .adef file to bind your client-side app and component to the
   22  * server-side App Control service.
   23  *
   24  * This code sample shows how to bind an app to this service:
   25  * @code
   26  * bindings
   27  * {
   28  *     myExe.myComp.le_appCtrl -> <root>.le_appCtrl
   29  * }
   30  * @endcode
   31  *
   32  * See @ref defFilesAdef for details.
   33  *
   34  * @section legatoServicesSupervisor_start Start App
   35  *
   36  * Use le_appCtrl_StartApp() (const char * appName) to start an app.
   37  *
   38  * The code sample shows how to use the App Control service to start an app:
   39  *
   40  * @code
   41  *  le_result_t result = le_appCtrl_Start("myApp");
   42  * @endcode
   43  *
   44  * where @c myApp is the name of the app.
   45  *
   46  * @section legatoServicesSupervisor_stop Stop App
   47  *
   48  * Use le_appCtrl_Stop() to stop an app.
   49  *
   50  * This code sample shows how to use the App Control service to stop an app.
   51  *
   52  * @code
   53  * le_result_t result = le_appCtrl_Stop("myApp");
   54  * @endcode
   55  *
   56  * where @c myApp is the name of the app.
   57  *
   58  * <HR>
   59  *
   60  * Copyright (C) Sierra Wireless Inc.
   61  */
   62 /**
   63  * @file le_appCtrl_interface.h
   64  *
   65  * Legato @ref c_appCtrl include file.
   66  *
   67  * Copyright (C) Sierra Wireless Inc.
   68  */
   69 
   70 #ifndef LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
   71 #define LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
   72 
   73 
   74 #include "legato.h"
   75 
   76 // Interface specific includes
   77 #include "le_limit_interface.h"
   78 
   79 
   80 //--------------------------------------------------------------------------------------------------
   81 /**
   82  * Type for handler called when a server disconnects.
   83  */
   84 //--------------------------------------------------------------------------------------------------
   85 typedef void (*le_appCtrl_DisconnectHandler_t)(void *);
   86 
   87 //--------------------------------------------------------------------------------------------------
   88 /**
   89  *
   90  * Connect the current client thread to the service providing this API. Block until the service is
   91  * available.
   92  *
   93  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
   94  * called before any other functions in this API.  Normally, ConnectService is automatically called
   95  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
   96  *
   97  * This function is created automatically.
   98  */
   99 //--------------------------------------------------------------------------------------------------
  100 void le_appCtrl_ConnectService
  101 (
  102     void
  103 );
  104 
  105 //--------------------------------------------------------------------------------------------------
  106 /**
  107  *
  108  * Try to connect the current client thread to the service providing this API. Return with an error
  109  * if the service is not available.
  110  *
  111  * For each thread that wants to use this API, either ConnectService or TryConnectService must be
  112  * called before any other functions in this API.  Normally, ConnectService is automatically called
  113  * for the main thread, but not for any other thread. For details, see @ref apiFilesC_client.
  114  *
  115  * This function is created automatically.
  116  *
  117  * @return
  118  *  - LE_OK if the client connected successfully to the service.
  119  *  - LE_UNAVAILABLE if the server is not currently offering the service to which the client is
  120  *    bound.
  121  *  - LE_NOT_PERMITTED if the client interface is not bound to any service (doesn't have a binding).
  122  *  - LE_COMM_ERROR if the Service Directory cannot be reached.
  123  */
  124 //--------------------------------------------------------------------------------------------------
  125 le_result_t le_appCtrl_TryConnectService
  126 (
  127     void
  128 );
  129 
  130 //--------------------------------------------------------------------------------------------------
  131 /**
  132  * Set handler called when server disconnection is detected.
  133  *
  134  * When a server connection is lost, call this handler then exit with LE_FATAL.  If a program wants
  135  * to continue without exiting, it should call longjmp() from inside the handler.
  136  */
  137 //--------------------------------------------------------------------------------------------------
  138 void le_appCtrl_SetServerDisconnectHandler
  139 (
  140     le_appCtrl_DisconnectHandler_t disconnectHandler,
  141     void *contextPtr
  142 );
  143 
  144 //--------------------------------------------------------------------------------------------------
  145 /**
  146  *
  147  * Disconnect the current client thread from the service providing this API.
  148  *
  149  * Normally, this function doesn't need to be called. After this function is called, there's no
  150  * longer a connection to the service, and the functions in this API can't be used. For details, see
  151  * @ref apiFilesC_client.
  152  *
  153  * This function is created automatically.
  154  */
  155 //--------------------------------------------------------------------------------------------------
  156 void le_appCtrl_DisconnectService
  157 (
  158     void
  159 );
  160 
  161 
  162 //--------------------------------------------------------------------------------------------------
  163 /**
  164  */
  165 //--------------------------------------------------------------------------------------------------
  166 typedef struct le_appCtrl_App* le_appCtrl_AppRef_t;
  167 
  168 
  169 //--------------------------------------------------------------------------------------------------
  170 /**
  171  * Reference type used by Add/Remove functions for EVENT 'le_appCtrl_TraceAttach'
  172  */
  173 //--------------------------------------------------------------------------------------------------
  174 typedef struct le_appCtrl_TraceAttachHandler* le_appCtrl_TraceAttachHandlerRef_t;
  175 
  176 
  177 //--------------------------------------------------------------------------------------------------
  178 /**
  179  * Handler for attaching to a process that is to be traced.  The process is blocked allowing the
  180  * tracer to attach to it.  The tracer must call TraceUnblock() to unblock the traced process.
  181  */
  182 //--------------------------------------------------------------------------------------------------
  183 typedef void (*le_appCtrl_TraceAttachHandlerFunc_t)
  184 (
  185     le_appCtrl_AppRef_t appRef,
  186         ///< Ref to the app.
  187     int32_t pid,
  188         ///< PID of a process that can be attached to.
  189     const char* procName,
  190         ///< Name of the process name.
  191     void* contextPtr
  192         ///<
  193 );
  194 
  195 //--------------------------------------------------------------------------------------------------
  196 /**
  197  * Gets a reference to an application.
  198  *
  199  * @return
  200  *      Reference to the named app.
  201  *      NULL if the app is not installed.
  202  */
  203 //--------------------------------------------------------------------------------------------------
  204 le_appCtrl_AppRef_t le_appCtrl_GetRef
  205 (
  206     const char* appName
  207         ///< [IN] Name of the app to get the ref for.
  208 )
  209 __attribute__(( nonnull(1) ));
  210 
  211 //--------------------------------------------------------------------------------------------------
  212 /**
  213  * Release the reference to an application.
  214  */
  215 //--------------------------------------------------------------------------------------------------
  216 void le_appCtrl_ReleaseRef
  217 (
  218     le_appCtrl_AppRef_t appRef
  219         ///< [IN] Ref to the app.
  220 );
  221 
  222 //--------------------------------------------------------------------------------------------------
  223 /**
  224  * Sets the run flag for a process in an application.
  225  *
  226  * If there is an error this function will kill the calling client.
  227  */
  228 //--------------------------------------------------------------------------------------------------
  229 void le_appCtrl_SetRun
  230 (
  231     le_appCtrl_AppRef_t appRef,
  232         ///< [IN] Ref to the app.
  233     const char* procName,
  234         ///< [IN] Process name to set the run flag for.
  235     bool run
  236         ///< [IN] Flag to run the process or not.
  237 )
  238 __attribute__(( nonnull(2) ));
  239 
  240 //--------------------------------------------------------------------------------------------------
  241 /**
  242  * Imports a file into the app's working directory.
  243  *
  244  * @return
  245  *      LE_OK if successfully imported the file.
  246  *      LE_DUPLICATE if the path conflicts with items already in the app's working directory.
  247  *      LE_NOT_FOUND if the path does not point to a valid file.
  248  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  249  *      LE_FAULT if there was some other error.
  250  *
  251  * @note If the caller is passing an invalid reference to the application, it is a fatal error,
  252  *       the function will not return.
  253  */
  254 //--------------------------------------------------------------------------------------------------
  255 le_result_t le_appCtrl_Import
  256 (
  257     le_appCtrl_AppRef_t appRef,
  258         ///< [IN] Ref to the app.
  259     const char* path
  260         ///< [IN] Absolute path to the file to import.
  261 )
  262 __attribute__(( nonnull(2) ));
  263 
  264 //--------------------------------------------------------------------------------------------------
  265 /**
  266  * Sets a device file's permissions.
  267  *
  268  * @return
  269  *      LE_OK if successfully set the device's permissions.
  270  *      LE_NOT_FOUND if the path does not point to a valid device.
  271  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  272  *      LE_FAULT if there was some other error.
  273  *
  274  * @note If the caller is passing an invalid reference to the application, it is a fatal error,
  275  *       the function will not return.
  276  */
  277 //--------------------------------------------------------------------------------------------------
  278 le_result_t le_appCtrl_SetDevicePerm
  279 (
  280     le_appCtrl_AppRef_t appRef,
  281         ///< [IN] Ref to the app.
  282     const char* path,
  283         ///< [IN] Absolute path to the device.
  284     const char* permissions
  285         ///< [IN] Permission string, "r", "w", "rw".
  286 )
  287 __attribute__(( nonnull(2,3) ));
  288 
  289 //--------------------------------------------------------------------------------------------------
  290 /**
  291  * Add handler function for EVENT 'le_appCtrl_TraceAttach'
  292  *
  293  * Event that indicates the process is blocked and can be attached to.
  294  */
  295 //--------------------------------------------------------------------------------------------------
  296 le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler
  297 (
  298     le_appCtrl_AppRef_t appRef,
  299         ///< [IN] Ref to the app.
  300     le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr,
  301         ///< [IN] Attach handler to register.
  302     void* contextPtr
  303         ///< [IN]
  304 );
  305 
  306 //--------------------------------------------------------------------------------------------------
  307 /**
  308  * Remove handler function for EVENT 'le_appCtrl_TraceAttach'
  309  */
  310 //--------------------------------------------------------------------------------------------------
  311 void le_appCtrl_RemoveTraceAttachHandler
  312 (
  313     le_appCtrl_TraceAttachHandlerRef_t handlerRef
  314         ///< [IN]
  315 );
  316 
  317 //--------------------------------------------------------------------------------------------------
  318 /**
  319  * Unblocks the traced process.  This should normally be done once the tracer has successfully
  320  * attached to the process.
  321  *
  322  * @note If the caller is passing an invalid reference to the application, it is a fatal error,
  323  *       the function will not return.
  324  */
  325 //--------------------------------------------------------------------------------------------------
  326 void le_appCtrl_TraceUnblock
  327 (
  328     le_appCtrl_AppRef_t appRef,
  329         ///< [IN] Ref to the app.
  330     int32_t pid
  331         ///< [IN] PID of the process to unblock.
  332 );
  333 
  334 //--------------------------------------------------------------------------------------------------
  335 /**
  336  * Starts an app.
  337  *
  338  * @return
  339  *      LE_OK if the app is successfully started.
  340  *      LE_DUPLICATE if the app is already running.
  341  *      LE_NOT_FOUND if the app isn't installed.
  342  *      LE_FAULT if there was an error and the app could not be launched.
  343  */
  344 //--------------------------------------------------------------------------------------------------
  345 le_result_t le_appCtrl_Start
  346 (
  347     const char* appName
  348         ///< [IN] Name of the app to start.
  349 )
  350 __attribute__(( nonnull(1) ));
  351 
  352 //--------------------------------------------------------------------------------------------------
  353 /**
  354  * Stops an app.
  355  *
  356  * @return
  357  *      LE_OK if successful.
  358  *      LE_NOT_FOUND if the app could not be found.
  359  */
  360 //--------------------------------------------------------------------------------------------------
  361 le_result_t le_appCtrl_Stop
  362 (
  363     const char* appName
  364         ///< [IN] Name of the app to stop.
  365 )
  366 __attribute__(( nonnull(1) ));
  367 
  368 #endif // LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
le_appCtrl_TraceAttachHandlerFunc_t
void(* le_appCtrl_TraceAttachHandlerFunc_t)(le_appCtrl_AppRef_t appRef, int32_t pid, const char *procName, void *contextPtr)
Definition: le_appCtrl_interface.h:184
le_result_t
le_result_t
Definition: le_basics.h:35
le_appCtrl_RemoveTraceAttachHandler
void le_appCtrl_RemoveTraceAttachHandler(le_appCtrl_TraceAttachHandlerRef_t handlerRef)
le_appCtrl_Stop
le_result_t le_appCtrl_Stop(const char *appName)
le_appCtrl_DisconnectService
void le_appCtrl_DisconnectService(void)
le_appCtrl_TraceAttachHandlerRef_t
struct le_appCtrl_TraceAttachHandler * le_appCtrl_TraceAttachHandlerRef_t
Definition: le_appCtrl_interface.h:174
le_appCtrl_AddTraceAttachHandler
le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler(le_appCtrl_AppRef_t appRef, le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr, void *contextPtr)
le_appCtrl_Start
le_result_t le_appCtrl_Start(const char *appName)
le_appCtrl_TryConnectService
le_result_t le_appCtrl_TryConnectService(void)
le_appCtrl_GetRef
le_appCtrl_AppRef_t le_appCtrl_GetRef(const char *appName)
le_appCtrl_SetDevicePerm
le_result_t le_appCtrl_SetDevicePerm(le_appCtrl_AppRef_t appRef, const char *path, const char *permissions)
le_limit_interface.h
le_appCtrl_DisconnectHandler_t
void(* le_appCtrl_DisconnectHandler_t)(void *)
Definition: le_appCtrl_interface.h:85
le_appCtrl_SetRun
void le_appCtrl_SetRun(le_appCtrl_AppRef_t appRef, const char *procName, bool run)
le_appCtrl_ReleaseRef
void le_appCtrl_ReleaseRef(le_appCtrl_AppRef_t appRef)
legato.h
le_appCtrl_Import
le_result_t le_appCtrl_Import(le_appCtrl_AppRef_t appRef, const char *path)
le_appCtrl_ConnectService
void le_appCtrl_ConnectService(void)
le_appCtrl_SetServerDisconnectHandler
void le_appCtrl_SetServerDisconnectHandler(le_appCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_appCtrl_TraceUnblock
void le_appCtrl_TraceUnblock(le_appCtrl_AppRef_t appRef, int32_t pid)