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