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