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* LE_NONNULL 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* LE_NONNULL appName
  207         ///< [IN] Name of the app to get the ref for.
  208 );
  209 
  210 //--------------------------------------------------------------------------------------------------
  211 /**
  212  * Release the reference to an application.
  213  */
  214 //--------------------------------------------------------------------------------------------------
  215 void le_appCtrl_ReleaseRef
  216 (
  217     le_appCtrl_AppRef_t appRef
  218         ///< [IN] Ref to the app.
  219 );
  220 
  221 //--------------------------------------------------------------------------------------------------
  222 /**
  223  * Sets the run flag for a process in an application.
  224  *
  225  * If there is an error this function will kill the calling client.
  226  */
  227 //--------------------------------------------------------------------------------------------------
  228 void le_appCtrl_SetRun
  229 (
  230     le_appCtrl_AppRef_t appRef,
  231         ///< [IN] Ref to the app.
  232     const char* LE_NONNULL procName,
  233         ///< [IN] Process name to set the run flag for.
  234     bool run
  235         ///< [IN] Flag to run the process or not.
  236 );
  237 
  238 //--------------------------------------------------------------------------------------------------
  239 /**
  240  * Imports a file into the app's working directory.
  241  *
  242  * @return
  243  *      LE_OK if successfully imported the file.
  244  *      LE_DUPLICATE if the path conflicts with items already in the app's working directory.
  245  *      LE_NOT_FOUND if the path does not point to a valid file.
  246  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  247  *      LE_FAULT if there was some other error.
  248  *
  249  * @note If the caller is passing an invalid reference to the application, it is a fatal error,
  250  *       the function will not return.
  251  */
  252 //--------------------------------------------------------------------------------------------------
  253 le_result_t le_appCtrl_Import
  254 (
  255     le_appCtrl_AppRef_t appRef,
  256         ///< [IN] Ref to the app.
  257     const char* LE_NONNULL path
  258         ///< [IN] Absolute path to the file to import.
  259 );
  260 
  261 //--------------------------------------------------------------------------------------------------
  262 /**
  263  * Sets a device file's permissions.
  264  *
  265  * @return
  266  *      LE_OK if successfully set the device's permissions.
  267  *      LE_NOT_FOUND if the path does not point to a valid device.
  268  *      LE_BAD_PARAMETER if the path is formatted incorrectly.
  269  *      LE_FAULT if there was some other error.
  270  *
  271  * @note If the caller is passing an invalid reference to the application, it is a fatal error,
  272  *       the function will not return.
  273  */
  274 //--------------------------------------------------------------------------------------------------
  275 le_result_t le_appCtrl_SetDevicePerm
  276 (
  277     le_appCtrl_AppRef_t appRef,
  278         ///< [IN] Ref to the app.
  279     const char* LE_NONNULL path,
  280         ///< [IN] Absolute path to the device.
  281     const char* LE_NONNULL permissions
  282         ///< [IN] Permission string, "r", "w", "rw".
  283 );
  284 
  285 //--------------------------------------------------------------------------------------------------
  286 /**
  287  * Add handler function for EVENT 'le_appCtrl_TraceAttach'
  288  *
  289  * Event that indicates the process is blocked and can be attached to.
  290  */
  291 //--------------------------------------------------------------------------------------------------
  292 le_appCtrl_TraceAttachHandlerRef_t le_appCtrl_AddTraceAttachHandler
  293 (
  294     le_appCtrl_AppRef_t appRef,
  295         ///< [IN] Ref to the app.
  296     le_appCtrl_TraceAttachHandlerFunc_t attachToPidPtr,
  297         ///< [IN] Attach handler to register.
  298     void* contextPtr
  299         ///< [IN]
  300 );
  301 
  302 //--------------------------------------------------------------------------------------------------
  303 /**
  304  * Remove handler function for EVENT 'le_appCtrl_TraceAttach'
  305  */
  306 //--------------------------------------------------------------------------------------------------
  307 void le_appCtrl_RemoveTraceAttachHandler
  308 (
  309     le_appCtrl_TraceAttachHandlerRef_t handlerRef
  310         ///< [IN]
  311 );
  312 
  313 //--------------------------------------------------------------------------------------------------
  314 /**
  315  * Unblocks the traced process.  This should normally be done once the tracer has successfully
  316  * attached to the process.
  317  *
  318  * @note If the caller is passing an invalid reference to the application, it is a fatal error,
  319  *       the function will not return.
  320  */
  321 //--------------------------------------------------------------------------------------------------
  322 void le_appCtrl_TraceUnblock
  323 (
  324     le_appCtrl_AppRef_t appRef,
  325         ///< [IN] Ref to the app.
  326     int32_t pid
  327         ///< [IN] PID of the process to unblock.
  328 );
  329 
  330 //--------------------------------------------------------------------------------------------------
  331 /**
  332  * Starts an app.
  333  *
  334  * @return
  335  *      LE_OK if the app is successfully started.
  336  *      LE_DUPLICATE if the app is already running.
  337  *      LE_NOT_FOUND if the app isn't installed.
  338  *      LE_FAULT if there was an error and the app could not be launched.
  339  */
  340 //--------------------------------------------------------------------------------------------------
  341 le_result_t le_appCtrl_Start
  342 (
  343     const char* LE_NONNULL appName
  344         ///< [IN] Name of the app to start.
  345 );
  346 
  347 //--------------------------------------------------------------------------------------------------
  348 /**
  349  * Stops an app.
  350  *
  351  * @return
  352  *      LE_OK if successful.
  353  *      LE_NOT_FOUND if the app could not be found.
  354  */
  355 //--------------------------------------------------------------------------------------------------
  356 le_result_t le_appCtrl_Stop
  357 (
  358     const char* LE_NONNULL appName
  359         ///< [IN] Name of the app to stop.
  360 );
  361 
  362 #endif // LE_APPCTRL_INTERFACE_H_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:35
