stream: support async operation using watcher
[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 /**
29 * Constructor function prototype for stream_t.
30 *
31 * @param uri URI to create a stream for
32 * @return stream instance, NULL on error
33 */
34 typedef stream_t*(*stream_constructor_t)(char *uri);
35
36 /**
37 * Callback function prototype, called when stream is ready.
38 *
39 * It is not allowed to destroy the stream during the callback, this would
40 * deadlock. Instead, return FALSE to destroy the stream. It is not allowed
41 * to call on_read()/on_write() during this callback.
42 *
43 * As select() may return even if a read()/write() would actually block, it is
44 * recommended to use the non-blocking calls and handle return values
45 * appropriately.
46 *
47 * @param data data passed during callback registration
48 * @param stream associated stream
49 * @return FALSE to destroy the stream
50 */
51 typedef bool (*stream_cb_t)(void *data, stream_t *stream);
52
53 /**
54 * Abstraction of a Berkley socket using stream semantics.
55 */
56 struct stream_t {
57
58 /**
59 * Read data from the stream.
60 *
61 * If "block" is FALSE and no data is available, the function returns -1
62 * and sets errno to EWOULDBLOCK.
63 *
64 * @param buf data buffer to read into
65 * @param len number of bytes to read
66 * @param block TRUE to use a blocking read
67 * @return number of bytes read, -1 on error
68 */
69 ssize_t (*read)(stream_t *this, void *buf, size_t len, bool block);
70
71 /**
72 * Register a callback to invoke when stream has data to read.
73 *
74 * @param cb callback function, NULL to unregister
75 * @param data data to pass to callback
76 */
77 void (*on_read)(stream_t *this, stream_cb_t cb, void *data);
78
79 /**
80 * Write data to the stream.
81 *
82 * If "block" is FALSE and the write would block, the function returns -1
83 * and sets errno to EWOULDBLOCK.
84 *
85 * @param buf data buffer to write
86 * @param len number of bytes to write
87 * @param block TRUE to use a blocking write
88 * @return number of bytes written, -1 on error
89 */
90 ssize_t (*write)(stream_t *this, void *buf, size_t len, bool block);
91
92 /**
93 * Register a callback to invoke when a write would not block.
94 *
95 * @param cb callback function, NULL to unregister
96 * @param data data to pass to callback
97 */
98 void (*on_write)(stream_t *this, stream_cb_t cb, void *data);
99
100 /**
101 * printf() convenience function for this stream.
102 *
103 * @param format printf format string
104 * @param ... argument list for format string
105 * @return number of characters written, negative on error
106 */
107 int (*print)(stream_t *this, char *format, ...);
108
109 /**
110 * vprintf() convenience function for this stream.
111 *
112 * @param format printf format string
113 * @param ap argument list for format string
114 * @return number of characters written, negative on error
115 */
116 int (*vprint)(stream_t *this, char *format, va_list ap);
117
118 /**
119 * Destroy a stream_t.
120 */
121 void (*destroy)(stream_t *this);
122 };
123
124 /**
125 * Create a stream from a file descriptor.
126 *
127 * The file descriptor MUST be a socket for non-blocking operation.
128 *
129 * @param fd file descriptor to wrap into a stream_t
130 * @return stream instance
131 */
132 stream_t *stream_create_from_fd(int fd);
133
134 #endif /** STREAM_H_ @}*/