AUTHORS: Add Valient Gough.
[openvswitch] / lib / stream-provider.h
1 /*
2  * Copyright (c) 2009, 2010 Nicira Networks.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at:
7  *
8  *     http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16
17 #ifndef STREAM_PROVIDER_H
18 #define STREAM_PROVIDER_H 1
19
20 #include <assert.h>
21 #include <sys/types.h>
22 #include "stream.h"
23
24 /* Active stream connection. */
25
26 /* Active stream connection.
27  *
28  * This structure should be treated as opaque by implementation. */
29 struct stream {
30     struct stream_class *class;
31     int state;
32     int error;
33     ovs_be32 remote_ip;
34     ovs_be16 remote_port;
35     ovs_be32 local_ip;
36     ovs_be16 local_port;
37     char *name;
38 };
39
40 void stream_init(struct stream *, struct stream_class *, int connect_status,
41                  const char *name);
42 void stream_set_remote_ip(struct stream *, ovs_be32 remote_ip);
43 void stream_set_remote_port(struct stream *, ovs_be16 remote_port);
44 void stream_set_local_ip(struct stream *, ovs_be32 local_ip);
45 void stream_set_local_port(struct stream *, ovs_be16 local_port);
46 static inline void stream_assert_class(const struct stream *stream,
47                                        const struct stream_class *class)
48 {
49     assert(stream->class == class);
50 }
51
52 struct stream_class {
53     /* Prefix for connection names, e.g. "tcp", "ssl", "unix". */
54     const char *name;
55
56     /* Attempts to connect to a peer.  'name' is the full connection name
57      * provided by the user, e.g. "tcp:1.2.3.4".  This name is useful for error
58      * messages but must not be modified.
59      *
60      * 'suffix' is a copy of 'name' following the colon and may be modified.
61      *
62      * Returns 0 if successful, otherwise a positive errno value.  If
63      * successful, stores a pointer to the new connection in '*streamp'.
64      *
65      * The open function must not block waiting for a connection to complete.
66      * If the connection cannot be completed immediately, it should return
67      * EAGAIN (not EINPROGRESS, as returned by the connect system call) and
68      * continue the connection in the background. */
69     int (*open)(const char *name, char *suffix, struct stream **streamp);
70
71     /* Closes 'stream' and frees associated memory. */
72     void (*close)(struct stream *stream);
73
74     /* Tries to complete the connection on 'stream'.  If 'stream''s connection
75      * is complete, returns 0 if the connection was successful or a positive
76      * errno value if it failed.  If the connection is still in progress,
77      * returns EAGAIN.
78      *
79      * The connect function must not block waiting for the connection to
80      * complete; instead, it should return EAGAIN immediately. */
81     int (*connect)(struct stream *stream);
82
83     /* Tries to receive up to 'n' bytes from 'stream' into 'buffer', and
84      * returns:
85      *
86      *     - If successful, the number of bytes received (between 1 and 'n').
87      *
88      *     - On error, a negative errno value.
89      *
90      *     - 0, if the connection has been closed in the normal fashion.
91      *
92      * The recv function will not be passed a zero 'n'.
93      *
94      * The recv function must not block waiting for data to arrive.  If no data
95      * have been received, it should return -EAGAIN immediately. */
96     ssize_t (*recv)(struct stream *stream, void *buffer, size_t n);
97
98     /* Tries to send up to 'n' bytes of 'buffer' on 'stream', and returns:
99      *
100      *     - If successful, the number of bytes sent (between 1 and 'n').
101      *
102      *     - On error, a negative errno value.
103      *
104      *     - Never returns 0.
105      *
106      * The send function will not be passed a zero 'n'.
107      *
108      * The send function must not block.  If no bytes can be immediately
109      * accepted for transmission, it should return -EAGAIN immediately. */
110     ssize_t (*send)(struct stream *stream, const void *buffer, size_t n);
111
112     /* Allows 'stream' to perform maintenance activities, such as flushing
113      * output buffers.
114      *
115      * May be null if 'stream' doesn't have anything to do here. */
116     void (*run)(struct stream *stream);
117
118     /* Arranges for the poll loop to wake up when 'stream' needs to perform
119      * maintenance activities.
120      *
121      * May be null if 'stream' doesn't have anything to do here. */
122     void (*run_wait)(struct stream *stream);
123
124     /* Arranges for the poll loop to wake up when 'stream' is ready to take an
125      * action of the given 'type'. */
126     void (*wait)(struct stream *stream, enum stream_wait_type type);
127 };
128 \f
129 /* Passive listener for incoming stream connections.
130  *
131  * This structure should be treated as opaque by stream implementations. */
132 struct pstream {
133     struct pstream_class *class;
134     char *name;
135 };
136
137 void pstream_init(struct pstream *, struct pstream_class *, const char *name);
138 static inline void pstream_assert_class(const struct pstream *pstream,
139                                         const struct pstream_class *class)
140 {
141     assert(pstream->class == class);
142 }
143
144 struct pstream_class {
145     /* Prefix for connection names, e.g. "ptcp", "pssl", "punix". */
146     const char *name;
147
148     /* Attempts to start listening for stream connections.  'name' is the full
149      * connection name provided by the user, e.g. "ptcp:1234".  This name is
150      * useful for error messages but must not be modified.
151      *
152      * 'suffix' is a copy of 'name' following the colon and may be modified.
153      *
154      * Returns 0 if successful, otherwise a positive errno value.  If
155      * successful, stores a pointer to the new connection in '*pstreamp'.
156      *
157      * The listen function must not block.  If the connection cannot be
158      * completed immediately, it should return EAGAIN (not EINPROGRESS, as
159      * returned by the connect system call) and continue the connection in the
160      * background. */
161     int (*listen)(const char *name, char *suffix, struct pstream **pstreamp);
162
163     /* Closes 'pstream' and frees associated memory. */
164     void (*close)(struct pstream *pstream);
165
166     /* Tries to accept a new connection on 'pstream'.  If successful, stores
167      * the new connection in '*new_streamp' and returns 0.  Otherwise, returns
168      * a positive errno value.
169      *
170      * The accept function must not block waiting for a connection.  If no
171      * connection is ready to be accepted, it should return EAGAIN. */
172     int (*accept)(struct pstream *pstream, struct stream **new_streamp);
173
174     /* Arranges for the poll loop to wake up when a connection is ready to be
175      * accepted on 'pstream'. */
176     void (*wait)(struct pstream *pstream);
177 };
178
179 /* Active and passive stream classes. */
180 extern struct stream_class tcp_stream_class;
181 extern struct pstream_class ptcp_pstream_class;
182 extern struct stream_class unix_stream_class;
183 extern struct pstream_class punix_pstream_class;
184 #ifdef HAVE_OPENSSL
185 extern struct stream_class ssl_stream_class;
186 extern struct pstream_class pssl_pstream_class;
187 #endif
188
189 #endif /* stream-provider.h */