tsocket: rewrite tsocket_guide.txt to reflect the current APIs
[ira/wip.git] / lib / tsocket / tsocket.h
1 /*
2    Unix SMB/CIFS implementation.
3
4    Copyright (C) Stefan Metzmacher 2009
5
6      ** NOTE! The following LGPL license applies to the tevent
7      ** library. This does NOT imply that all of Samba is released
8      ** under the LGPL
9
10    This library is free software; you can redistribute it and/or
11    modify it under the terms of the GNU Lesser General Public
12    License as published by the Free Software Foundation; either
13    version 3 of the License, or (at your option) any later version.
14
15    This library is distributed in the hope that it will be useful,
16    but WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
18    Lesser General Public License for more details.
19
20    You should have received a copy of the GNU Lesser General Public
21    License along with this library; if not, see <http://www.gnu.org/licenses/>.
22 */
23
24 #ifndef _TSOCKET_H
25 #define _TSOCKET_H
26
27 #include <talloc.h>
28 #include <tevent.h>
29
30 struct tsocket_address;
31 struct tdgram_context;
32 struct tstream_context;
33 struct iovec;
34
35 /*
36  * tsocket_address related functions
37  */
38 char *tsocket_address_string(const struct tsocket_address *addr,
39                              TALLOC_CTX *mem_ctx);
40
41 struct tsocket_address *_tsocket_address_copy(const struct tsocket_address *addr,
42                                               TALLOC_CTX *mem_ctx,
43                                               const char *location);
44
45 #define tsocket_address_copy(addr, mem_ctx) \
46         _tsocket_address_copy(addr, mem_ctx, __location__)
47
48 /*
49  * tdgram_context related functions
50  */
51 struct tevent_req *tdgram_recvfrom_send(TALLOC_CTX *mem_ctx,
52                                         struct tevent_context *ev,
53                                         struct tdgram_context *dgram);
54 ssize_t tdgram_recvfrom_recv(struct tevent_req *req,
55                              int *perrno,
56                              TALLOC_CTX *mem_ctx,
57                              uint8_t **buf,
58                              struct tsocket_address **src);
59
60 struct tevent_req *tdgram_sendto_send(TALLOC_CTX *mem_ctx,
61                                       struct tevent_context *ev,
62                                       struct tdgram_context *dgram,
63                                       const uint8_t *buf, size_t len,
64                                       const struct tsocket_address *dst);
65 ssize_t tdgram_sendto_recv(struct tevent_req *req,
66                            int *perrno);
67
68 struct tevent_req *tdgram_disconnect_send(TALLOC_CTX *mem_ctx,
69                                           struct tevent_context *ev,
70                                           struct tdgram_context *dgram);
71 int tdgram_disconnect_recv(struct tevent_req *req,
72                            int *perrno);
73
74 /*
75  * tstream_context related functions
76  */
77 ssize_t tstream_pending_bytes(struct tstream_context *stream);
78
79 struct tevent_req *tstream_readv_send(TALLOC_CTX *mem_ctx,
80                                       struct tevent_context *ev,
81                                       struct tstream_context *stream,
82                                       struct iovec *vector,
83                                       size_t count);
84 int tstream_readv_recv(struct tevent_req *req,
85                        int *perrno);
86
87 struct tevent_req *tstream_writev_send(TALLOC_CTX *mem_ctx,
88                                        struct tevent_context *ev,
89                                        struct tstream_context *stream,
90                                        const struct iovec *vector,
91                                        size_t count);
92 int tstream_writev_recv(struct tevent_req *req,
93                         int *perrno);
94
95 struct tevent_req *tstream_disconnect_send(TALLOC_CTX *mem_ctx,
96                                            struct tevent_context *ev,
97                                            struct tstream_context *stream);
98 int tstream_disconnect_recv(struct tevent_req *req,
99                             int *perrno);
100
101 /*
102  * BSD sockets: inet, inet6 and unix
103  */
104
105 int _tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx,
106                                        const char *fam,
107                                        const char *addr,
108                                        uint16_t port,
109                                        struct tsocket_address **_addr,
110                                        const char *location);
111 #define tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr) \
112         _tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr, \
113                                            __location__)
114
115 char *tsocket_address_inet_addr_string(const struct tsocket_address *addr,
116                                        TALLOC_CTX *mem_ctx);
117 uint16_t tsocket_address_inet_port(const struct tsocket_address *addr);
118 int tsocket_address_inet_set_port(struct tsocket_address *addr,
119                                   uint16_t port);
120
121 int _tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx,
122                                     const char *path,
123                                     struct tsocket_address **_addr,
124                                     const char *location);
125 #define tsocket_address_unix_from_path(mem_ctx, path, _addr) \
126         _tsocket_address_unix_from_path(mem_ctx, path, _addr, \
127                                         __location__)
128 char *tsocket_address_unix_path(const struct tsocket_address *addr,
129                                 TALLOC_CTX *mem_ctx);
130
131 int _tdgram_inet_udp_socket(const struct tsocket_address *local,
132                             const struct tsocket_address *remote,
133                             TALLOC_CTX *mem_ctx,
134                             struct tdgram_context **dgram,
135                             const char *location);
136 #define tdgram_inet_udp_socket(local, remote, mem_ctx, dgram) \
137         _tdgram_inet_udp_socket(local, remote, mem_ctx, dgram, __location__)
138
139 int _tdgram_unix_socket(const struct tsocket_address *local,
140                         const struct tsocket_address *remote,
141                         TALLOC_CTX *mem_ctx,
142                         struct tdgram_context **dgram,
143                         const char *location);
144 #define tdgram_unix_socket(local, remote, mem_ctx, dgram) \
145         _tdgram_unix_socket(local, remote, mem_ctx, dgram, __location__)
146
147 struct tevent_req * tstream_inet_tcp_connect_send(TALLOC_CTX *mem_ctx,
148                                         struct tevent_context *ev,
149                                         const struct tsocket_address *local,
150                                         const struct tsocket_address *remote);
151 int _tstream_inet_tcp_connect_recv(struct tevent_req *req,
152                                    int *perrno,
153                                    TALLOC_CTX *mem_ctx,
154                                    struct tstream_context **stream,
155                                    const char *location);
156 #define tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream) \
157         _tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, \
158                                        __location__)
159
160 struct tevent_req * tstream_unix_connect_send(TALLOC_CTX *mem_ctx,
161                                         struct tevent_context *ev,
162                                         const struct tsocket_address *local,
163                                         const struct tsocket_address *remote);
164 int _tstream_unix_connect_recv(struct tevent_req *req,
165                                int *perrno,
166                                TALLOC_CTX *mem_ctx,
167                                struct tstream_context **stream,
168                                const char *location);
169 #define tstream_unix_connect_recv(req, perrno, mem_ctx, stream) \
170         _tstream_unix_connect_recv(req, perrno, mem_ctx, stream, \
171                                           __location__)
172
173 int _tstream_unix_socketpair(TALLOC_CTX *mem_ctx1,
174                              struct tstream_context **_stream1,
175                              TALLOC_CTX *mem_ctx2,
176                              struct tstream_context **_stream2,
177                              const char *location);
178 #define tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2) \
179         _tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2, \
180                                  __location__)
181
182 int _tstream_bsd_existing_socket(TALLOC_CTX *mem_ctx,
183                                  int fd,
184                                  struct tstream_context **_stream,
185                                  const char *location);
186 #define tstream_bsd_existing_socket(mem_ctx, fd, stream) \
187         _tstream_bsd_existing_socket(mem_ctx, fd, stream, \
188                                      __location__)
189
190 /*
191  * Queue and PDU helpers
192  */
193
194 struct tevent_req *tdgram_sendto_queue_send(TALLOC_CTX *mem_ctx,
195                                             struct tevent_context *ev,
196                                             struct tdgram_context *dgram,
197                                             struct tevent_queue *queue,
198                                             const uint8_t *buf,
199                                             size_t len,
200                                             struct tsocket_address *dst);
201 ssize_t tdgram_sendto_queue_recv(struct tevent_req *req, int *perrno);
202
203 typedef int (*tstream_readv_pdu_next_vector_t)(struct tstream_context *stream,
204                                                void *private_data,
205                                                TALLOC_CTX *mem_ctx,
206                                                struct iovec **vector,
207                                                size_t *count);
208 struct tevent_req *tstream_readv_pdu_send(TALLOC_CTX *mem_ctx,
209                                 struct tevent_context *ev,
210                                 struct tstream_context *stream,
211                                 tstream_readv_pdu_next_vector_t next_vector_fn,
212                                 void *next_vector_private);
213 int tstream_readv_pdu_recv(struct tevent_req *req, int *perrno);
214
215 struct tevent_req *tstream_readv_pdu_queue_send(TALLOC_CTX *mem_ctx,
216                                 struct tevent_context *ev,
217                                 struct tstream_context *stream,
218                                 struct tevent_queue *queue,
219                                 tstream_readv_pdu_next_vector_t next_vector_fn,
220                                 void *next_vector_private);
221 int tstream_readv_pdu_queue_recv(struct tevent_req *req, int *perrno);
222
223 struct tevent_req *tstream_writev_queue_send(TALLOC_CTX *mem_ctx,
224                                              struct tevent_context *ev,
225                                              struct tstream_context *stream,
226                                              struct tevent_queue *queue,
227                                              const struct iovec *vector,
228                                              size_t count);
229 int tstream_writev_queue_recv(struct tevent_req *req, int *perrno);
230
231 #endif /* _TSOCKET_H */
232