1 // Copyright Maciej Sobczak 2008-2019. 2 // This file is part of YAMI4. 3 // 4 // YAMI4 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 // YAMI4 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 YAMI4. If not, see <http://www.gnu.org/licenses/>. 16 17 #ifndef YAMICORE_CORE_H_INCLUDED 18 #define YAMICORE_CORE_H_INCLUDED 19 20 #include "channel_descriptor.h" 21 #include <cstddef> 22 23 /// Namespace devoted for everything related to YAMI4. 24 namespace yami 25 { 26 27 /// Namespace defining the YAMI4-core communication module. 28 namespace core 29 { 30 31 /// General type for reporting success and error states. 32 enum result 33 { 34 ok, ///< Operation completed successfully. 35 no_such_name, ///< The given name was not found. 36 bad_type, ///< The expected type is different than the actual. 37 no_such_index, ///< Index out of range. 38 no_memory, ///< Not enough memory. 39 nesting_too_deep, ///< The nesting of parameters is too deep. 40 not_enough_space, ///< There is not enough space in the buffer. 41 no_entries, ///< There are no entries. 42 unexpected_value, ///< The given value was not recognized. 43 bad_protocol, ///< The connection protocol is incorrect. 44 io_error, ///< Unable to perform the I/O operation. 45 timed_out, ///< The requested operation timed out. 46 channel_closed, ///< The operation was not possible due to EOF. 47 bad_state ///< The given object is in the wrong state. 48 }; 49 50 /// Type of function callback for incoming message dispatch. 51 /// @param hint Arbitrary (any) argument provided at the time 52 /// when the callback was installed. 53 /// @param source Name of the originating channel. 54 /// @param header_buffers Array of pointers to data buffers that can be used 55 /// to deserialize the message header. 56 /// @param header_buffer_sizes Array of sizes of header data buffers. 57 /// @param num_of_header_buffers Number of elements in the 58 /// <code>header_buffers</code> and <code>header_buffer_sizes</code> 59 /// arrays. 60 /// @param body_buffers Array of pointers to data buffers that can be used 61 /// to deserialize the message body. 62 /// @param body_buffer_sizes Array of sizes of body data buffers. 63 /// @param num_of_body_buffers Number of elements in the 64 /// <code>body_buffers</code> and <code>body_buffer_sizes</code> 65 /// arrays. 66 /// 67 /// <b>Note</b>: The arguments to this callback can be directly used with 68 /// the <code>deserialize</code> function of the <code>parameters</code> 69 /// class. 70 extern "C" typedef void (*incoming_message_dispatch_function)( 71 void * hint, 72 const char * source, 73 const char * header_buffers[], 74 std::size_t header_buffer_sizes[], 75 std::size_t num_of_header_buffers, 76 const char * body_buffers[], 77 std::size_t body_buffer_sizes[], 78 std::size_t num_of_body_buffers); 79 80 /// Type of function callback (hook) for new incoming connection. 81 /// This function sees the new channel already in the proper state 82 /// and can use it (in particular it can close it). 83 /// @param hint Arbitrary (any) argument provided at the time 84 /// when the callback was installed. 85 /// @param source The source (remote) name of the newly created channel. 86 /// @param index Index for the channel descriptor. 87 /// @param sequence_number Sequence number for the channel descriptor. 88 /// @return <code>true</code> if the connection is accepted and 89 /// <code>false</code> otherwise. 90 extern "C" typedef void (*new_incoming_connection_function)( 91 void * hint, 92 const char * source, 93 std::size_t index, std::size_t sequence_number); 94 95 /// Type of function callback (hook) for closing connection. 96 /// @param hint Arbitrary (any) argument provided at the time 97 /// when the callback was installed. 98 /// @param name The name of the closing channel. 99 /// @param reason The reason for closing the connection, this is either 100 /// <code>channel_closed</code> for regular end-of-stream condition 101 /// or an appropriate error value that was reported while operating 102 /// on the given channel. 103 extern "C" typedef void (*closed_connection_function)( 104 void * hint, 105 const char * name, result reason); 106 107 /// Type of function callback for outgoing message progress report. 108 /// If both size values are zero, it means that there was an 109 /// error while sending the message - 110 /// the message itself will be abandoned and channel will be closed. 111 /// @param hint Arbitrary (any) argument provided at the time 112 /// when the callback was installed. 113 /// @param sent_bytes The number of bytes accumulated from the beginning 114 /// of the message that have been sent. 115 /// @param total_byte_count The overall size of the message. 116 /// 117 /// <b>Note</b>: When <code>sent_bytes</code> and 118 /// <code>total_byte_count</code> are equal it means that the whole message 119 /// has been sent; if they are both zero it indicates that there was an error 120 /// and the message was abandoned. 121 extern "C" typedef void (*message_progress_function)( 122 void * hint, 123 std::size_t sent_bytes, 124 std::size_t total_byte_count); 125 126 /// Type of internal event notification. 127 enum event_notification 128 { 129 agent_closed, // (NULL, 0) 130 listener_added, // (target, 0) 131 listener_removed, // (target, 0) 132 incoming_connection_open, // (target, 0) 133 outgoing_connection_open, // (target, 0) 134 connection_closed, // (target, 0) 135 connection_error, // (target, 0) 136 message_sent, // (target, bytes) 137 message_received // (target, bytes) 138 }; 139 140 /// Type of function callback for internal event notifications (logging). 141 /// Depending on the event type, some callback parameters are used. 142 extern "C" typedef void (*event_notification_function)( 143 void * hint, 144 event_notification e, 145 const char * str, 146 std::size_t size); 147 148 /// Type of function callback for internal I/O error logging. 149 extern "C" typedef void (*io_error_function)( 150 void * hint, 151 int error_code, 152 const char * description); 153 154 } // namespace core 155 156 } // namespace yami 157 158 #endif // YAMICORE_CORE_H_INCLUDED 159