1 /* Copyright (c) 2014, 2021, Oracle and/or its affiliates.
2 
3    This program is free software; you can redistribute it and/or modify
4    it under the terms of the GNU General Public License, version 2.0,
5    as published by the Free Software Foundation.
6 
7    This program is also distributed with certain software (including
8    but not limited to OpenSSL) that is licensed under separate terms,
9    as designated in a particular file or component or in included license
10    documentation.  The authors of MySQL hereby grant you an additional
11    permission to link the program and your derivative works with the
12    separately licensed software that they have included with MySQL.
13 
14    This program is distributed in the hope that it will be useful,
15    but WITHOUT ANY WARRANTY; without even the implied warranty of
16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17    GNU General Public License, version 2.0, for more details.
18 
19    You should have received a copy of the GNU General Public License
20    along with this program; if not, write to the Free Software
21    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA */
22 
23 #ifndef GCS_COMMUNICATION_INTERFACE_INCLUDED
24 #define GCS_COMMUNICATION_INTERFACE_INCLUDED
25 
26 #include "gcs_communication_event_listener.h"
27 #include "gcs_message.h"
28 
29 /**
30   @class Gcs_communication_interface
31 
32   This interface represents all the communication facilities that a binding
33   implementation should provide. Like all interfaces in this API, it is
34   group-oriented, meaning that a single instance shall exist per group,
35   as it was returned by the class Gcs_interface::get_communication_session.
36 
37   It has two major subsections:
38   - Message sending: represented by the method send_message, it will
39     broadcast a message to the group in which this interface is bound.
40     All message data is encapsulated in the Gcs_message object that
41     contains more detail about the information to be sent.
42     Guarantees are bound to the binding implementation. This means that the
43     implementation shall send message of this message and shall not be
44     maintained between different groups.
45 
46   - Message receiving: Due to the asynchronous nature of this interface,
47     message reception is done via an event. They shall be delivered in
48     form of callbacks defined in Gcs_communication_event_listener class,
49     that should be implemented by a client of this interface interested
50     in receiving those notifications.
51 
52   A typical usage for this interface would be:
53 
54   @code{.cpp}
55   class my_Gcs_communication_event_listener: Gcs_communication_event_listener
56   {
57     void on_message_received(const Gcs_message &message)
58     {
59       //Do something when message arrives...
60     }
61   }
62 
63   //meanwhile in your client code...
64   Gcs_communication_interface *gcs_comm_interface_instance; // obtained
65                                                             // previously
66 
67   Gcs_communication_event_listener listener_instance;
68 
69   int ref_handler=
70     gcs_comm_interface_instance->add_event_listener(listener_instance);
71 
72   Gcs_message *msg= new Gcs_message(<message_params>);
73 
74   gcs_comm_interface_instance->send_message(msg);
75 
76   //Normal program flow...
77 
78   //In the end...
79   gcs_comm_interface_instance->remove_event_listener(ref_handler);
80 
81   @endcode
82 
83 */
84 class Gcs_communication_interface
85 {
86 public:
87   /**
88     Method used to broadcast a message to a group in which this interface
89     pertains.
90 
91     Note that one must belong to an active group to send messages.
92 
93     @param[in] message_to_send the Gcs_message object to send
94     @return A gcs_error value
95       @retval GCS_OK When message is transmitted successfully
96       @retval GCS_ERROR When error occurred while transmitting message
97       @retval GCS_MESSAGE_TOO_BIG When message is bigger than
98                                   the GCS can handle
99   */
100 
101   virtual enum_gcs_error send_message(const Gcs_message &message_to_send)= 0;
102 
103 
104   /**
105     Registers an implementation of a Gcs_communication_event_listener that will
106     receive Communication Events.
107 
108     Note that a binding implementation shall not offer the possibility of
109     changing listeners while the system is up and running. In that sense,
110     listeners must be added to it only when booting up the system.
111 
112     @param[in] event_listener a class that implements
113                               Gcs_communication_event_listener
114     @return an handle representing the registration of this object to
115             be used in remove_event_listener
116   */
117 
118   virtual int
119   add_event_listener(const Gcs_communication_event_listener &event_listener)= 0;
120 
121 
122   /**
123     Removes a previously registered event listener.
124 
125     Note that a binding implementation shall not offer the possibility of
126     changing listeners while the system is up and running. In that sense
127     listeners must be removed from it only when shutting down the system.
128 
129     @param[in] event_listener_handle the handle returned when the listener was
130                                  registered
131   */
132 
133   virtual void remove_event_listener(int event_listener_handle)= 0;
134 
135 
~Gcs_communication_interface()136   virtual ~Gcs_communication_interface() {}
137 };
138 
139 #endif // GCS_COMMUNICATION_INTERFACE_H
140