Rename "subsystems" directory to "base"
[oonf.git] / include / oonf / base / oonf_telnet.h
1
2 /*
3  * The olsr.org Optimized Link-State Routing daemon version 2 (olsrd2)
4  * Copyright (c) 2004-2015, the olsr.org team - see HISTORY file
5  * All rights reserved.
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * * Redistributions of source code must retain the above copyright
12  *   notice, this list of conditions and the following disclaimer.
13  * * Redistributions in binary form must reproduce the above copyright
14  *   notice, this list of conditions and the following disclaimer in
15  *   the documentation and/or other materials provided with the
16  *   distribution.
17  * * Neither the name of olsr.org, olsrd nor the names of its
18  *   contributors may be used to endorse or promote products derived
19  *   from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
25  * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
27  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
29  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
31  * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
32  * POSSIBILITY OF SUCH DAMAGE.
33  *
34  * Visit http://www.olsr.org for more information.
35  *
36  * If you find this software useful feel free to make a donation
37  * to the project. For more information see the website or contact
38  * the copyright holders.
39  *
40  */
41
42 /**
43  * @file
44  */
45
46 #ifndef OONF_TELNET_H_
47 #define OONF_TELNET_H_
48
49 #include <oonf/libcommon/avl.h>
50 #include <oonf/oonf.h>
51 #include <oonf/libcommon/list.h>
52 #include <oonf/libcommon/netaddr.h>
53 #include <oonf/libcommon/netaddr_acl.h>
54 #include <oonf/base/oonf_stream_socket.h>
55
56 /*! subsystem identifier */
57 #define OONF_TELNET_SUBSYSTEM "telnet"
58
59 /**
60  * telnet session status
61  */
62 enum oonf_telnet_result
63 {
64   /*! active and waiting for the next command */
65   TELNET_RESULT_ACTIVE,
66
67   /*! will output continuous data until stopped */
68   TELNET_RESULT_CONTINOUS,
69
70   /*! an error happened with the telnet command */
71   TELNET_RESULT_INTERNAL_ERROR,
72
73   /*! telnet session should end */
74   TELNET_RESULT_QUIT,
75
76   /**
77    * this one is used internally for the telnet API,
78    * it should not be returned by a command handler
79    */
80   _TELNET_RESULT_UNKNOWN_COMMAND,
81 };
82
83 /**
84  * represents a cleanup handler that must be called when the
85  * telnet core is shut down.
86  */
87 struct oonf_telnet_cleanup {
88   /*! pointer to telnet data */
89   struct oonf_telnet_data *data;
90
91   /**
92    * Callback that a telnet session is to be cleaned up
93    * @param cleanup registered cleanup handler
94    */
95   void (*cleanup_handler)(struct oonf_telnet_cleanup *cleanup);
96
97   /*! custom data pointer for cleanup handler */
98   void *custom;
99
100   /*! node for list of cleanup handlers */
101   struct list_entity node;
102 };
103
104 /**
105  * represents the data part of a telnet connection to a client
106  */
107 struct oonf_telnet_data {
108   /*! address of remote communication partner */
109   struct netaddr *remote;
110
111   /*! output buffer for telnet commands */
112   struct autobuf *out;
113
114   /*! current telnet command */
115   const char *command;
116
117   /*! current telnet parameters */
118   const char *parameter;
119
120   /*! true if echo mode is active */
121   bool show_echo;
122
123   /*! millisecond timeout between commands */
124   uint32_t timeout_value;
125
126   /**
127    * Callback triggered to stop continuous data output
128    * @param data this telnet data object
129    */
130   void (*stop_handler)(struct oonf_telnet_data *data);
131
132   /*! custom data for stop handler */
133   void *stop_data[4];
134
135   /*! custom timer for stop handler */
136   struct oonf_timer_instance stop_timer;
137
138   /*! list of cleanup handlers */
139   struct list_entity cleanup_list;
140 };
141
142 /**
143  * represents a full telnet session including socket
144  */
145 struct oonf_telnet_session {
146   /*! telnet TCP stream session */
147   struct oonf_stream_session session;
148
149   /*! telnet data */
150   struct oonf_telnet_data data;
151 };
152
153 #if !defined(REMOVE_HELPTEXT)
154 /**
155  * define an array entry for a telnet command
156  * @param cmd command name
157  * @param cb callback for command
158  * @param helptext help text for command
159  * @param args additional arguments
160  */
161 #define TELNET_CMD(cmd, cb, helptext, args...)                                                                         \
162   { .command = (cmd), .handler = (cb), .help = helptext, ##args }
163 #else
164 #define TELNET_CMD(cmd, cb, helptext, args...)                                                                         \
165   { .command = (cmd), .handler = (cb), .help = "", ##args }
166 #endif
167
168 /**
169  * represents a telnet command
170  */
171 struct oonf_telnet_command {
172   /*! name of telnet command */
173   const char *command;
174
175   /*! help text for telnet command, NULL if it uses a custom help handler */
176   const char *help;
177
178   /*! access control list for telnet command, NULL if not used */
179   struct netaddr_acl *acl;
180
181   /**
182    * callback triggered when telnet command is called
183    * @param con telnet data
184    * @return telnet result
185    */
186   enum oonf_telnet_result (*handler)(struct oonf_telnet_data *con);
187
188   /**
189    * callback triggered when help command for telnet command is called
190    * @param con telnet data
191    * @return telnet result
192    */
193   enum oonf_telnet_result (*help_handler)(struct oonf_telnet_data *con);
194
195   /*! node for tree of telnet commands */
196   struct avl_node _node;
197 };
198
199 EXPORT int oonf_telnet_add(struct oonf_telnet_command *command);
200 EXPORT void oonf_telnet_remove(struct oonf_telnet_command *command);
201
202 EXPORT void oonf_telnet_stop(struct oonf_telnet_data *data, bool print_prompt);
203
204 EXPORT enum oonf_telnet_result oonf_telnet_execute(
205   const char *cmd, const char *para, struct autobuf *out, struct netaddr *remote);
206
207 /**
208  * Add a cleanup handler to a telnet session
209  * @param data pointer to telnet data
210  * @param cleanup pointer to initialized cleanup handler
211  */
212 static INLINE void
213 oonf_telnet_add_cleanup(struct oonf_telnet_data *data, struct oonf_telnet_cleanup *cleanup) {
214   cleanup->data = data;
215   list_add_tail(&data->cleanup_list, &cleanup->node);
216 }
217
218 /**
219  * Removes a cleanup handler to a telnet session
220  * @param cleanup pointer to cleanup handler
221  */
222 static INLINE void
223 oonf_telnet_remove_cleanup(struct oonf_telnet_cleanup *cleanup) {
224   list_remove(&cleanup->node);
225 }
226
227 /**
228  * Flushs the output stream of a telnet session. This will be only
229  * necessary for continous output.
230  * @param data pointer to telnet data
231  */
232 static INLINE void
233 oonf_telnet_flush_session(struct oonf_telnet_data *data) {
234   struct oonf_telnet_session *session;
235
236   session = container_of(data, struct oonf_telnet_session, data);
237   if (session->session.state != STREAM_SESSION_INACTIVE && session->session.state != STREAM_SESSION_CLEANUP) {
238     oonf_stream_flush(&session->session);
239   }
240 }
241
242 #endif /* OONF_TELNET_H_ */