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
34 namespace 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///
44 class GNet::Interfaces : public EventHandler , public FutureEventHandler
45{
46 public:
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
62 Interfaces() ;
63 ///< Default constructor resulting in an empty list.
64 ///< Use load() to initialise.
65
66 Interfaces( ExceptionSink , InterfacesHandler & ) ;
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
117 private: // overrides
118 void readEvent() override ; // GNet::EventHandler
119 void onFutureEvent() override ; // GNet::FutureEventHandler
120
121 public:
122 Interfaces( const Interfaces & ) = delete ;
123 Interfaces( Interfaces && ) = delete ;
124 void operator=( const Interfaces & ) = delete ;
125 void operator=( Interfaces && ) = delete ;
126
127 private:
128 using AddressList = std::vector<Address> ;
129 void loadImp( ExceptionSink , std::vector<Item> & list ) ;
130
131 private:
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///
142 class GNet::InterfacesHandler
143{
144 public:
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///
156 class GNet::InterfacesNotifier
157{
158 public:
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
GNet::Address
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:53
GNet::EventHandler
A base class for classes that handle asynchronous events from the event loop.
Definition: geventhandler.h:48
GNet::ExceptionSink
A tuple containing an ExceptionHandler interface pointer and a bound 'exception source' pointer.
Definition: gexceptionsink.h:100
GNet::FutureEventHandler
A callback interface for GNet::FutureEvent.
Definition: gfutureevent.h:113
GNet::InterfacesHandler
An interface for receiving notification of network changes.
Definition: ginterfaces.h:143
GNet::InterfacesHandler::onInterfaceEvent
virtual void onInterfaceEvent(const std::string &)=0
Indicates some network event that might have invalidated the GNet::Interfaces state,...
GNet::InterfacesHandler::~InterfacesHandler
virtual ~InterfacesHandler()=default
Destructor.
GNet::InterfacesNotifier
A pimple base-class used by GNet::Interfaces.
Definition: ginterfaces.h:157
GNet::InterfacesNotifier::readEvent
virtual std::string readEvent()=0
Called by GNet::Interfaces to handle a read event.
GNet::InterfacesNotifier::~InterfacesNotifier
virtual ~InterfacesNotifier()=default
Destructor.
GNet::InterfacesNotifier::onFutureEvent
virtual std::string onFutureEvent()=0
Called by GNet::Interfaces to handle a future event.
GNet::Interfaces
A class for getting a list of network interfaces and their addresses.
Definition: ginterfaces.h:45
GNet::Interfaces::load
void load()
Loads or reloads the list.
Definition: ginterfaces_common.cpp:39
GNet::Interfaces::active
static bool active()
Returns true if the implementation can raise InterfacesHandler events.
Definition: ginterfaces_unix.cpp:72
GNet::Interfaces::Interfaces
Interfaces()
Default constructor resulting in an empty list.
GNet::Interfaces::loaded
bool loaded() const
Returns true if load()ed.
Definition: ginterfaces_common.cpp:53
GNet::Interfaces::~Interfaces
~Interfaces() override
Destructor.
GNet::Interfaces::supported
static bool supported()
Returns false if a stubbed-out implementation.
Definition: ginterfaces_common.cpp:48
GNet::Interfaces::begin
const_iterator begin() const
Returns a begin iterator.
Definition: ginterfaces_common.cpp:147
GNet::Interfaces::addresses
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.
Definition: ginterfaces_common.cpp:100
GNet::Interfaces::end
const_iterator end() const
Returns a one-off-the-end iterator.
Definition: ginterfaces_common.cpp:152
GNet::Interfaces::find
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.
Definition: ginterfaces_common.cpp:58
GNet::Interfaces::names
G::StringArray names(bool all=false) const
Returns the interface names, optionally including interfaces that are not up.
Definition: ginterfaces_common.cpp:134
gaddress.h
geventhandler.h
gexceptionsink.h
gfutureevent.h
gsocket.h
gstrings.h
GNet
Network classes.
Definition: gdef.h:1115
G::StringArray
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstrings.h:31
GNet::Interfaces::Item
Used by GNet::Interfaces to describe an interface address binding.
Definition: ginterfaces.h:48