monotone

monotone Mtn Source Tree

Root/netxx/stream.h

1/*
2 * Copyright (C) 2001-2004 Peter J Jones (pjones@pmade.org)
3 * All Rights Reserved
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
7 * are met:
8 *
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
14 * distribution.
15 * 3. Neither the name of the Author nor the names of its contributors
16 * may be used to endorse or promote products derived from this software
17 * without specific prior written permission.
18 *
19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
20 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
22 * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR
23 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
26 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
27 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
29 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 * SUCH DAMAGE.
31 */
32
33/** @file
34 * This file contains the definition of the Netxx::Stream class.
35**/
36
37#ifndef _netxx_stream_h_
38#define _netxx_stream_h_
39
40// Netxx includes
41#include <netxx/types.h>
42#include <netxx/streambase.h>
43
44namespace Netxx {
45
46 // forward declarations
47 class ProbeInfo;
48
49/**
50 * The Netxx::Stream class is used to establish a connection with a peer.
51 * The peer to connect to is listed in a Netxx::Address class. The peer may
52 * have more than one address in the Netxx::Address and the Netxx::Stream
53 * class will connect to the first one possible.
54 *
55 * This class is mainly for a 'client' application since it makes the
56 * connection to a given peer. To make is useful in a server application,
57 * this class also has a constructor that you can use to communicate with a
58 * client that was returned from a call to accept_connection().
59**/
60class Stream : public StreamBase {
61public:
62 //####################################################################
63 /**
64 * Construct a new Netxx::Stream and connect to the given peer. The
65 * first address in the Netxx::Address class that works will be the one
66 * the Stream object is connected to. If the Stream object cannot
67 * connect to any of the address an exception is trown.
68 *
69 * If a timeout is given, it will be used for all stream operations,
70 * including the initial connection to the peer.
71 *
72 * @param address The list of addresses for the peer.
73 * @param timeout An optional timeout to use for all operations.
74 * @author Peter Jones
75 **/
76 //####################################################################
77 explicit Stream (const Address &address, const Timeout &timeout=Timeout());
78
79 //####################################################################
80 /**
81 * Construct a new Netxx::Stream without a Netxx::Address. Instead given
82 * a char* that holds the name of the peer. This name will be passed to
83 * the Netxx::Address constructor along with the given default port
84 * number.
85 *
86 * @param uri The name of the peer to connect to in a possible URI format.
87 * @param default_port The port to use if the given URI does not have one.
88 * @param timeout An optional timeout to use for all operations.
89 * @see Netxx::Address
90 * @author Peter Jones
91 **/
92 //####################################################################
93 explicit Stream (const char *uri, port_type default_port=0, const Timeout &timeout=Timeout());
94
95 //####################################################################
96 /**
97 * Construct a new Netxx::Stream and take over an already established
98 * connection. This Stream object will then own the connection socket
99 * and will close it in its destructor.
100 *
101 * This is useful for server applications so that they can use a
102 * Netxx::Stream object to communicate with a new client that was
103 * returned from Netxx::StreamServer::accept_connection().
104 *
105 * @param socketfd The file descriptor for the socket to own.
106 * @param timeout An optional timeout to use for all operations.
107 * @author Peter Jones
108 **/
109 //####################################################################
110 explicit Stream (socket_type socketfd, const Timeout &timeout=Timeout());
111
112 //####################################################################
113 /**
114 * Netxx::Stream copy constructor. I can't see how this would be very
115 * useful but it is provided for safety and completeness. The copy
116 * constructor will cause a copy of the socket to be made.
117 *
118 * @param other The other Netxx::Stream to copy from.
119 * @author Peter Jones
120 **/
121 //####################################################################
122 Stream (const Stream &other);
123
124 //####################################################################
125 /**
126 * Assignement operator. I can't see how this would be very useful but
127 * it is provided for safety and completeness. This function will
128 * preform a copy of the give Netxx::Stream object via the Netxx::Stream
129 * copy constructor.
130 *
131 * @param other The other Netxx::Stream to copy from.
132 * @author Peter Jones
133 **/
134 //####################################################################
135 Stream& operator= (const Stream &other);
136
137 //####################################################################
138 /**
139 * Exchange connection information with another Netxx::Stream. This is
140 * similar to std::swap().
141 *
142 * @param other The other Netxx::Stream object to swap with.
143 * @author Peter Jones
144 **/
145 //####################################################################
146 void swap (Stream &other);
147
148 //####################################################################
149 /**
150 * Netxx::Stream destructor. Close the connection with the peer if there
151 * is one.
152 *
153 * @author Peter Jones
154 **/
155 //####################################################################
156 ~Stream (void);
157
158 //####################################################################
159 /**
160 * Read data from the connected peer and place then in the given buffer.
161 * If an error occures this function will throw an exception. If a
162 * timeout occures (only if you set a timeout) then -1 is returned.
163 *
164 * It is possible for this function to return -1 if you did not set a
165 * timeout. This would happen if you had set the socket for this
166 * connection to non-blocking via the Netxx::SockOpt class.
167 *
168 * @param buffer The buffer to store the read bytes into.
169 * @param length The size of the given buffer.
170 * @return Greater than 0: The number of bytes read from the peer and placed into your buffer.
171 * @return 0: The peer closed the connection.
172 * @return -1: A timeout occured.
173 * @see Netxx::SockOpt
174 * @author Peter Jones
175 **/
176 //####################################################################
177 signed_size_type read (void *buffer, size_type length);
178
179 //####################################################################
180 /**
181 * Write data from the given buffer to the connected peer. If an error
182 * occures this function will throw an exception. If a timeout occures
183 * (only if you set a timeout) then -1 is returned.
184 *
185 * It is possible for this function to return -1 if you did not set a
186 * timeout. This would happen if you had set the socket for this
187 * connection to non-blocking via the Netxx::SockOpt class.
188 *
189 * @param buffer The buffer to take the data from and send to the peer.
190 * @param length The amount of data to use from the buffer.
191 * @return Greater than 0: The number of bytes that were sent to the peer.
192 * @return 0: The peer closed the connection.
193 * @return -1: A timeout occured.
194 * @see Netxx::SockOpt
195 * @author Peter Jones
196 **/
197 //####################################################################
198 signed_size_type write (const void *buffer, size_type length);
199
200 //####################################################################
201 /**
202 * Close the connection to the peer. Once the connection is closed you
203 * should not preform any other operations on this object. This function
204 * is normally called from the destructor.
205 *
206 * @author Peter Jones
207 **/
208 //####################################################################
209 void close (void);
210
211 //####################################################################
212 /**
213 * Return the socket file descriptor used for the peer connection. This
214 * is useful for calls to the Netxx::SockOpt class, as well as others.
215 *
216 * @return The socket file descriptor being used by this object.
217 * @author Peter Jones
218 **/
219 //####################################################################
220 socket_type get_socketfd (void) const;
221
222 //####################################################################
223 /**
224 * Get information about how this Stream should be probed from the
225 * Netxx::Probe class.
226 *
227 * @return A Netxx::ProbeInfo object.
228 * @author Peter Jones
229 **/
230 //####################################################################
231 const ProbeInfo* get_probe_info (void) const;
232
233private:
234 struct pimpl; pimpl *pimpl_;
235
236}; // end Netxx::Stream class
237} // end Netxx namespace
238#endif

Archive Download this file

Branches

Tags

Quick Links:     www.monotone.ca    -     Downloads    -     Documentation    -     Wiki    -     Code Forge    -     Build Status