E-MailRelay

ginterfaces.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 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 "gstringarray.h"
27#include "geventstate.h"
28#include "geventhandler.h"
29#include "gfutureevent.h"
30#include "gsocket.h"
31#include <string>
32#include <memory>
33#include <vector>
34
35 namespace GNet
36{
37 class Interfaces ;
38 class InterfacesHandler ;
39 class InterfacesNotifier ;
40}
41
42//| \class GNet::Interfaces
43/// A class for getting a list of network interfaces and their addresses.
44/// An InterfacesHandler interface can be supplied to the constructor
45/// in order to get dynamic updates.
46///
47 class GNet::Interfaces : public EventHandler , public FutureEventHandler
48{
49 public:
50 struct Item /// Used by GNet::Interfaces to describe an interface address binding.
51 {
52 std::string name ; // interface name
53 std::string altname ; // windows friendly name, utf8
54 int ifindex {0} ; // interface 1-based index, 0 on error, family-specific on windows
55 unsigned int address_family {0} ;
56 bool valid_address {false} ;
57 Address address ;
58 bool has_netmask {false} ;
59 unsigned int netmask_bits {0U} ;
60 bool up {false} ;
61 bool loopback {false} ;
62 Item() ;
63 } ;
64 using const_iterator = std::vector<Item>::const_iterator ;
65
66 explicit Interfaces( EventState ) ;
67 ///< Constructor resulting in an empty list.
68 ///< Use load() to initialise.
69
70 Interfaces( EventState , InterfacesHandler & ) ;
71 ///< Constructor resulting in an empty list with an
72 ///< attached event handler. Use load() or addresses() to
73 ///< initialise the list and activate the event
74 ///< listener.
75
76 ~Interfaces() override ;
77 ///< Destructor.
78
79 static bool supported() ;
80 ///< Returns false if a stubbed-out implementation.
81
82 static bool active() ;
83 ///< Returns true if the implementation can raise
84 ///< InterfacesHandler events.
85
86 void load() ;
87 ///< Loads or reloads the list.
88
89 bool loaded() const ;
90 ///< Returns true if load()ed.
91
92 G::StringArray names( bool all = false ) const ;
93 ///< Returns the interface names, optionally including
94 ///< interfaces that are not up.
95
96 const_iterator begin() const ;
97 ///< Returns a begin iterator.
98
99 const_iterator end() const ;
100 ///< Returns a one-off-the-end iterator.
101
102 std::vector<Address> addresses( const std::string & name , unsigned int port , int af = AF_UNSPEC ) const ;
103 ///< Returns addresses bound to the given interface.
104 ///< Does a lazy load().
105
106 std::size_t addresses( std::vector<Address> & out , const std::string & name , unsigned int port , int af = AF_UNSPEC ) const ;
107 ///< An overload that appends to the given list and returns
108 ///< the number added.
109
110 private: // overrides
111 void readEvent() override ; // GNet::EventHandler
112 void onFutureEvent() override ; // GNet::FutureEventHandler
113
114 public:
115 Interfaces( const Interfaces & ) = delete ;
116 Interfaces( Interfaces && ) = delete ;
117 Interfaces operator=( const Interfaces & ) = delete ;
118 Interfaces operator=( Interfaces && ) = delete ;
119
120 private:
121 using AddressList = std::vector<Address> ;
122 void loadImp( EventState , std::vector<Item> & list ) ;
123 static int index( const std::string & ) ;
124
125 private:
126 EventState m_es ;
127 InterfacesHandler * m_handler{nullptr} ;
128 mutable bool m_loaded{false} ;
129 mutable std::vector<Item> m_list ;
130 std::unique_ptr<InterfacesNotifier> m_notifier ;
131} ;
132
133//| \class GNet::InterfacesHandler
134/// An interface for receiving notification of network changes.
135///
136 class GNet::InterfacesHandler
137{
138 public:
139 virtual void onInterfaceEvent( const std::string & ) = 0 ;
140 ///< Indicates some network event that might have invalidated
141 ///< the GNet::Interfaces state, requiring a re-load().
142
143 virtual ~InterfacesHandler() = default ;
144 ///< Destructor.
145} ;
146
147//| \class GNet::InterfacesNotifier
148/// A pimple base-class used by GNet::Interfaces.
149///
150 class GNet::InterfacesNotifier
151{
152 public:
153 virtual std::string readEvent() = 0 ;
154 ///< Called by GNet::Interfaces to handle a read event.
155 ///< Returns a diagnostic representation of the event
156 ///< or the empty string.
157
158 virtual std::string onFutureEvent() = 0 ;
159 ///< Called by GNet::Interfaces to handle a future event.
160 ///< Returns a diagnostic representation of the event
161 ///< or the empty string.
162
163 virtual ~InterfacesNotifier() = default ;
164 ///< Destructor.
165} ;
166
167#endif
GNet::Address
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:63
GNet::EventHandler
A base class for classes that have a file descriptor and handle asynchronous events from the event lo...
Definition: geventhandler.h:48
GNet::EventState
A lightweight object containing an ExceptionHandler pointer, optional ExceptionSource pointer and opt...
Definition: geventstate.h:131
GNet::FutureEventHandler
A callback interface for GNet::FutureEvent.
Definition: gfutureevent.h:126
GNet::InterfacesHandler
An interface for receiving notification of network changes.
Definition: ginterfaces.h:137
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:151
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:48
GNet::Interfaces::Interfaces
Interfaces(EventState)
Constructor resulting in an empty list.
Definition: ginterfaces_common.cpp:28
GNet::Interfaces::addresses
std::vector< Address > addresses(const std::string &name, unsigned int port, int af=AF_UNSPEC) const
Returns addresses bound to the given interface.
Definition: ginterfaces_common.cpp:65
GNet::Interfaces::load
void load()
Loads or reloads the list.
Definition: ginterfaces_common.cpp:43
GNet::Interfaces::active
static bool active()
Returns true if the implementation can raise InterfacesHandler events.
Definition: ginterfaces_none.cpp:44
GNet::Interfaces::loaded
bool loaded() const
Returns true if load()ed.
Definition: ginterfaces_common.cpp:59
GNet::Interfaces::~Interfaces
~Interfaces() override
Destructor.
GNet::Interfaces::supported
static bool supported()
Returns false if a stubbed-out implementation.
Definition: ginterfaces_common.cpp:53
GNet::Interfaces::begin
const_iterator begin() const
Returns a begin iterator.
Definition: ginterfaces_common.cpp:111
GNet::Interfaces::end
const_iterator end() const
Returns a one-off-the-end iterator.
Definition: ginterfaces_common.cpp:116
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:97
gaddress.h
geventhandler.h
geventstate.h
gfutureevent.h
gsocket.h
gstringarray.h
GNet
Network classes.
Definition: gdef.h:1243
G::StringArray
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstringarray.h:30
GNet::Interfaces::Item
Used by GNet::Interfaces to describe an interface address binding.
Definition: ginterfaces.h:51