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
35namespace 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///
48{
49public:
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
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
110private: // overrides
111 void readEvent() override ; // GNet::EventHandler
112 void onFutureEvent() override ; // GNet::FutureEventHandler
113
114public:
115 Interfaces( const Interfaces & ) = delete ;
116 Interfaces( Interfaces && ) = delete ;
117 Interfaces operator=( const Interfaces & ) = delete ;
118 Interfaces operator=( Interfaces && ) = delete ;
119
120private:
121 using AddressList = std::vector<Address> ;
122 void loadImp( EventState , std::vector<Item> & list ) ;
123 static int index( const std::string & ) ;
124
125private:
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///
137{
138public:
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///
151{
152public:
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
The GNet::Address class encapsulates a TCP/UDP transport address.
Definition: gaddress.h:63
A base class for classes that have a file descriptor and handle asynchronous events from the event lo...
Definition: geventhandler.h:48
A lightweight object containing an ExceptionHandler pointer, optional ExceptionSource pointer and opt...
Definition: geventstate.h:131
A callback interface for GNet::FutureEvent.
Definition: gfutureevent.h:126
An interface for receiving notification of network changes.
Definition: ginterfaces.h:137
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:151
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:48
Interfaces(EventState)
Constructor resulting in an empty list.
std::vector< Address > addresses(const std::string &name, unsigned int port, int af=AF_UNSPEC) const
Returns addresses bound to the given interface.
void load()
Loads or reloads the list.
static bool active()
Returns true if the implementation can raise InterfacesHandler events.
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.
const_iterator end() const
Returns a one-off-the-end iterator.
G::StringArray names(bool all=false) const
Returns the interface names, optionally including interfaces that are not up.
Network classes.
Definition: gdef.h:1243
std::vector< std::string > StringArray
A std::vector of std::strings.
Definition: gstringarray.h:30
Used by GNet::Interfaces to describe an interface address binding.
Definition: ginterfaces.h:51