gnunet_chat_handle.h (12290B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2021--2025 GNUnet e.V. 4 5 GNUnet is free software: you can redistribute it and/or modify it 6 under the terms of the GNU Affero General Public License as published 7 by the Free Software Foundation, either version 3 of the License, 8 or (at your option) any later version. 9 10 GNUnet is distributed in the hope that it will be useful, but 11 WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Affero General Public License for more details. 14 15 You should have received a copy of the GNU Affero General Public License 16 along with this program. If not, see <http://www.gnu.org/licenses/>. 17 18 SPDX-License-Identifier: AGPL3.0-or-later 19 */ 20 /* 21 * @author Tobias Frisch 22 * @file gnunet_chat_handle.h 23 */ 24 25 #ifndef GNUNET_CHAT_HANDLE_H_ 26 #define GNUNET_CHAT_HANDLE_H_ 27 28 #include "gnunet_chat_lib.h" 29 #include "gnunet_chat_account.h" 30 #include "gnunet_chat_contact.h" 31 #include "gnunet_chat_lobby.h" 32 #include "gnunet_chat_message.h" 33 #include "gnunet_chat_uri.h" 34 35 #include "internal/gnunet_chat_accounts.h" 36 #include "internal/gnunet_chat_attribute_process.h" 37 #include "internal/gnunet_chat_ticket_process.h" 38 39 #include <gnunet/gnunet_common.h> 40 #include <gnunet/gnunet_arm_service.h> 41 #include <gnunet/gnunet_fs_service.h> 42 #include <gnunet/gnunet_gns_service.h> 43 #include <gnunet/gnunet_identity_service.h> 44 #include <gnunet/gnunet_messenger_service.h> 45 #include <gnunet/gnunet_namestore_service.h> 46 #include <gnunet/gnunet_reclaim_lib.h> 47 #include <gnunet/gnunet_reclaim_service.h> 48 #include <gnunet/gnunet_time_lib.h> 49 #include <gnunet/gnunet_util_lib.h> 50 51 struct GNUNET_CHAT_Handle; 52 53 struct GNUNET_CHAT_InternalServices 54 { 55 struct GNUNET_CHAT_Handle *chat; 56 struct GNUNET_ARM_Operation *op; 57 struct GNUNET_CHAT_InternalServices *next; 58 struct GNUNET_CHAT_InternalServices *prev; 59 }; 60 61 struct GNUNET_CHAT_InternalMessages 62 { 63 struct GNUNET_CHAT_Handle *chat; 64 struct GNUNET_CHAT_Message *msg; 65 struct GNUNET_SCHEDULER_Task *task; 66 struct GNUNET_CHAT_InternalMessages *next; 67 struct GNUNET_CHAT_InternalMessages *prev; 68 }; 69 70 struct GNUNET_CHAT_InternalLobbies 71 { 72 struct GNUNET_CHAT_Lobby *lobby; 73 struct GNUNET_CHAT_InternalLobbies *next; 74 struct GNUNET_CHAT_InternalLobbies *prev; 75 }; 76 77 struct GNUNET_CHAT_UriLookups 78 { 79 struct GNUNET_CHAT_Handle *handle; 80 81 struct GNUNET_GNS_LookupRequest *request; 82 struct GNUNET_CHAT_Uri *uri; 83 84 struct GNUNET_CHAT_UriLookups *next; 85 struct GNUNET_CHAT_UriLookups *prev; 86 }; 87 88 struct GNUNET_CHAT_Handle 89 { 90 const struct GNUNET_CONFIGURATION_Handle* cfg; 91 struct GNUNET_SCHEDULER_Task *shutdown_hook; 92 struct GNUNET_SCHEDULER_Task *destruction; 93 struct GNUNET_SCHEDULER_Task *connection; 94 struct GNUNET_SCHEDULER_Task *refresh; 95 96 struct GNUNET_CHAT_InternalServices *services_head; 97 struct GNUNET_CHAT_InternalServices *services_tail; 98 99 struct GNUNET_CHAT_InternalMessages *internal_head; 100 struct GNUNET_CHAT_InternalMessages *internal_tail; 101 102 char *directory; 103 104 GNUNET_CHAT_ContextMessageCallback msg_cb; 105 void *msg_cls; 106 107 struct GNUNET_CHAT_InternalAccounts *accounts_head; 108 struct GNUNET_CHAT_InternalAccounts *accounts_tail; 109 110 enum GNUNET_GenericReturnValue refreshing; 111 struct GNUNET_CHAT_Contact *own_contact; 112 113 struct GNUNET_CHAT_Account *next; 114 struct GNUNET_CHAT_Account *current; 115 struct GNUNET_NAMESTORE_ZoneMonitor *monitor; 116 117 struct GNUNET_CHAT_InternalLobbies *lobbies_head; 118 struct GNUNET_CHAT_InternalLobbies *lobbies_tail; 119 120 struct GNUNET_CHAT_UriLookups *lookups_head; 121 struct GNUNET_CHAT_UriLookups *lookups_tail; 122 123 struct GNUNET_CHAT_AttributeProcess *attributes_head; 124 struct GNUNET_CHAT_AttributeProcess *attributes_tail; 125 126 struct GNUNET_CHAT_TicketProcess *tickets_head; 127 struct GNUNET_CHAT_TicketProcess *tickets_tail; 128 129 struct GNUNET_CONTAINER_MultiHashMap *files; 130 struct GNUNET_CONTAINER_MultiHashMap *contexts; 131 struct GNUNET_CONTAINER_MultiShortmap *contacts; 132 struct GNUNET_CONTAINER_MultiHashMap *groups; 133 struct GNUNET_CONTAINER_MultiHashMap *invitations; 134 135 struct GNUNET_ARM_Handle *arm; 136 struct GNUNET_FS_Handle *fs; 137 struct GNUNET_GNS_Handle *gns; 138 struct GNUNET_IDENTITY_Handle *identity; 139 struct GNUNET_MESSENGER_Handle *messenger; 140 struct GNUNET_NAMESTORE_Handle *namestore; 141 struct GNUNET_RECLAIM_Handle *reclaim; 142 143 char *public_key; 144 void *user_pointer; 145 }; 146 147 /** 148 * Creates a chat handle with a selected configuration, 149 * a custom message callback and a custom closure for 150 * the callback. 151 * 152 * @param[in] cfg Configuration 153 * @param[in] msg_cb Message callback 154 * @param[in,out] msg_cls Closure 155 * @return New chat handle 156 */ 157 struct GNUNET_CHAT_Handle* 158 handle_create_from_config (const struct GNUNET_CONFIGURATION_Handle* cfg, 159 GNUNET_CHAT_ContextMessageCallback msg_cb, 160 void *msg_cls); 161 162 /** 163 * Updates the string representation of the public key from 164 * a given chat <i>handle</i>. 165 * 166 * @param[in,out] handle Chat handle 167 */ 168 void 169 handle_update_key (struct GNUNET_CHAT_Handle *handle); 170 171 /** 172 * Destroys a chat <i>handle</i> and frees its memory. 173 * 174 * @param[in,out] handle Chat handle 175 */ 176 void 177 handle_destroy (struct GNUNET_CHAT_Handle *handle); 178 179 /** 180 * Connects a given chat <i>handle</i> to a selected 181 * chat <i>account</i> using it for further operations. 182 * 183 * @param[in,out] handle Chat handle 184 * @param[in] account Chat account 185 */ 186 void 187 handle_connect (struct GNUNET_CHAT_Handle *handle, 188 struct GNUNET_CHAT_Account *account); 189 190 /** 191 * Disconnects a given chat <i>handle</i> from its current 192 * connected chat account. 193 * 194 * @param[in,out] handle Chat handle 195 */ 196 void 197 handle_disconnect (struct GNUNET_CHAT_Handle *handle); 198 199 /** 200 * Searches for an existing chat account by <i>name</i> as 201 * identifier for a given chat <i>handle</i>. 202 * 203 * @param[in] handle Chat handle 204 * @param[in] name Chat account name 205 * @param[in] skip_op Whether to skip accounts with active operation 206 * @return Chat account 207 */ 208 struct GNUNET_CHAT_Account* 209 handle_get_account_by_name (const struct GNUNET_CHAT_Handle *handle, 210 const char *name, 211 enum GNUNET_GenericReturnValue skip_op); 212 213 /** 214 * Enqueues a creation for a chat account with a specific 215 * <i>name</i> as identifier for a given chat <i>handle</i>. 216 * 217 * @param[in,out] handle Chat handle 218 * @param[in] name Chat account name 219 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 220 */ 221 enum GNUNET_GenericReturnValue 222 handle_create_account (struct GNUNET_CHAT_Handle *handle, 223 const char *name); 224 225 /** 226 * Enqueues a deletion for a chat <i>account</i> of a 227 * given chat <i>handle</i>. 228 * 229 * @param[in,out] handle Chat handle 230 * @param[in] account Chat account 231 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 232 */ 233 enum GNUNET_GenericReturnValue 234 handle_delete_account (struct GNUNET_CHAT_Handle *handle, 235 const struct GNUNET_CHAT_Account *account); 236 237 /** 238 * Renames a chat <i>account</i> of a given chat 239 * <i>handle</i> to another specific <i>new_name</i>. 240 * 241 * @param[in,out] handle Chat handle 242 * @param[in] account Chat account 243 * @param[in] new_name New chat account name 244 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 245 */ 246 enum GNUNET_GenericReturnValue 247 handle_rename_account (struct GNUNET_CHAT_Handle *handle, 248 const struct GNUNET_CHAT_Account *account, 249 const char *new_name); 250 251 /** 252 * Enqueues a deletion for a chat <i>lobby</i> for a 253 * given chat <i>handle</i>. 254 * 255 * @param[in,out] handle Chat handle 256 * @param[in] lobby Chat lobby 257 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 258 */ 259 enum GNUNET_GenericReturnValue 260 handle_delete_lobby (struct GNUNET_CHAT_Handle *handle, 261 const struct GNUNET_CHAT_Lobby *lobby); 262 263 /** 264 * Returns the main directory path to store information 265 * of a given chat <i>handle</i>. 266 * 267 * @param[in] handle Chat handle 268 * @return Directory path 269 */ 270 const char* 271 handle_get_directory (const struct GNUNET_CHAT_Handle *handle); 272 273 /** 274 * Returns an allocated string providing the full path to 275 * a file stored by a chat <i>handle</i> with a given 276 * <i>hash</i>. 277 * 278 * @param[in] handle Chat handle 279 * @param[in] hash File hash 280 * @return File path 281 */ 282 char* 283 handle_create_file_path (const struct GNUNET_CHAT_Handle *handle, 284 const struct GNUNET_HashCode *hash); 285 286 /** 287 * Updates the used private key by creating a new identity 288 * using the same identifier as currently in use, replacing 289 * the old identity. 290 * 291 * @param[in,out] handle Chat handle 292 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 293 */ 294 enum GNUNET_GenericReturnValue 295 handle_update (struct GNUNET_CHAT_Handle *handle); 296 297 /** 298 * Returns the private key from the current connected chat 299 * account of a given chat <i>handle</i>. 300 * 301 * @param[in] handle Chat handle 302 * @return EGOs private key or NULL 303 */ 304 const struct GNUNET_CRYPTO_BlindablePrivateKey* 305 handle_get_key (const struct GNUNET_CHAT_Handle *handle); 306 307 /** 308 * Sends an internal chat message from a given chat 309 * <i>handle</i> with an optional chat <i>account</i> or 310 * <i>context</i>, a custom <i>flag</i> and an optional 311 * <i>warning</i> text. 312 * 313 * You can select whether the callback for the internal 314 * message should be scheduled dynamically or be called 315 * as instant feedback. 316 * 317 * @param[in,out] handle Chat handle 318 * @param[in,out] account Chat account or NULL 319 * @param[in,out] context Chat context or NULL 320 * @param[in] flag Chat message flag 321 * @param[in] warning Warning text 322 * @param[in] feedback Instant feedback 323 */ 324 void 325 handle_send_internal_message (struct GNUNET_CHAT_Handle *handle, 326 struct GNUNET_CHAT_Account *account, 327 struct GNUNET_CHAT_Context *context, 328 enum GNUNET_CHAT_MessageFlag flag, 329 const char *warning, 330 enum GNUNET_GenericReturnValue feedback); 331 332 /** 333 * Sends a name message to a messenger <i>room</i> with 334 * a selected chat <i>handle</i>. 335 * 336 * @param[in,out] handle Chat handle 337 * @param[in,out] room Messenger room 338 */ 339 void 340 handle_send_room_name (struct GNUNET_CHAT_Handle *handle, 341 struct GNUNET_MESSENGER_Room *room); 342 343 /** 344 * Checks a given chat <i>handle</i> for any chat context 345 * connected with a messenger <i>room</i>, creates it if 346 * necessary and manages its context type. 347 * 348 * @param[in,out] handle Chat handle 349 * @param[in,out] room Messenger room 350 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 351 */ 352 enum GNUNET_GenericReturnValue 353 handle_request_context_by_room (struct GNUNET_CHAT_Handle *handle, 354 struct GNUNET_MESSENGER_Room *room); 355 356 /** 357 * Returns the chat contact registered for a given messenger 358 * <i>contact</i> by a selected chat <i>handle</i>. 359 * 360 * @param[in] handle Chat handle 361 * @param[in] contact Messenger contact 362 * @return Chat contact or NULL 363 */ 364 struct GNUNET_CHAT_Contact* 365 handle_get_contact_from_messenger (const struct GNUNET_CHAT_Handle *handle, 366 const struct GNUNET_MESSENGER_Contact *contact); 367 368 /** 369 * Returns the chat group registered for a given messenger 370 * <i>room</i> by a selected chat <i>handle</i>. 371 * 372 * @param[in] handle Chat handle 373 * @param[in] room Messenger room 374 * @return Chat group or NULL 375 */ 376 struct GNUNET_CHAT_Group* 377 handle_get_group_from_messenger (const struct GNUNET_CHAT_Handle *handle, 378 const struct GNUNET_MESSENGER_Room *room); 379 380 /** 381 * Processes the <i>data</i> of records under a given 382 * <i>label</i> and creates a matching chat <i>context</i> 383 * with it if it does not exist already, registered by a chat 384 * <i>handle</i>, to be updated. 385 * 386 * @param[in,out] handle Chat handle 387 * @param[in] label Namestore label 388 * @param[in] count Count of data 389 * @param[in] data Records data 390 * @return Chat context or NULL 391 */ 392 struct GNUNET_CHAT_Context* 393 handle_process_records (struct GNUNET_CHAT_Handle *handle, 394 const char *label, 395 unsigned int count, 396 const struct GNUNET_GNSRECORD_Data *data); 397 398 #endif /* GNUNET_CHAT_HANDLE_H_ */