shell.h 14 KB

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