shell.h 14 KB

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