shell.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342
  1. /*
  2. * shell.h
  3. */
  4. /**
  5. \ingroup clish
  6. \defgroup clish_shell shell
  7. @{
  8. \brief This class represents the top level container for a CLI session.
  9. */
  10. #ifndef _clish_shell_h
  11. #define _clish_shell_h
  12. #include <stdio.h>
  13. #include <pthread.h>
  14. #include "lub/c_decl.h"
  15. #include "lub/types.h"
  16. #include "lub/argv.h"
  17. #include "tinyrl/tinyrl.h"
  18. #include "view.h"
  19. #include "konf/net.h"
  20. _BEGIN_C_DECL typedef struct clish_shell_s clish_shell_t;
  21. /*=====================================
  22. * SHELL INTERFACE
  23. *===================================== */
  24. /**
  25. * A hook function used during the spawning of a new shell.
  26. *
  27. * This will be invoked from the context of the spawned shell's thread
  28. * and will be invoked just after the shell instance is created.
  29. *
  30. * This enables the client-specific initialisation of the spawned shell's
  31. * thread
  32. * e.g. to map the I/O streams, authenticate a user.
  33. *
  34. * N.B. It is possible for a client to have this invoked multiple times
  35. * if the user is spawning new shells using a commmand which uses the
  36. * "clish_spawn" builtin function. Hence the client should remember the
  37. * shell which first calls this function, and only assign resource (e.g.
  38. * setting up a script interpreter) for that call.
  39. *
  40. * \return
  41. * - BOOL_TRUE if everything is OK
  42. * - BOOL_FALSE if the shell should be immediately shut down.
  43. *
  44. */
  45. typedef bool_t clish_shell_init_fn_t(
  46. /**
  47. * The shell instance which invoked this call
  48. */
  49. const clish_shell_t * shell);
  50. /**
  51. * A hook function used during the shutting down of a spawned shell
  52. *
  53. * This will be invoked from the context of the spawned shell's thread
  54. * and will be invoked just before the shell is destroyed.
  55. *
  56. * This enables the client-specific finalisation to occur.
  57. * e.g. releasing any resource held by the cookie,
  58. * shutting down telnet connections
  59. *
  60. * NB. This function may be called multiple times if a user is spawning
  61. * new commands (via the "clish_spawn" builtin command), hence should use
  62. * the reference to the root shell (remembered by the first call to clish_shell_init_fn_t callback)
  63. * to signal when the cleanup should occur.
  64. */
  65. typedef void clish_shell_fini_fn_t(
  66. /**
  67. * The shell instance which invoked this call
  68. */
  69. const clish_shell_t * shell);
  70. /**
  71. * A hook function used to indicate a command line has been executed and the
  72. * shell is about to prompt for the next command.
  73. *
  74. * This will be invoked from the context of the spawned shell's thread
  75. * and will be called once an ACTION has been performed.
  76. *
  77. * A client may use this as a periodic indicator of CLI activity,
  78. * e.g. to manage session timeouts. In addition any required logging of
  79. * commands may be performed.
  80. */
  81. typedef void clish_shell_cmd_line_fn_t(
  82. /**
  83. * The shell instance which invoked this call
  84. */
  85. const clish_shell_t * instance,
  86. /**
  87. * The text of the command line entered
  88. */
  89. const char *cmd_line);
  90. /**
  91. * A hook function used to invoke the script associated with a command
  92. *
  93. * This will be invoked from the context of the spawned shell's thread
  94. * and will be invoked with the ACTION script which is to be performed.
  95. *
  96. * The clish component will only pass down a call when a command has been
  97. * correctly input.
  98. *
  99. * The client may choose to implement invocation of the script in a number of
  100. * ways, which may include forking a sub-process or thread. It is important
  101. * that the call doesn't return until the script has been fully evaluated.
  102. *
  103. * \return
  104. * - BOOL_TRUE - if the script is executed without issue
  105. * - BOOL_FALSE - if the script had an issue with execution.
  106. *
  107. * \post
  108. * - If the script executes successfully then any "view" tag associated with the
  109. * command will be honored. i.e. the CLI will switch to the new view
  110. */
  111. typedef bool_t clish_shell_script_fn_t(
  112. /**
  113. * The shell instance which invoked this call
  114. */
  115. const clish_shell_t * instance,
  116. /**
  117. * The script to be evaluated
  118. */
  119. const char *script);
  120. /**
  121. * A hook function used to control config file write
  122. *
  123. */
  124. typedef bool_t clish_shell_config_fn_t(
  125. /**
  126. * The shell instance which invoked this call
  127. */
  128. const clish_shell_t * instance,
  129. /**
  130. * The command
  131. */
  132. const clish_command_t * cmd,
  133. /**
  134. * Argument vector
  135. */
  136. clish_pargv_t * pargv);
  137. /**
  138. * A hook function used to control access for the current user.
  139. *
  140. * This will be invoked from the context of the spawned shell's thread
  141. * and will be called during the parsing of the XML files.
  142. *
  143. * The clish component will only insert a command into a view if the access
  144. * call is sucessfull.
  145. *
  146. * The client may choose to implement invocation of the script in a number of
  147. * ways, which may include forking a sub-process or thread. It is important
  148. * that the call doesn't return until the script has been fully evaluated.
  149. *
  150. * \return
  151. * - BOOL_TRUE - if the user of the current CLISH session is permitted access
  152. * - BOOL_FALSE - if the user of the current CLISH session is not permitted access
  153. *
  154. * \post
  155. * - If access is granted then the associated command will be inserted into the
  156. * appropriate view.
  157. */
  158. typedef bool_t clish_shell_access_fn_t(
  159. /**
  160. * The shell instance which invoked this call
  161. */
  162. const clish_shell_t * instance,
  163. /**
  164. * A textual string which describes a limitation for a command. This
  165. * string typically may be the name of a user group, of which the
  166. * current user must be a member to grant access to a command.
  167. */
  168. const char *access);
  169. /**
  170. * A hook function used as a built in command callback
  171. *
  172. * This will be invoked from the context of the spawned shell's thread
  173. * and will be called during the execution of a builting command.
  174. *
  175. * A client may register any number of these callbacks in its
  176. * clish_shell_builtin_cmds_t structure.
  177. *
  178. * \return
  179. * - BOOL_TRUE - if the command completes correctly
  180. * - BOOL_FALSE - if the command fails.
  181. *
  182. */
  183. typedef bool_t clish_shell_builtin_fn_t(
  184. /**
  185. * The shell instance which invoked this call
  186. */
  187. const clish_shell_t * instance,
  188. /**
  189. * A vector of textual command line arguments.
  190. */
  191. const lub_argv_t * argv);
  192. /**
  193. * A client of libclish may provide some builtin commands which will be
  194. * interpreted by the framework, instead of the client's script engine.
  195. */
  196. typedef struct {
  197. const char *name; /**< The textual name to be used in
  198. * the 'builtin' XML attribute"
  199. */
  200. clish_shell_builtin_fn_t *callback;
  201. /**< The function to be invoked */
  202. } clish_shell_builtin_t;
  203. /**
  204. * A client of libclish will provide hooks for the control of the CLI within
  205. * a particular system.
  206. * They will populate an instance of this structure and pass it into the
  207. */
  208. typedef struct {
  209. clish_shell_init_fn_t *init_fn; /**< Initialisation call */
  210. clish_shell_access_fn_t *access_fn; /**< Access control call */
  211. clish_shell_cmd_line_fn_t *cmd_line_fn;/**< Command line logging call */
  212. clish_shell_script_fn_t *script_fn; /**< script evaluation call */
  213. clish_shell_fini_fn_t *fini_fn; /**< Finalisation call */
  214. clish_shell_config_fn_t *config_fn; /**< Config call */
  215. const clish_shell_builtin_t *cmd_list;/**< NULL terminated list */
  216. } clish_shell_hooks_t;
  217. /*-----------------
  218. * meta functions
  219. *----------------- */
  220. int clish_shell_spawn_and_wait(const clish_shell_hooks_t * hooks, void *cookie);
  221. /**
  222. * This operation causes a separate (POSIX) thread of execution to
  223. * be spawned. This thread becomes responsible for the CLI session.
  224. *
  225. * This will be invoked from the context of the spawned shell's thread
  226. * and will be called during the execution of a builting command.
  227. *
  228. * A client may register any number of these callbacks in its
  229. * clish_shell_builtin_cmds_t structure.
  230. *
  231. * \return
  232. * - BOOL_TRUE - if the thread was successfully spawned
  233. * - BOOL_FALSE - if the thread failed to be spawned
  234. *
  235. */
  236. bool_t clish_shell_spawn(
  237. /**
  238. * A POSIX thread reference to fill out. This can be used
  239. * to later control the spawned thread if necessary.
  240. */
  241. pthread_t * pthread,
  242. /**
  243. * A POSIX thread attribute reference which will be used
  244. * to define the thread which will be lanched. A value of
  245. * NULL will use the system default.
  246. */
  247. const pthread_attr_t * attr,
  248. /**
  249. * A reference to the clients hooks. These are used to
  250. * communicate back the client when client-specific actions
  251. * are required.
  252. */
  253. const clish_shell_hooks_t * hooks,
  254. /**
  255. * A client specific reference which can be obtained during
  256. * a callback by invoking clish_shell__get_client_cookie()
  257. */
  258. void *cookie);
  259. bool_t
  260. clish_shell_spawn_from_file(const clish_shell_hooks_t * hooks,
  261. void *cookie, const char *filename);
  262. clish_shell_t *clish_shell_new(const clish_shell_hooks_t * hooks,
  263. void *cookie, FILE * istream, FILE * ostream);
  264. /*-----------------
  265. * methods
  266. *----------------- */
  267. /*
  268. * Called to invoke the startup command for this shell
  269. */
  270. bool_t clish_shell_startup(clish_shell_t * instance);
  271. void clish_shell_delete(clish_shell_t * instance);
  272. clish_view_t *clish_shell_find_create_view(clish_shell_t * instance,
  273. const char *name,
  274. const char *prompt);
  275. clish_ptype_t *clish_shell_find_create_ptype(clish_shell_t * instance,
  276. const char *name,
  277. const char *text,
  278. const char *pattern,
  279. clish_ptype_method_e method,
  280. clish_ptype_preprocess_e
  281. preprocess);
  282. int clish_shell_xml_read(clish_shell_t * instance, const char *filename);
  283. void clish_shell_help(clish_shell_t * instance, const char *line);
  284. bool_t
  285. clish_shell_execute(clish_shell_t * instance,
  286. const clish_command_t * cmd, clish_pargv_t ** pargv);
  287. bool_t
  288. clish_shell_readline(clish_shell_t * shell,
  289. const char *prompt,
  290. const clish_command_t ** cmd, clish_pargv_t ** pargv);
  291. void clish_shell_set_context(clish_shell_t * instance, const char *viewname);
  292. void clish_shell_dump(clish_shell_t * instance);
  293. void clish_shell_close(clish_shell_t * instance);
  294. /*-----------------
  295. * attributes
  296. *----------------- */
  297. const clish_view_t *clish_shell__get_view(const clish_shell_t * instance);
  298. const char *clish_shell__get_viewid(const clish_shell_t * instance);
  299. const char *clish_shell__get_overview(const clish_shell_t * instance);
  300. tinyrl_t *clish_shell__get_tinyrl(const clish_shell_t * instance);
  301. void *clish_shell__get_client_cookie(const clish_shell_t * instance);
  302. void
  303. clish_shell__set_pwd(clish_shell_t * instance, unsigned index,
  304. const char * line, clish_view_t * view, char * viewid);
  305. char *clish_shell__get_pwd_line(const clish_shell_t * instance,
  306. unsigned index);
  307. clish_view_t *clish_shell__get_pwd_view(const clish_shell_t * instance,
  308. unsigned index);
  309. char *clish_shell__get_pwd_viewid(const clish_shell_t * instance,
  310. unsigned index);
  311. char *clish_shell__get_line(const clish_command_t * cmd, clish_pargv_t * pargv);
  312. konf_client_t *clish_shell__get_client(const clish_shell_t * instance);
  313. FILE *clish_shell__get_istream(const clish_shell_t * instance);
  314. FILE *clish_shell__get_ostream(const clish_shell_t * instance);
  315. /* Context */
  316. typedef struct clish_context_s clish_context_t;
  317. int clish_shell_wait(clish_context_t * instance);
  318. clish_context_t *clish_shell_spawn_stream(const pthread_attr_t * attr,
  319. const clish_shell_hooks_t * hooks, void *cookie,
  320. FILE * istream, FILE * ostream);
  321. _END_C_DECL
  322. #endif /* _clish_shell_h */
  323. /** @} clish_shell */