diff options
author | Christian Grothoff <christian@grothoff.org> | 2011-12-09 17:28:06 +0000 |
---|---|---|
committer | Christian Grothoff <christian@grothoff.org> | 2011-12-09 17:28:06 +0000 |
commit | aac6badf87eb6b89def532f06aa9c6e1544f5d60 (patch) | |
tree | e4e4a6aa279881cb5d7497433c592c9135a37cb7 /src/include/gnunet_stream_lib.h | |
parent | 6d753c220dad05da6d3774aca83acbf741b18a2b (diff) | |
download | gnunet-aac6badf87eb6b89def532f06aa9c6e1544f5d60.tar.gz gnunet-aac6badf87eb6b89def532f06aa9c6e1544f5d60.zip |
-revising stream library api
Diffstat (limited to 'src/include/gnunet_stream_lib.h')
-rw-r--r-- | src/include/gnunet_stream_lib.h | 146 |
1 files changed, 108 insertions, 38 deletions
diff --git a/src/include/gnunet_stream_lib.h b/src/include/gnunet_stream_lib.h index b06f3f564..b04892a08 100644 --- a/src/include/gnunet_stream_lib.h +++ b/src/include/gnunet_stream_lib.h | |||
@@ -54,39 +54,69 @@ enum GNUNET_STREAM_Status | |||
54 | GNUNET_STREAM_TIMEOUT = 1, | 54 | GNUNET_STREAM_TIMEOUT = 1, |
55 | 55 | ||
56 | /** | 56 | /** |
57 | * Other side has shutdown the socket for this type of operation | ||
58 | * (reading/writing) | ||
59 | */ | ||
60 | GNUNET_STREAM_SHUTDOWN = 2 | ||
61 | |||
62 | /** | ||
57 | * A serious error occured while operating of this stream | 63 | * A serious error occured while operating of this stream |
58 | */ | 64 | */ |
59 | GNUNET_STREAM_SYSERR = 2 | 65 | GNUNET_STREAM_SYSERR = 3 |
60 | }; | 66 | }; |
61 | 67 | ||
62 | /** | 68 | /** |
63 | * Opaque handler for stream | 69 | * Opaque handler for stream |
64 | */ | 70 | */ |
65 | struct GNUNET_STREAM_socket; | 71 | struct GNUNET_STREAM_Socket; |
66 | 72 | ||
67 | /** | 73 | /** |
68 | * Functions of this type will be called when a stream is established | 74 | * Functions of this type will be called when a stream is established |
69 | * | 75 | * |
70 | * @param cls the closure from GNUNET_STREAM_open | 76 | * @param cls the closure from GNUNET_STREAM_open |
77 | * @param socket socket to use to communicate with the other side (read/write) | ||
71 | */ | 78 | */ |
72 | typedef void (*GNUNET_STREAM_OpenCallback) (void *cls); | 79 | typedef void (*GNUNET_STREAM_OpenCallback) (void *cls, |
80 | struct GNUNET_STREAM_Socket *socket); | ||
81 | |||
73 | 82 | ||
74 | /** | 83 | /** |
75 | * Tries to open a stream to the target peer | 84 | * Tries to open a stream to the target peer |
76 | * | 85 | * |
77 | * @param cls the closure | ||
78 | * @param target the target peer to which the stream has to be opened | 86 | * @param target the target peer to which the stream has to be opened |
79 | * @param app_port the application port number which uniquely identifies this | 87 | * @param app_port the application port number which uniquely identifies this |
80 | * stream | 88 | * stream |
81 | * @param open_cb this function will be called after stream has be established | 89 | * @param open_cb this function will be called after stream has be established |
90 | * @param open_cb_cls the closure for open_cb | ||
82 | * @return if successful it returns the stream socket; NULL if stream cannot be | 91 | * @return if successful it returns the stream socket; NULL if stream cannot be |
83 | * opened | 92 | * opened |
84 | */ | 93 | */ |
85 | struct GNUNET_STREAM_socket * | 94 | struct GNUNET_STREAM_Socket * |
86 | GNUNET_STREAM_open (void *cls, | 95 | GNUNET_STREAM_open (const struct GNUNET_PeerIdentity *target, |
87 | const struct GNUNET_PeerIdentity *target, | ||
88 | GNUNET_MESH_ApplicationType app_port, | 96 | GNUNET_MESH_ApplicationType app_port, |
89 | GNUNET_STREAM_OpenCallback open_cb); | 97 | GNUNET_STREAM_OpenCallback open_cb, |
98 | void *open_cb_cls); | ||
99 | |||
100 | |||
101 | /** | ||
102 | * Shutdown the stream for reading or writing (man 2 shutdown). | ||
103 | * | ||
104 | * @param socket the stream socket | ||
105 | * @param how SHUT_RD, SHUT_WR or SHUT_RDWR | ||
106 | */ | ||
107 | void | ||
108 | GNUNET_STREAM_shutdown (struct GNUNET_STREAM_Socket *socket, | ||
109 | int how); | ||
110 | |||
111 | |||
112 | /** | ||
113 | * Closes the stream | ||
114 | * | ||
115 | * @param socket the stream socket | ||
116 | */ | ||
117 | void | ||
118 | GNUNET_STREAM_close (struct GNUNET_STREAM_Socket *socket); | ||
119 | |||
90 | 120 | ||
91 | /** | 121 | /** |
92 | * Functions of this type are called upon new stream connection from other peers | 122 | * Functions of this type are called upon new stream connection from other peers |
@@ -99,35 +129,59 @@ GNUNET_STREAM_open (void *cls, | |||
99 | * stream (the socket will be invalid after the call) | 129 | * stream (the socket will be invalid after the call) |
100 | */ | 130 | */ |
101 | typedef int (*GNUNET_STREAM_ListenCallback) (void *cls, | 131 | typedef int (*GNUNET_STREAM_ListenCallback) (void *cls, |
102 | struct GNUNET_STREAM_socket *socket, | 132 | struct GNUNET_STREAM_Socket *socket, |
103 | const struct | 133 | const struct |
104 | GNUNET_PeerIdentity *initiator); | 134 | GNUNET_PeerIdentity *initiator); |
105 | 135 | ||
136 | |||
137 | /** | ||
138 | * A socket for listening. | ||
139 | */ | ||
140 | struct GNUNET_STREAM_ListenSocket; | ||
141 | |||
106 | /** | 142 | /** |
107 | * Listens for stream connections for a specific application ports | 143 | * Listens for stream connections for a specific application ports |
108 | * | 144 | * |
109 | * @param app_port the application port for which new streams will be accepted | 145 | * @param app_port the application port for which new streams will be accepted |
110 | * @param listen_cb this function will be called when a peer tries to establish | 146 | * @param listen_cb this function will be called when a peer tries to establish |
111 | * a stream with us | 147 | * a stream with us |
112 | * @return GNUNET_OK if we are listening, GNUNET_SYSERR for any error | 148 | * @param listen_cb_cls closure for listen_cb |
149 | * @return listen socket, NULL for any error | ||
113 | */ | 150 | */ |
114 | int | 151 | struct GNUNET_STREAM_ListenSocket * |
115 | GNUNET_STREAM_listen (GNUNET_MESH_ApplicationType app_port, | 152 | GNUNET_STREAM_listen (GNUNET_MESH_ApplicationType app_port, |
116 | GNUNET_STREAM_ListenCallback listen_cb, | 153 | GNUNET_STREAM_ListenCallback listen_cb, |
117 | void *cls); | 154 | void *listen_cb_cls); |
155 | |||
118 | 156 | ||
119 | /** | 157 | /** |
120 | * Functions of this signature are called whenever reading/writing operations | 158 | * Closes the listen socket |
159 | * | ||
160 | * @param socket the listen socket | ||
161 | */ | ||
162 | void | ||
163 | GNUNET_STREAM_listen_close (struct GNUNET_STREAM_ListenSocket *socket); | ||
164 | |||
165 | |||
166 | /** | ||
167 | * Functions of this signature are called whenever writing operations | ||
121 | * on a stream are executed | 168 | * on a stream are executed |
122 | * | 169 | * |
123 | * @param cls the closure from GNUNET_STREAM_write/read | 170 | * @param cls the closure from GNUNET_STREAM_write/read |
124 | * @param status the status of the stream at the time this function is called | 171 | * @param status the status of the stream at the time this function is called |
125 | * @param size the number of bytes read or written | 172 | * @param size the number of bytes read or written |
126 | */ | 173 | */ |
127 | typedef void (*GNUNET_STREAM_CompletionCallback) (void *cls, | 174 | typedef void (*GNUNET_STREAM_CompletionContinuation) (void *cls, |
128 | enum GNUNET_STREAM_Status | 175 | enum GNUNET_STREAM_Status |
129 | status, | 176 | status, |
130 | size_t size); | 177 | size_t size); |
178 | |||
179 | |||
180 | /** | ||
181 | * Handle to cancel IO operations. | ||
182 | */ | ||
183 | struct GNUNET_STREAM_IOHandle; | ||
184 | |||
131 | 185 | ||
132 | /** | 186 | /** |
133 | * Tries to write the given data to the stream | 187 | * Tries to write the given data to the stream |
@@ -135,43 +189,59 @@ typedef void (*GNUNET_STREAM_CompletionCallback) (void *cls, | |||
135 | * @param socket the socket representing a stream | 189 | * @param socket the socket representing a stream |
136 | * @param data the data buffer from where the data is written into the stream | 190 | * @param data the data buffer from where the data is written into the stream |
137 | * @param size the number of bytes to be written from the data buffer | 191 | * @param size the number of bytes to be written from the data buffer |
138 | * @param write_cb the function to call upon writing some bytes into the stream | ||
139 | * @param timeout the timeout period | 192 | * @param timeout the timeout period |
140 | * @param cls the closure | 193 | * @param write_cont the function to call upon writing some bytes into the stream |
194 | * @param write_cont_cls the closure | ||
195 | * @return handle to cancel the operation | ||
141 | */ | 196 | */ |
142 | void | 197 | struct GNUNET_STREAM_IOHandle * |
143 | GNUNET_STREAM_write (const struct GNUNET_STREAM_socket *socket, | 198 | GNUNET_STREAM_write (struct GNUNET_STREAM_Socket *socket, |
144 | void *data, | 199 | const void *data, |
145 | size_t size, | 200 | size_t size, |
146 | GNUNET_STREAM_CompletionCallback write_cb, | ||
147 | struct GNUNET_TIME_Relative timeout, | 201 | struct GNUNET_TIME_Relative timeout, |
148 | void *cls); | 202 | GNUNET_STREAM_CompletionContinuation write_cont, |
203 | void *write_cont_cls); | ||
204 | |||
205 | |||
206 | /** | ||
207 | * Functions of this signature are called whenever data is available from the | ||
208 | * stream. | ||
209 | * | ||
210 | * @param cls the closure from GNUNET_STREAM_write/read | ||
211 | * @param status the status of the stream at the time this function is called | ||
212 | * @param data traffic from the other side | ||
213 | * @param size the number of bytes available in data read | ||
214 | */ | ||
215 | typedef void (*GNUNET_STREAM_DataProcessor) (void *cls, | ||
216 | enum GNUNET_STREAM_Status status, | ||
217 | const char *data, | ||
218 | size_t size); | ||
219 | |||
149 | 220 | ||
150 | /** | 221 | /** |
151 | * Tries to read data from the stream | 222 | * Tries to read data from the stream |
152 | * | 223 | * |
153 | * @param socket the socket representing a stream | 224 | * @param socket the socket representing a stream |
154 | * @param buffer the buffer into which the read data is stored | ||
155 | * @param size the number of bytes that are to be read | ||
156 | * @param read_cb the completion callback function which is called after | ||
157 | * attempting to read size number of bytes from the stream | ||
158 | * @param timeout the timeout period | 225 | * @param timeout the timeout period |
159 | * @param cls the closure | 226 | * @param proc function to call with data |
227 | * @param proc_cls the closure for proc | ||
228 | * @return handle to cancel the operation | ||
160 | */ | 229 | */ |
161 | void | 230 | struct GNUNET_STREAM_IOHandle * |
162 | GNUNET_STREAM_read (const struct GNUNET_STREAM_socket *socket, | 231 | GNUNET_STREAM_read (const struct GNUNET_STREAM_Socket *socket, |
163 | void *buffer, | ||
164 | size_t size, | ||
165 | GNUNET_STREAM_CompletionCallback read_cb, | ||
166 | struct GNUNET_TIME_Relative timeout, | 232 | struct GNUNET_TIME_Relative timeout, |
167 | void *cls); | 233 | GNUNET_STREAM_DataProcessor proc, |
234 | void *proc_cls); | ||
235 | |||
236 | |||
168 | /** | 237 | /** |
169 | * Closes the stream | 238 | * Cancel pending read or write operation. |
170 | * | 239 | * |
171 | * @param socket the stream socket | 240 | * @param ioh handle to operation to cancel |
172 | */ | 241 | */ |
173 | void | 242 | void |
174 | GNUNET_STREAM_close (struct GNUNET_STREAM_socket *socket); | 243 | GNUNET_STREAM_io_cancel (struct GNUNET_STREAM_IOHandle *ioh); |
244 | |||
175 | 245 | ||
176 | #if 0 | 246 | #if 0 |
177 | { | 247 | { |