1/*
2    This file is part of libmicrospdy
3    Copyright Copyright (C) 2013 Andrey Uzunov
4
5    This program is free software: you can redistribute it and/or modify
6    it under the terms of the GNU General Public License as published by
7    the Free Software Foundation, either version 3 of the License, or
8    (at your option) any later version.
9
10    This program is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13    GNU General Public License for more details.
14
15    You should have received a copy of the GNU General Public License
16    along with this program.  If not, see <http://www.gnu.org/licenses/>.
17*/
18
19/**
20 * @file io.h
21 * @brief  Signatures for IO functions.
22 * @author Andrey Uzunov
23 */
24
25#ifndef IO_H
26#define IO_H
27
28#include "platform.h"
29#include "io_openssl.h"
30#include "io_raw.h"
31
32
33/**
34 * Used for return code when reading and writing to the TLS socket.
35 */
36enum SPDY_IO_ERROR
37{
38	/**
39	 * The connection was closed by the other party.
40	 */
41	SPDY_IO_ERROR_CLOSED = 0,
42
43	/**
44	 * Any kind of error ocurred. The session has to be closed.
45	 */
46	SPDY_IO_ERROR_ERROR = -2,
47
48	/**
49	 * The function had to return without processing any data. The whole
50	 * cycle of events has to be called again (SPDY_run) as something
51	 * either has to be written or read or the the syscall was
52	 * interrupted by a signal.
53	 */
54	SPDY_IO_ERROR_AGAIN = -3,
55};
56
57
58/**
59 * Global initializing. Must be called only once in the program.
60 *
61 */
62typedef void
63(*SPDYF_IOGlobalInit) ();
64
65
66/**
67 * Global deinitializing for the whole program. Should be called
68 * at the end of the program.
69 *
70 */
71typedef void
72(*SPDYF_IOGlobalDeinit) ();
73
74
75/**
76 * Initializing of io context for a specific daemon.
77 * Must be called when the daemon starts.
78 *
79 * @param daemon SPDY_Daemon for which io will be used. Daemon's
80 * 				certificate and key file are used for tls.
81 * @return SPDY_YES on success or SPDY_NO on error
82 */
83typedef int
84(*SPDYF_IOInit) (struct SPDY_Daemon *daemon);
85
86
87/**
88 * Deinitializing io context for a daemon. Should be called
89 * when the deamon is stopped.
90 *
91 * @param daemon SPDY_Daemon which is being stopped
92 */
93typedef void
94(*SPDYF_IODeinit) (struct SPDY_Daemon *daemon);
95
96
97/**
98 * Initializing io for a specific connection. Must be called
99 * after the connection has been accepted.
100 *
101 * @param session SPDY_Session whose socket will be used
102 * @return SPDY_NO if some funcs inside fail. SPDY_YES otherwise
103 */
104typedef int
105(*SPDYF_IONewSession) (struct SPDY_Session *session);
106
107
108/**
109 * Deinitializing io for a specific connection. Should be called
110 * closing session's socket.
111 *
112 * @param session SPDY_Session whose socket is used
113 */
114typedef void
115(*SPDYF_IOCloseSession) (struct SPDY_Session *session);
116
117
118/**
119 * Reading from session's socket. Reads available data and put it to the
120 * buffer.
121 *
122 * @param session for which data is received
123 * @param buffer where data from the socket will be written to
124 * @param size of the buffer
125 * @return number of bytes (at most size) read from the connection
126 *         0 if the other party has closed the connection
127 *         SPDY_IO_ERROR code on error
128 */
129typedef int
130(*SPDYF_IORecv) (struct SPDY_Session *session,
131				void * buffer,
132				size_t size);
133
134
135/**
136 * Writing to session's socket. Writes the data given into the buffer to the
137 *  socket.
138 *
139 * @param session whose context is used
140 * @param buffer from where data will be written to the socket
141 * @param size number of bytes to be taken from the buffer
142 * @return number of bytes (at most size) from the buffer that has been
143 * 			written to the connection
144 *         0 if the other party has closed the connection
145 *         SPDY_IO_ERROR code on error
146 */
147typedef int
148(*SPDYF_IOSend) (struct SPDY_Session *session,
149				const void * buffer,
150				size_t size);
151
152
153/**
154 * Checks if there is data staying in the buffers of the underlying
155 * system that waits to be read. In case of TLS, this will call
156 * something like SSL_pending().
157 *
158 * @param session which is checked
159 * @return SPDY_YES if data is pending or SPDY_NO otherwise
160 */
161typedef int
162(*SPDYF_IOIsPending) (struct SPDY_Session *session);
163
164
165/**
166 * Called just before frames are about to be processed and written
167 * to the socket.
168 *
169 * @param session
170 * @return SPDY_NO if writing must not happen in the call;
171 *         SPDY_YES otherwise
172 */
173typedef int
174(*SPDYF_IOBeforeWrite) (struct SPDY_Session *session);
175
176
177/**
178 * Called just after frames have been processed and written
179 * to the socket.
180 *
181 * @param session
182 * @param was_written has the same value as the write function for the
183 *        session will return
184 * @return returned value will be used by the write function to return
185 */
186typedef int
187(*SPDYF_IOAfterWrite) (struct SPDY_Session *session,
188                       int was_written);
189
190
191/**
192 * Sets callbacks for the daemon with regard to the IO subsystem.
193 *
194 * @param daemon
195 * @param io_subsystem the IO subsystem that will
196 *        be initialized and used by daemon.
197 * @return SPDY_YES on success or SPDY_NO otherwise
198 */
199int
200SPDYF_io_set_daemon(struct SPDY_Daemon *daemon,
201                    enum SPDY_IO_SUBSYSTEM io_subsystem);
202
203
204/**
205 * Sets callbacks for the session with regard to the IO subsystem.
206 *
207 * @param session
208 * @param io_subsystem the IO subsystem that will
209 *        be initialized and used by session.
210 * @return SPDY_YES on success or SPDY_NO otherwise
211 */
212int
213SPDYF_io_set_session(struct SPDY_Session *session,
214                     enum SPDY_IO_SUBSYSTEM io_subsystem);
215
216#endif
217