E-MailRelay
ginterfaces.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file ginterfaces.h
19///
20
21#ifndef G_NET_INTERFACES_H
22#define G_NET_INTERFACES_H
23
24#include "gdef.h"
25#include "gaddress.h"
26#include "gstrings.h"
27#include "gexceptionsink.h"
28#include "geventhandler.h"
29#include "gfutureevent.h"
30#include "gsocket.h"
31#include <string>
32#include <vector>
33
34namespace GNet
35{
36 class Interfaces ;
37 class InterfacesHandler ;
38 class InterfacesNotifier ;
39}
40
41//| \class GNet::Interfaces
42/// A class for getting a list of network interfaces and their addresses.
43///
45{
46public:
47 struct Item /// Used by GNet::Interfaces to describe an interface address binding.
48 {
49 std::string name ;
50 std::string altname ; // windows friendly name, utf8
51 unsigned int address_family{0} ;
52 bool valid_address{false} ;
53 Address address ;
54 bool has_netmask{false} ;
55 unsigned int netmask_bits{0U} ;
56 bool up{false} ;
57 bool loopback{false} ;
58 Item() ;
59 } ;
60 using const_iterator = std::vector<Item>::const_iterator ;
61
63 ///< Default constructor resulting in an empty list.
64 ///< Use load() to initialise.
65
67 ///< Constructor resulting in an empty list with an
68 ///< attached event handler. Use load() or find() to
69 ///< initialise the list and activate the event
70 ///< listener.
71
72 ~Interfaces() override ;
73 ///< Destructor.
74
75 static bool supported() ;
76 ///< Returns false if a stubbed-out implementation.
77
78 static bool active() ;
79 ///< Returns true if the implementation can raise
80 ///< InterfacesHandler events.
81
82 void load() ;
83 ///< Loads or reloads the list.
84
85 bool loaded() const ;
86 ///< Returns true if load()ed.
87
88 G::StringArray names( bool all = false ) const ;
89 ///< Returns the interface names, optionally including
90 ///< interfaces that are not up.
91
92 const_iterator begin() const ;
93 ///< Returns a begin iterator.
94
95 const_iterator end() const ;
96 ///< Returns a one-off-the-end iterator.
97
98 std::vector<Address> find( const std::string & name , unsigned int port ,
99 bool allow_decoration = true ) const ;
100 ///< Finds the named interface and returns its addresses
101 ///< if it is up. If the decoration flag is used and the name
102 ///< is decorated with "-ipv4" or "-ipv6" then only those
103 ///< addresses are returned. The returned addresses all have
104 ///< the given port number. Returns the empty list if not
105 ///< found or if found but not up. Does lazy load()ing.
106
107 std::vector<Address> addresses( const G::StringArray & names , unsigned int port ,
108 G::StringArray & used_names , G::StringArray & empty_names ,
109 G::StringArray & bad_names ) const ;
110 ///< Treats each name given as an address or interface name and
111 ///< returns the total set of addresses. Returns by reference
112 ///< (1) names that are, or have, addresses, (2) names that might
113 ///< be interfaces with no bound addresses, and (3) the remainder,
114 ///< ie. names that are not addresses and cannot be a valid
115 ///< interface name.
116
117private: // overrides
118 void readEvent() override ; // GNet::EventHandler
119 void onFutureEvent() override ; // GNet::FutureEventHandler
120
121public:
122 Interfaces( const Interfaces & ) = delete ;
123 Interfaces( Interfaces && ) = delete ;
124 void operator=( const Interfaces & ) = delete ;
125 void operator=( Interfaces && ) = delete ;
126
127private:
128 using AddressList = std::vector<Address> ;
129 void loadImp( ExceptionSink , std::vector<Item> & list ) ;
130
131private:
132 ExceptionSink m_es ;
133 InterfacesHandler * m_handler{nullptr} ;
134 mutable bool m_loaded{false} ;
135 mutable std::vector<Item> m_list ;
136 std::unique_ptr<InterfacesNotifier> m_notifier ;
137} ;
138
139//| \class GNet::InterfacesHandler
140/// An interface for receiving notification of network changes.
141///
143{
144public:
145 virtual void onInterfaceEvent( const std::string & ) = 0 ;
146 ///< Indicates some network event that might have invalidated
147 ///< the GNet::Interfaces state, requiring a re-load().
148
149 virtual ~InterfacesHandler() = default ;
150 ///< Destructor.
151} ;
152
153//| \class GNet::InterfacesNotifier
154/// A pimple base-class used by GNet::Interfaces.
155///
157{
158public:
159 virtual std::string readEvent() = 0 ;
160 ///< Called by GNet::Interfaces to handle a read event.
161 ///< Returns a diagnostic representation of the event
162 ///< or the empty string.
163
164 virtual std::string onFutureEvent() = 0 ;
165 ///< Called by GNet::Interfaces to handle a future event.
166 ///< Returns a diagnostic representation of the event
167 ///< or the empty string.
168
169 virtual ~InterfacesNotifier() = default ;
170 ///< Destructor.
171} ;
172
173#endif
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:53
A base class for classes that handle asynchronous events from the event loop.
Definition: geventhandler.h:48
A tuple containing an ExceptionHandler interface pointer and a bound 'exception source' pointer.
A callback interface for GNet::FutureEvent.
Definition: gfutureevent.h:113
An interface for receiving notification of network changes.
Definition: ginterfaces.h:143
virtual void onInterfaceEvent(const std::string &)=0
Indicates some network event that might have invalidated the GNet::Interfaces state,...
virtual ~InterfacesHandler()=default
Destructor.
A pimple base-class used by GNet::Interfaces.
Definition: ginterfaces.h:157
virtual std::string readEvent()=0
Called by GNet::Interfaces to handle a read event.
virtual ~InterfacesNotifier()=default
Destructor.
virtual std::string onFutureEvent()=0
Called by GNet::Interfaces to handle a future event.
A class for getting a list of network interfaces and their addresses.
Definition: ginterfaces.h:45
void load()
Loads or reloads the list.
static bool active()
Returns true if the implementation can raise InterfacesHandler events.
Interfaces()
Default constructor resulting in an empty list.
bool loaded() const
Returns true if load()ed.
~Interfaces() override
Destructor.
static bool supported()
Returns false if a stubbed-out implementation.
const_iterator begin() const
Returns a begin iterator.
std::vector< Address > addresses(const G::StringArray &names, unsigned int port, G::StringArray &used_names, G::StringArray &empty_names, G::StringArray &bad_names) const
Treats each name given as an address or interface name and returns the total set of addresses.
const_iterator end() const
Returns a one-off-the-end iterator.
std::vector< Address > find(const std::string &name, unsigned int port, bool allow_decoration=true) const
Finds the named interface and returns its addresses if it is up.
G::StringArray names(bool all=false) const
Returns the interface names, optionally including interfaces that are not up.
Network classes.
Definition: gdef.h:1115
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:31
Used by GNet::Interfaces to describe an interface address binding.
Definition: ginterfaces.h:48