lookip: Disconnect asynchronously to avoid dead-locking watcher unregistration
[strongswan.git] / src / libstrongswan / networking / streams / stream.h
1 /*
2 * Copyright (C) 2013 Martin Willi
3 * Copyright (C) 2013 revosec AG
4 *
5 * This program is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License as published by the
7 * Free Software Foundation; either version 2 of the License, or (at your
8 * option) any later version. See <http://www.fsf.org/copyleft/gpl.txt>.
9 *
10 * This program is distributed in the hope that it will be useful, but
11 * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
12 * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
13 * for more details.
14 */
15
16 /**
17 * @defgroup stream stream
18 * @{ @ingroup streams
19 */
20
21 #ifndef STREAM_H_
22 #define STREAM_H_
23
24 typedef struct stream_t stream_t;
25
26 #include <library.h>
27
28 #include <sys/un.h>
29 #include <sys/socket.h>
30
31 /**
32 * Constructor function prototype for stream_t.
33 *
34 * @param uri URI to create a stream for
35 * @return stream instance, NULL on error
36 */
37 typedef stream_t*(*stream_constructor_t)(char *uri);
38
39 /**
40 * Callback function prototype, called when stream is ready.
41 *
42 * It is not allowed to destroy the stream nor to call on_read()/on_write/()
43 * during the callback.
44 *
45 * As select() may return even if a read()/write() would actually block, it is
46 * recommended to use the non-blocking calls and handle return values
47 * appropriately.
48 *
49 * @param data data passed during callback registration
50 * @param stream associated stream
51 * @return FALSE unregisters the invoked callback, TRUE keeps it
52 */
53 typedef bool (*stream_cb_t)(void *data, stream_t *stream);
54
55 /**
56 * Abstraction of a Berkley socket using stream semantics.
57 */
58 struct stream_t {
59
60 /**
61 * Read data from the stream.
62 *
63 * If "block" is FALSE and no data is available, the function returns -1
64 * and sets errno to EWOULDBLOCK.
65 *
66 * @param buf data buffer to read into
67 * @param len number of bytes to read
68 * @param block TRUE to use a blocking read
69 * @return number of bytes read, -1 on error
70 */
71 ssize_t (*read)(stream_t *this, void *buf, size_t len, bool block);
72
73 /**
74 * Read data from the stream, avoiding short reads.
75 *
76 * This call is always blocking, and reads until len has been read
77 * completely. If the connection is closed before enough bytes could be
78 * returned, errno is set to ECONNRESET.
79 *
80 * @param buf data buffer to read into
81 * @param len number of bytes to read
82 * @return TRUE if len bytes read, FALSE on error
83 */
84 bool (*read_all)(stream_t *this, void *buf, size_t len);
85
86 /**
87 * Register a callback to invoke when stream has data to read.
88 *
89 * @param cb callback function, NULL to unregister
90 * @param data data to pass to callback
91 */
92 void (*on_read)(stream_t *this, stream_cb_t cb, void *data);
93
94 /**
95 * Write data to the stream.
96 *
97 * If "block" is FALSE and the write would block, the function returns -1
98 * and sets errno to EWOULDBLOCK.
99 *
100 * @param buf data buffer to write
101 * @param len number of bytes to write
102 * @param block TRUE to use a blocking write
103 * @return number of bytes written, -1 on error
104 */
105 ssize_t (*write)(stream_t *this, void *buf, size_t len, bool block);
106
107 /**
108 * Write data to the stream, avoiding short writes.
109 *
110 * This call is always blocking, and writes until len bytes has been
111 * written.
112 *
113 * @param buf data buffer to write
114 * @param len number of bytes to write
115 * @return TRUE if len bytes written, FALSE on error
116 */
117 bool (*write_all)(stream_t *this, void *buf, size_t len);
118
119 /**
120 * Register a callback to invoke when a write would not block.
121 *
122 * @param cb callback function, NULL to unregister
123 * @param data data to pass to callback
124 */
125 void (*on_write)(stream_t *this, stream_cb_t cb, void *data);
126
127 /**
128 * Get a FILE reference for this stream.
129 *
130 * @return FILE*, must be fclose()d, NULL on error
131 */
132 FILE* (*get_file)(stream_t *this);
133
134 /**
135 * Destroy a stream_t.
136 */
137 void (*destroy)(stream_t *this);
138 };
139
140 /**
141 * Create a stream for UNIX sockets.
142 *
143 * UNIX URIs start with unix://, followed by the socket path. For absolute
144 * paths, an URI looks something like:
145 *
146 * unix:///path/to/socket
147 *
148 * @param uri UNIX socket specific URI, must start with "unix://"
149 * @return stream instance, NULL on failure
150 */
151 stream_t *stream_create_unix(char *uri);
152
153 /**
154 * Helper function to parse a unix:// URI to a sockaddr
155 *
156 * @param uri URI
157 * @param addr sockaddr
158 * @return length of sockaddr, -1 on error
159 */
160 int stream_parse_uri_unix(char *uri, struct sockaddr_un *addr);
161
162 /**
163 * Create a stream for TCP sockets.
164 *
165 * TCP URIs start with tcp://, followed by a hostname (FQDN or IP), followed
166 * by a colon separated port. A full TCP uri looks something like:
167 *
168 * tcp://srv.example.com:5555
169 * tcp://0.0.0.0:1234
170 * tcp://[fec2::1]:7654
171 *
172 * There is no default port, so a colon after tcp:// is mandatory.
173 *
174 * @param uri TCP socket specific URI, must start with "tcp://"
175 * @return stream instance, NULL on failure
176 */
177 stream_t *stream_create_tcp(char *uri);
178
179 /**
180 * Helper function to parse a tcp:// URI to a sockaddr
181 *
182 * @param uri URI
183 * @param addr sockaddr, large enough for URI
184 * @return length of sockaddr, -1 on error
185 */
186 int stream_parse_uri_tcp(char *uri, struct sockaddr *addr);
187
188 /**
189 * Create a stream from a file descriptor.
190 *
191 * The file descriptor MUST be a socket for non-blocking operation.
192 *
193 * @param fd file descriptor to wrap into a stream_t
194 * @return stream instance
195 */
196 stream_t *stream_create_from_fd(int fd);
197
198 #endif /** STREAM_H_ @}*/