stream: add support for UNIX streams
[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
30 /**
31 * Constructor function prototype for stream_t.
32 *
33 * @param uri URI to create a stream for
34 * @return stream instance, NULL on error
35 */
36 typedef stream_t*(*stream_constructor_t)(char *uri);
37
38 /**
39 * Callback function prototype, called when stream is ready.
40 *
41 * It is not allowed to destroy the stream during the callback, this would
42 * deadlock. Instead, return FALSE to destroy the stream. It is not allowed
43 * to call on_read()/on_write() during this 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 to destroy the stream
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 * Register a callback to invoke when stream has data to read.
75 *
76 * @param cb callback function, NULL to unregister
77 * @param data data to pass to callback
78 */
79 void (*on_read)(stream_t *this, stream_cb_t cb, void *data);
80
81 /**
82 * Write data to the stream.
83 *
84 * If "block" is FALSE and the write would block, the function returns -1
85 * and sets errno to EWOULDBLOCK.
86 *
87 * @param buf data buffer to write
88 * @param len number of bytes to write
89 * @param block TRUE to use a blocking write
90 * @return number of bytes written, -1 on error
91 */
92 ssize_t (*write)(stream_t *this, void *buf, size_t len, bool block);
93
94 /**
95 * Register a callback to invoke when a write would not block.
96 *
97 * @param cb callback function, NULL to unregister
98 * @param data data to pass to callback
99 */
100 void (*on_write)(stream_t *this, stream_cb_t cb, void *data);
101
102 /**
103 * printf() convenience function for this stream.
104 *
105 * @param format printf format string
106 * @param ... argument list for format string
107 * @return number of characters written, negative on error
108 */
109 int (*print)(stream_t *this, char *format, ...);
110
111 /**
112 * vprintf() convenience function for this stream.
113 *
114 * @param format printf format string
115 * @param ap argument list for format string
116 * @return number of characters written, negative on error
117 */
118 int (*vprint)(stream_t *this, char *format, va_list ap);
119
120 /**
121 * Destroy a stream_t.
122 */
123 void (*destroy)(stream_t *this);
124 };
125
126 /**
127 * Create a stream for UNIX sockets.
128 *
129 * UNIX URIs start with unix://, followed by the socket path. For absolute
130 * paths, an URI looks something like:
131 *
132 * unix:///path/to/socket
133 *
134 * @param uri UNIX socket specific URI, must start with "unix://"
135 * @return stream instance, NULL on failure
136 */
137 stream_t *stream_create_unix(char *uri);
138
139 /**
140 * Helper function to parse a unix:// URI to a sockaddr
141 *
142 * @param uri URI
143 * @param addr sockaddr
144 * @return length of sockaddr, -1 on error
145 */
146 int stream_parse_uri_unix(char *uri, struct sockaddr_un *addr);
147
148 /**
149 * Create a stream from a file descriptor.
150 *
151 * The file descriptor MUST be a socket for non-blocking operation.
152 *
153 * @param fd file descriptor to wrap into a stream_t
154 * @return stream instance
155 */
156 stream_t *stream_create_from_fd(int fd);
157
158 #endif /** STREAM_H_ @}*/