2 * Copyright (c) 2009, 2010 Nicira Networks.
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:
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef STREAM_PROVIDER_H
18 #define STREAM_PROVIDER_H 1
21 #include <sys/types.h>
24 /* Active stream connection. */
26 /* Active stream connection.
28 * This structure should be treated as opaque by implementation. */
30 const struct stream_class *class;
40 void stream_init(struct stream *, const struct stream_class *,
41 int connect_status, const char *name);
42 void stream_set_remote_ip(struct stream *, ovs_be32 remote_ip);
43 void stream_set_dscp(struct stream *, uint8_t dscp);
44 void stream_set_remote_port(struct stream *, ovs_be16 remote_port);
45 void stream_set_local_ip(struct stream *, ovs_be32 local_ip);
46 void stream_set_local_port(struct stream *, ovs_be16 local_port);
47 static inline void stream_assert_class(const struct stream *stream,
48 const struct stream_class *class)
50 assert(stream->class == class);
54 /* Prefix for connection names, e.g. "tcp", "ssl", "unix". */
57 /* True if this stream needs periodic probes to verify connectivty. For
58 * streams which need probes, it can take a long time to notice the
59 * connection was dropped. */
62 /* Attempts to connect to a peer. 'name' is the full connection name
63 * provided by the user, e.g. "tcp:1.2.3.4". This name is useful for error
64 * messages but must not be modified.
66 * 'suffix' is a copy of 'name' following the colon and may be modified.
67 * 'dscp' is the DSCP value that the new connection should use in the IP
68 * packets it sends. (If no DSCP value should be set in the packet, dscp
69 * will be set to DSCP_INVALID. If no DSCP value is specified, DSCP_DEFAULT
70 * value will be applied.)
72 * Returns 0 if successful, otherwise a positive errno value. If
73 * successful, stores a pointer to the new connection in '*streamp'.
75 * The open function must not block waiting for a connection to complete.
76 * If the connection cannot be completed immediately, it should return
77 * EAGAIN (not EINPROGRESS, as returned by the connect system call) and
78 * continue the connection in the background. */
79 int (*open)(const char *name, char *suffix, struct stream **streamp,
82 /* Closes 'stream' and frees associated memory. */
83 void (*close)(struct stream *stream);
85 /* Tries to complete the connection on 'stream'. If 'stream''s connection
86 * is complete, returns 0 if the connection was successful or a positive
87 * errno value if it failed. If the connection is still in progress,
90 * The connect function must not block waiting for the connection to
91 * complete; instead, it should return EAGAIN immediately. */
92 int (*connect)(struct stream *stream);
94 /* Tries to receive up to 'n' bytes from 'stream' into 'buffer', and
97 * - If successful, the number of bytes received (between 1 and 'n').
99 * - On error, a negative errno value.
101 * - 0, if the connection has been closed in the normal fashion.
103 * The recv function will not be passed a zero 'n'.
105 * The recv function must not block waiting for data to arrive. If no data
106 * have been received, it should return -EAGAIN immediately. */
107 ssize_t (*recv)(struct stream *stream, void *buffer, size_t n);
109 /* Tries to send up to 'n' bytes of 'buffer' on 'stream', and returns:
111 * - If successful, the number of bytes sent (between 1 and 'n').
113 * - On error, a negative errno value.
117 * The send function will not be passed a zero 'n'.
119 * The send function must not block. If no bytes can be immediately
120 * accepted for transmission, it should return -EAGAIN immediately. */
121 ssize_t (*send)(struct stream *stream, const void *buffer, size_t n);
123 /* Allows 'stream' to perform maintenance activities, such as flushing
126 * May be null if 'stream' doesn't have anything to do here. */
127 void (*run)(struct stream *stream);
129 /* Arranges for the poll loop to wake up when 'stream' needs to perform
130 * maintenance activities.
132 * May be null if 'stream' doesn't have anything to do here. */
133 void (*run_wait)(struct stream *stream);
135 /* Arranges for the poll loop to wake up when 'stream' is ready to take an
136 * action of the given 'type'. */
137 void (*wait)(struct stream *stream, enum stream_wait_type type);
140 /* Passive listener for incoming stream connections.
142 * This structure should be treated as opaque by stream implementations. */
144 const struct pstream_class *class;
148 void pstream_init(struct pstream *, const struct pstream_class *, const char *name);
149 static inline void pstream_assert_class(const struct pstream *pstream,
150 const struct pstream_class *class)
152 assert(pstream->class == class);
155 struct pstream_class {
156 /* Prefix for connection names, e.g. "ptcp", "pssl", "punix". */
159 /* True if this pstream needs periodic probes to verify connectivty. For
160 * pstreams which need probes, it can take a long time to notice the
161 * connection was dropped. */
164 /* Attempts to start listening for stream connections. 'name' is the full
165 * connection name provided by the user, e.g. "ptcp:1234". This name is
166 * useful for error messages but must not be modified.
168 * 'suffix' is a copy of 'name' following the colon and may be modified.
169 * 'dscp' is the DSCP value that the new connection should use in the IP
170 * packets it sends. (If no DSCP value should be set in the packet, dscp
171 * will be set to DSCP_INVALID. If no DSCP value is specified, DSCP_DEFAULT
172 * value will be applied.)
174 * Returns 0 if successful, otherwise a positive errno value. If
175 * successful, stores a pointer to the new connection in '*pstreamp'.
177 * The listen function must not block. If the connection cannot be
178 * completed immediately, it should return EAGAIN (not EINPROGRESS, as
179 * returned by the connect system call) and continue the connection in the
181 int (*listen)(const char *name, char *suffix, struct pstream **pstreamp,
184 /* Closes 'pstream' and frees associated memory. */
185 void (*close)(struct pstream *pstream);
187 /* Tries to accept a new connection on 'pstream'. If successful, stores
188 * the new connection in '*new_streamp' and returns 0. Otherwise, returns
189 * a positive errno value.
191 * The accept function must not block waiting for a connection. If no
192 * connection is ready to be accepted, it should return EAGAIN. */
193 int (*accept)(struct pstream *pstream, struct stream **new_streamp);
195 /* Arranges for the poll loop to wake up when a connection is ready to be
196 * accepted on 'pstream'. */
197 void (*wait)(struct pstream *pstream);
200 /* Active and passive stream classes. */
201 extern const struct stream_class tcp_stream_class;
202 extern const struct pstream_class ptcp_pstream_class;
203 extern const struct stream_class unix_stream_class;
204 extern const struct pstream_class punix_pstream_class;
206 extern const struct stream_class ssl_stream_class;
207 extern const struct pstream_class pssl_pstream_class;
210 #endif /* stream-provider.h */