m2mb API docs  25.30.004.0
m2mb API sets documentation
m2mb_appMng.h
Go to the documentation of this file.
1 /* $version: 252203 */
2 /*===============================================================================================*/
3 /* >>> Copyright (C) Telit Communications S.p.A. Italy All Rights Reserved. <<< */
24 #ifndef M2MB_APPMNG_H
25 #define M2MB_APPMNG_H
26 /* Include ======================================================================================*/
27 
28 
29 /* Global declarations ==========================================================================*/
30 
31 #define M2MB_APPMNG_INVALID 0
32 
33 #define M2MB_APPMNG_AUTOSTART 1
34 #define M2MB_APPMNG_NOT_AUTOSTART 0
35 
36 /* max length for each argument */
37 #define M2MB_APPMNG_MAX_ARG_LEN 32
38 /* max numbers of args per app allowed */
39 #define M2MB_APPMNG_MAX_ARG_NUM 10
40 /* max delay start that can be set */
41 #define M2MB_APPMNG_MAX_DELAY 60
42 /* application file extension must be APP_FILE_EXTENSION */
43 #define APP_FILE_EXTENSION ".bin"
44 /* max and minimum filename lenght (extension included) for application file */
45 #define M2MB_APPMNG_MIN_FILEBIN_LEN 5
46 #define M2MB_APPMNG_MAX_FILEBIN_LEN 64
47 
48 #define M2MB_APPMNG_MOD_DIR "/mod/"
49 /* the main application manager directory */
50 
51 /* Global typedefs ==============================================================================*/
52 
53 /* error for App Manager */
54 typedef enum M2MB_APPMNG_RESULT
55 {
56  M2MB_APPMNG_RESULT_SUCCESS,
57  M2MB_APPMNG_RESULT_ERROR,
58  M2MB_APPMNG_RESULT_PTR_ERROR,
59  M2MB_APPMNG_RESULT_NO_MEMORY,
60  M2MB_APPMNG_RESULT_START_ERROR,
61  M2MB_APPMNG_RESULT_STOP_ERROR,
62  M2MB_APPMNG_RESULT_SET_ERROR,
63  M2MB_APPMNG_RESULT_GET_ERROR,
64  M2MB_APPMNG_RESULT_INVALID_STOP,
65  M2MB_APPMNG_RESULT_INVALID_START,
66  /* generic error to analyse */
67  M2MB_APPMNG_RESULT_GENERIC_ERROR,
68  /* provided args on API do not match expected values */
69  M2MB_APPMNG_RESULT_INVALID_ARG,
70  /* virtual address of application is not valid or already in use */
71  M2MB_APPMNG_RESULT_INVALID_ADDRESS,
72  /* not enough RAM memory available */
73  M2MB_APPMNG_RESULT_ERR_AVAILABLE_RAM,
74  /* app file not found in FS: maybe deleted after being inserted in execution list */
75  M2MB_APPMNG_RESULT_ERR_NO_ENTRY,
76  /* internal init error */
77  M2MB_APPMNG_RESULT_ERR_FILEINI,
78  /* no applications in execution list */
79  M2MB_APPMNG_RESULT_ERR_EMPTY_LIST,
80  /* application not in execution list as executable */
81  M2MB_APPMNG_RESULT_NOT_EXE,
82  /* integrity check on binary file fails */
83  M2MB_APPMNG_RESULT_ERR_CRC,
84  M2MB_APPMNG_RESULT_DIFF_CRC_PREAMBLE,
85  /* error during update parameter procedure */
86  M2MB_APPMNG_RESULT_UPDATE_ERROR,
87  /* wrong arg format */
88  M2MB_APPMNG_RESULT_ARG_FORMAT_ERROR,
89  /* arglen exceeded maximum value or 0 */
90  M2MB_APPMNG_RESULT_LEN_ARG_ERROR,
91  /* command not supported, e.g app stop for old version in place */
92  M2MB_APPMNG_RESULT_NOT_SUPPORTED,
93 
94  M2MB_APPMNG_RESULT_ERR_UNKNOWN = 255,
95  M2MB_APPMNG_RESULT_END,
96 
97  ENUM_TO_INT( M2MB_APPMNG_RESULT_E )
98 } M2MB_APPMNG_RESULT_E;
99 
100 typedef enum
101 {
102  /* lenght name of app */
103  M2MB_APPMNG_SEL_CMD_LNAME_APP,
104  /* app name */
105  M2MB_APPMNG_SEL_CMD_NAME,
106  /* not allowed set in user space: checks automatically also integrity: fail in case of integrity error
107  it is current virtual address if app is in running, otherwise it is the address the application will request to run
108  */
109  M2MB_APPMNG_SEL_CMD_ADDRESS,
110  /* only get: total RAM occupied by app in case of running; RAM that will be required to run in case of app not
111  running with about 8K boundary tolerance. Automatic check of integrity is performed: fail in case of integrity error
112  */
113  M2MB_APPMNG_SEL_CMD_RAM,
114  /* number of total args */
115  M2MB_APPMNG_SEL_CMD_TOT_ARGS,
116  /* N arg selected, in get or set, it starts from index 1, index 0 is reserved for name of app ( index 0 => arg[0] )
117  the max length of arg[0] is M2MB_APPMNG_MAX_FILEBIN_LEN */
118  M2MB_APPMNG_SEL_CMD_ARG_N,
119  /* Only for get len of specified arg N: arglen of arg N. Args must be passed as string terminating with NULL carachter'\0'.
120  MAX ARG LEN IS M2MB_APPMNG_MAX_ARG_LEN.
121  */
122  M2MB_APPMNG_SEL_CMD_ARGLEN_N,
123  /* current delay, volatile value, used to delay start or stop of the application */
124  M2MB_APPMNG_SEL_CMD_DELAY,
125  /* permanent saved value of delay in *ini file */
126  M2MB_APPMNG_SEL_CMD_DELAY_INI,
127  /* run flag in file *.ini : permanent */
128  M2MB_APPMNG_SEL_CMD_SET_EXE_AUTO_INI,
129  M2MB_APPMNG_SEL_CMD_STATE,
130  /* set or get more arguments separated by comma, at once as unique string */
131  M2MB_APPMNG_SEL_CMD_ARGS,
132  /* delete all arguments: only for set */
133  M2MB_APPMNG_SEL_CMD_ARGS_DELETE,
134 
135  /* ---- */
136  M2MB_APPMNG_SEL_CMD_END,
137  ENUM_TO_INT( M2MB_APPMNG_SEL_CMD_E )
138 } M2MB_APPMNG_SEL_CMD_E;
139 
140 typedef enum
141 {
142  /* application ready to start */
143  M2MB_APPMNG_STATE_READY,
144  /* application is in the starting process, but it's not yet in the run state( start with delay ) */
145  M2MB_APPMNG_STATE_STARTING,
146  /* application is in the run state */
147  M2MB_APPMNG_STATE_RUN,
148  /* application is in the stopping process, but it's not yet in the stop state( stop with delay ) */
149  M2MB_APPMNG_STATE_STOPPING,
150  /* application is in the stop state */
151  M2MB_APPMNG_STATE_STOP,
152 
153  ENUM_TO_INT( M2MB_APPMNG_STATE_E )
154 } M2MB_APPMNG_STATE_E;
155 
156 typedef struct M2MB_APPMNG_HANDLE_TAG *M2MB_APPMNG_HANDLE;
157 
158 /* Global functions =============================================================================*/
159 /*-----------------------------------------------------------------------------------------------*/
210 /*-----------------------------------------------------------------------------------------------*/
211 
212 M2MB_APPMNG_RESULT_E m2mb_appMng_add( M2MB_APPMNG_HANDLE *pAppMngHandle, CHAR* appName, UINT32 delayStart );
213 
214 /*-----------------------------------------------------------------------------------------------*/
251 /*-----------------------------------------------------------------------------------------------*/
252 
253 M2MB_APPMNG_RESULT_E m2mb_appMng_del( M2MB_APPMNG_HANDLE appMngHandle );
254 
255 /*-----------------------------------------------------------------------------------------------*/
301 /*-----------------------------------------------------------------------------------------------*/
302 
303 M2MB_APPMNG_RESULT_E m2mb_appMng_start( M2MB_APPMNG_HANDLE appMngHandle );
304 
305 /*-----------------------------------------------------------------------------------------------*/
306 
353 /*-----------------------------------------------------------------------------------------------*/
354 
355 M2MB_APPMNG_RESULT_E m2mb_appMng_stop( M2MB_APPMNG_HANDLE appMngHandle );
356 
357 /*-----------------------------------------------------------------------------------------------*/
358 
474 /*-----------------------------------------------------------------------------------------------*/
475 
476 M2MB_APPMNG_RESULT_E m2mb_appMng_setItem( M2MB_APPMNG_HANDLE appMngHandle,
477  M2MB_APPMNG_SEL_CMD_E selCmd,
478  void *pIn,
479  void *pOption
480  );
481 
482 /*-----------------------------------------------------------------------------------------------*/
483 
646 /*-----------------------------------------------------------------------------------------------*/
647 
648 M2MB_APPMNG_RESULT_E m2mb_appMng_getItem( M2MB_APPMNG_HANDLE appMngHandle,
649  M2MB_APPMNG_SEL_CMD_E selCmd,
650  MEM_W *pOut,
651  void *pIn
652  );
653 
654 /*-----------------------------------------------------------------------------------------------*/
655 
682 /*-----------------------------------------------------------------------------------------------*/
683 
684 UINT8 m2mb_appMng_appsNumber( void );
685 
686 /*-----------------------------------------------------------------------------------------------*/
687 
720 /*-----------------------------------------------------------------------------------------------*/
721 
722 M2MB_APPMNG_HANDLE m2mb_appMng_getHandleByN( UINT8 n );
723 
724 /*-----------------------------------------------------------------------------------------------*/
725 
756 /*-----------------------------------------------------------------------------------------------*/
757 
758 M2MB_APPMNG_HANDLE m2mb_appMng_getHandleByName( char *name );
759 
760 /*-----------------------------------------------------------------------------------------------*/
761 
792 /*-----------------------------------------------------------------------------------------------*/
793 
794 M2MB_APPMNG_HANDLE m2mb_appMng_getMyHandle( void );
795 
796 /*-----------------------------------------------------------------------------------------------*/
838 /*-----------------------------------------------------------------------------------------------*/
839 M2MB_APPMNG_RESULT_E m2mb_appMng_checkIntegrity( CHAR* appName, MEM_W *pAddress, UINT32 *pTotRam );
840 
841 /* Global define ================================================================================*/
842 
843 #endif /* M2MB_APPMNG_H */
m2mb_appMng_stop
M2MB_APPMNG_RESULT_E m2mb_appMng_stop(M2MB_APPMNG_HANDLE appMngHandle)
m2mb_appMng_stop
m2mb_appMng_getHandleByName
M2MB_APPMNG_HANDLE m2mb_appMng_getHandleByName(char *name)
m2mb_appMng_getHandleByName
m2mb_appMng_getHandleByN
M2MB_APPMNG_HANDLE m2mb_appMng_getHandleByN(UINT8 n)
m2mb_appMng_getHandleByN
m2mb_appMng_getItem
M2MB_APPMNG_RESULT_E m2mb_appMng_getItem(M2MB_APPMNG_HANDLE appMngHandle, M2MB_APPMNG_SEL_CMD_E selCmd, MEM_W *pOut, void *pIn)
m2mb_appMng_getItem
m2mb_appMng_del
M2MB_APPMNG_RESULT_E m2mb_appMng_del(M2MB_APPMNG_HANDLE appMngHandle)
m2mb_appMng_del
m2mb_appMng_getMyHandle
M2MB_APPMNG_HANDLE m2mb_appMng_getMyHandle(void)
m2mb_appMng_getMyHandle
m2mb_appMng_checkIntegrity
M2MB_APPMNG_RESULT_E m2mb_appMng_checkIntegrity(CHAR *appName, MEM_W *pAddress, UINT32 *pTotRam)
Function to verify integrity of an application file.
m2mb_appMng_appsNumber
UINT8 m2mb_appMng_appsNumber(void)
m2mb_appMng_appsNumber
m2mb_appMng_start
M2MB_APPMNG_RESULT_E m2mb_appMng_start(M2MB_APPMNG_HANDLE appMngHandle)
m2mb_appMng_start
m2mb_appMng_add
M2MB_APPMNG_RESULT_E m2mb_appMng_add(M2MB_APPMNG_HANDLE *pAppMngHandle, CHAR *appName, UINT32 delayStart)
m2mb_appMng_add
m2mb_appMng_setItem
M2MB_APPMNG_RESULT_E m2mb_appMng_setItem(M2MB_APPMNG_HANDLE appMngHandle, M2MB_APPMNG_SEL_CMD_E selCmd, void *pIn, void *pOption)
m2mb_appMng_setItem