monotone

monotone Mtn Source Tree

Root/netxx/datagramserver.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::DatagramServer class.
35**/
36
37#ifndef _netxx_datagramserver_h_
38#define _netxx_datagramserver_h_
39
40// Netxx includes
41#include <netxx/types.h>
42#include <netxx/timeout.h>
43#include <netxx/address.h>
44#include <netxx/peer.h>
45
46// standard includes
47#include <utility>
48
49namespace Netxx {
50
51 // forward declarations
52 class ProbeInfo;
53 class ServerBase;
54
55/**
56 * The Netxx::DatagramServer class is used for datagram based servers.
57**/
58class DatagramServer {
59public:
60 /// type returned from receive_datagram
61 typedef std::pair<signed_size_type, Peer> receive_type;
62
63 //####################################################################
64 /**
65 * Create a datagram server that will bind to all local addresses on the
66 * given port number. The timeout will be used when you make a call to
67 * receive_datagram.
68 *
69 * @param port The local port number to bind to.
70 * @param timeout The timeout to use for server operations.
71 * @author Peter Jones
72 **/
73 //####################################################################
74 explicit DatagramServer (port_type port, const Timeout &timeout=Timeout());
75
76 //####################################################################
77 /**
78 * Create a datagram server that will bind to all addresses given in the
79 * Address class.
80 *
81 * @param addr The list of addresses to bind to.
82 * @param timeout The timeout to use for server operations.
83 * @author Peter Jones
84 **/
85 //####################################################################
86 explicit DatagramServer (const Address &addr, const Timeout &timeout=Timeout());
87
88 //####################################################################
89 /**
90 * Clean up after the DatagramServer.
91 *
92 * @author Peter Jones
93 **/
94 //####################################################################
95 ~DatagramServer (void);
96
97 //####################################################################
98 /**
99 * Try to receive an incoming datagram. If you have set a timeout and no
100 * datagram is pending within that timeout this memeber function will
101 * return with -1 for the bytes read and an invalid Peer class. If no
102 * timeout was given, this function will block until a datagram arives.
103 * Once a datagram has been received it will be stored inside the given
104 * buffer and the amount of stored data along with data about the sender
105 * of the datagram will returned in a std::pair.
106 *
107 * @param buffer The buffer where the datagram data can be placed.
108 * @param length The size of the buffer.
109 * @return A std::pair where first is the bytes placed in the buffer and
110 * second is the Peer class for the sending peer.
111 * @author Peter Jones
112 **/
113 //####################################################################
114 receive_type receive (void *buffer, size_type length);
115
116 //####################################################################
117 /**
118 * Send a datagram to the given peer. The send will occur using the
119 * datagram server socket. This may not be thread safe. Some protocols
120 * will send a datagram to the client using the server socket with
121 * information about another port to start talking on. It is up to the
122 * developer to decide which approach is better, to respond using the
123 * server datagram socket or create a new datagram server or client for
124 * the communication.
125 *
126 * Using the same DatagramServer object in multiple threads of execution
127 * and then calling the send() member function will probably cause you
128 * problems and a debugging nightmare.
129 *
130 * @param peer The peer to send the datagram to.
131 * @param buffer The buffer that contains the datagram to send.
132 * @param length The size of the datagram to send.
133 * @return The number of bytes sent or -1 in the case of a timeout.
134 **/
135 //####################################################################
136 signed_size_type send (const Peer &peer, const void *buffer, size_type length);
137
138 //####################################################################
139 /**
140 * Get information about how this DatagramServer should be probed from
141 * the Netxx::Probe class.
142 *
143 * @return A Netxx::ProbeInfo object.
144 * @author Peter Jones
145 **/
146 //####################################################################
147 const ProbeInfo* get_probe_info (void) const;
148
149 friend bool operator== (const DatagramServer &ds, socket_type fd);
150 friend bool operator== (socket_type fd, const DatagramServer &ds);
151 friend bool operator!= (const DatagramServer &ds, socket_type fd);
152 friend bool operator!= (socket_type fd, const DatagramServer &ds);
153
154private:
155 ServerBase *pimpl_;
156 DatagramServer (const DatagramServer&);
157 DatagramServer& operator= (const DatagramServer&);
158
159}; // end Netxx::DatagramServer class
160} // end Netxx namespace
161#endif

Archive Download this file

Branches

Tags

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