le_appCtrl_Start
le_result_t le_appCtrl_Start(const char *LE_NONNULL appName)
le_appCtrl_RemoveTraceAttachHandler
void le_appCtrl_RemoveTraceAttachHandler(le_appCtrl_TraceAttachHandlerRef_t handlerRef)
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_Import
le_result_t le_appCtrl_Import(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path)
le_appCtrl_Stop
le_result_t le_appCtrl_Stop(const char *LE_NONNULL appName)
le_appCtrl_TryConnectService
le_result_t le_appCtrl_TryConnectService(void)
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 *LE_NONNULL procName, bool run)
le_appCtrl_ReleaseRef
void le_appCtrl_ReleaseRef(le_appCtrl_AppRef_t appRef)
legato.h
le_appCtrl_ConnectService
void le_appCtrl_ConnectService(void)
le_appCtrl_TraceAttachHandlerFunc_t
void(* le_appCtrl_TraceAttachHandlerFunc_t)(le_appCtrl_AppRef_t appRef, int32_t pid, const char *LE_NONNULL procName, void *contextPtr)
Definition: le_appCtrl_interface.h:184
le_appCtrl_GetRef
le_appCtrl_AppRef_t le_appCtrl_GetRef(const char *LE_NONNULL appName)
le_appCtrl_SetServerDisconnectHandler
void le_appCtrl_SetServerDisconnectHandler(le_appCtrl_DisconnectHandler_t disconnectHandler, void *contextPtr)
le_appCtrl_SetDevicePerm
le_result_t le_appCtrl_SetDevicePerm(le_appCtrl_AppRef_t appRef, const char *LE_NONNULL path, const char *LE_NONNULL permissions)
le_appCtrl_TraceUnblock
void le_appCtrl_TraceUnblock(le_appCtrl_AppRef_t appRef, int32_t pid)