monotone

monotone Mtn Source Tree

Root/netxx/datagram.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::Datagram class.
35**/
36
37#ifndef _netxx_datagram_h_
38#define _netxx_datagram_h_
39
40// Netxx includes
41#include <netxx/types.h>
42#include <netxx/address.h>
43#include <netxx/timeout.h>
44
45// standard includes
46#include <string>
47#include <utility>
48
49namespace Netxx {
50
51 // forward declarations
52 class ProbeInfo;
53
54/**
55 * The Netxx::Datagram class is a simple wrapper class for sending
56 * datagrams. It supports both connected and unconnected datagram sockets.
57**/
58class Datagram {
59public:
60 /// the type returned from Datagram::receive()
61 typedef std::pair<signed_size_type, Peer> receive_type;
62
63 //####################################################################
64 /**
65 * Construct a new Netxx::Datagram object. If you use this constructor
66 * you must use the send() and receive() member functions instead of the
67 * read() and write() member functions.
68 *
69 * @param timeout An optional timeout for datagram operations.
70 * @author Peter Jones
71 **/
72 //####################################################################
73 explicit Datagram (const Timeout &timeout=Timeout());
74
75 //####################################################################
76 /**
77 * Construct a new Netxx::Datagram object and connect it to the given
78 * peer. Connected Datagram objects can use the read() and write()
79 * member functions. Any data send or received will be to/from the
80 * connected peer.
81 *
82 * @param connect_to The peer to connect to.
83 * @param timeout An optional timeout for datagram operations.
84 * @author Peter Jones
85 **/
86 //####################################################################
87 explicit Datagram (const Address &connect_to, const Timeout &timeout=Timeout());
88
89 //####################################################################
90 /**
91 * Construct a new Netxx::Datagram object and connect it to the given
92 * peer name and port number. The peer name and port number are given to
93 * the Netxx::Address so please see that documentation for more info.
94 *
95 * Connected Datagram objects can use the read() and write() member
96 * functions. Any data send or received will be to/from the connected
97 * peer.
98 *
99 * @param peer_name The name of the peer to connect to with optional port number.
100 * @param default_port The port to use if none is given in peer_name.
101 * @param timeout An optional timeout to use for datagram operations.
102 * @see Netxx::Address
103 * @author Peter Jones
104 **/
105 //####################################################################
106 Datagram (const char *peer_name, port_type default_port, const Timeout &timeout=Timeout());
107
108 //####################################################################
109 /**
110 * Create a datagram object using an already existing socket file
111 * descriptor. The responsiblity for the socket will be transfered to
112 * the new datagram object. You can remove responsibility by calling the
113 * release() member function.
114 *
115 * @param socketfd The file descriptor for the socket to take ownership of.
116 * @param timeout An optional timeout for datagram operations.
117 * @author Peter Jones
118 **/
119 //####################################################################
120 explicit Datagram (socket_type socketfd, const Timeout &timeout=Timeout());
121
122 //####################################################################
123 /**
124 * Class destructor. Clean up after the datagram by closing the socket
125 * if necessary.
126 *
127 * @author Peter Jones
128 **/
129 //####################################################################
130 ~Datagram (void);
131
132 //####################################################################
133 /**
134 * Send data to a specific peer address. You cannot use this function if
135 * you created the datagram object with the connecting constructor. This
136 * function will throw an exception if there are any errors.
137 *
138 * @param peer The peer to send the data to.
139 * @param buffer The buffer to send to the peer.
140 * @param length The size of the buffer.
141 * @return Greater than or equal to 0: The number of bytes sent to the peer.
142 * @return -1: A timeout occured.
143 * @author Peter Jones
144 **/
145 //####################################################################
146 signed_size_type send (const Peer &peer, const void *buffer, size_type length);
147
148 //####################################################################
149 /**
150 * Receive data from any peer. The peer that sent that data will be
151 * returned in a std::pair. This function will throw an exception if
152 * an error occures. You can only use this function if you did not use
153 * the connecting constructor.
154 *
155 * @param buffer A place to store the incoming datagram message.
156 * @param length The size of the buffer.
157 * @return receive_type.first greater than or equal to 0: The number of bytes that were placed in the buffer.
158 * @return receive_type.first == -1: A timeout occured.
159 * @author Peter Jones
160 **/
161 //####################################################################
162 receive_type receive (void *buffer, size_type length);
163
164 //####################################################################
165 /**
166 * Write data to the connected peer. You can only use this function if
167 * you used the connecting constructor. An exception will be thrown if
168 * an error occures.
169 *
170 * @param buffer The buffer that contains the messeage to send to the peer.
171 * @param length The size of the buffer.
172 * @return Greater than or equal to 0: The number of bytes sent to the peer.
173 * @return -1 A timeout occured.
174 * @author Peter Jones
175 **/
176 //####################################################################
177 signed_size_type write (const void *buffer, size_type length);
178
179 //####################################################################
180 /**
181 * Read data from a connected peer into a buffer. You can only call this
182 * function if you used the connecting constructor. An exception will be
183 * thrown if an error occures.
184 *
185 * @param buffer The place to store the received message from the peer.
186 * @param length The size of the buffer.
187 * @return Greater than or equal to 0:The number of bytes placed in your buffer.
188 * @return -1 A timeout occured.
189 * @author Peter Jones
190 **/
191 //####################################################################
192 signed_size_type read (void *buffer, size_type length);
193
194 //####################################################################
195 /**
196 * Get the file descriptor for the socket this Datagram object is using.
197 *
198 * @return The current socket file descriptor.
199 * @author Peter Jones
200 **/
201 //####################################################################
202 socket_type get_socketfd (void) const;
203
204 //####################################################################
205 /**
206 * Close the socket that the datagram object is using if it is open.
207 * This is normally done by the datagram class destructor.
208 *
209 * @author Peter Jones
210 **/
211 //####################################################################
212 void close (void);
213
214 //####################################################################
215 /**
216 * Release control of the socket file descriptor that is being used.
217 * This will prevent the destructor from closing the socket. Once you
218 * call release you must make sure that some other object takes control
219 * of the file descriptor or it could be leaked.
220 *
221 * @author Peter Jones
222 **/
223 //####################################################################
224 void release (void);
225
226 //####################################################################
227 /**
228 * Get information about how Datagram objects should be used with the
229 * Netxx::Probe class.
230 *
231 * @return A Netxx::ProbeInfo object.
232 * @author Peter Jones
233 **/
234 //####################################################################
235 const ProbeInfo* get_probe_info (void) const;
236
237private:
238 struct pimpl; pimpl *pimpl_;
239 Datagram (const Datagram&);
240 Datagram& operator= (const Datagram&);
241
242}; // end Netxx::Datagram class
243} // end Netxx namespace
244#endif

Archive Download this file

Branches

Tags

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