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     const 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 *, 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)
  49 {
  50     assert(stream->class == class);
  51 }
  52
  53 struct stream_class {
  54     /* Prefix for connection names, e.g. "tcp", "ssl", "unix". */
  55     const char *name;
  56
  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. */
  60     bool needs_probes;
  61
  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.
  65      *
  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.)
  71      *
  72      * Returns 0 if successful, otherwise a positive errno value.  If
  73      * successful, stores a pointer to the new connection in '*streamp'.
  74      *
  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,
  80                 uint8_t dscp);
  81
  82     /* Closes 'stream' and frees associated memory. */
  83     void (*close)(struct stream *stream);
  84
  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,
  88      * returns EAGAIN.
  89      *
  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);
  93
  94     /* Tries to receive up to 'n' bytes from 'stream' into 'buffer', and
  95      * returns:
  96      *
  97      *     - If successful, the number of bytes received (between 1 and 'n').
  98      *
  99      *     - On error, a negative errno value.
 100      *
 101      *     - 0, if the connection has been closed in the normal fashion.
 102      *
 103      * The recv function will not be passed a zero 'n'.
 104      *
 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);
 108
 109     /* Tries to send up to 'n' bytes of 'buffer' on 'stream', and returns:
 110      *
 111      *     - If successful, the number of bytes sent (between 1 and 'n').
 112      *
 113      *     - On error, a negative errno value.
 114      *
 115      *     - Never returns 0.
 116      *
 117      * The send function will not be passed a zero 'n'.
 118      *
 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);
 122
 123     /* Allows 'stream' to perform maintenance activities, such as flushing
 124      * output buffers.
 125      *
 126      * May be null if 'stream' doesn't have anything to do here. */
 127     void (*run)(struct stream *stream);
 128
 129     /* Arranges for the poll loop to wake up when 'stream' needs to perform
 130      * maintenance activities.
 131      *
 132      * May be null if 'stream' doesn't have anything to do here. */
 133     void (*run_wait)(struct stream *stream);
 134
 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);
 138 };
 139 \f
 140 /* Passive listener for incoming stream connections.
 141  *
 142  * This structure should be treated as opaque by stream implementations. */
 143 struct pstream {
 144     const struct pstream_class *class;
 145     char *name;
 146 };
 147
 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)
 151 {
 152     assert(pstream->class == class);
 153 }
 154
 155 struct pstream_class {
 156     /* Prefix for connection names, e.g. "ptcp", "pssl", "punix". */
 157     const char *name;
 158
 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. */
 162     bool needs_probes;
 163
 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.
 167      *
 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.)
 173      *
 174      * Returns 0 if successful, otherwise a positive errno value.  If
 175      * successful, stores a pointer to the new connection in '*pstreamp'.
 176      *
 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
 180      * background. */
 181     int (*listen)(const char *name, char *suffix, struct pstream **pstreamp,
 182                   uint8_t dscp);
 183
 184     /* Closes 'pstream' and frees associated memory. */
 185     void (*close)(struct pstream *pstream);
 186
 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.
 190      *
 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);
 194
 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);
 198 };
 199
 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;
 205 #ifdef HAVE_OPENSSL
 206 extern const struct stream_class ssl_stream_class;
 207 extern const struct pstream_class pssl_pstream_class;
 208 #endif
 209
 210 #endif /* stream-provider.h */