gnunet_chat_handle.h (12432B)
1 /* 2 This file is part of GNUnet. 3 Copyright (C) 2021--2026 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_HashCode *next_secret; 115 struct GNUNET_CHAT_Account *current; 116 struct GNUNET_NAMESTORE_ZoneMonitor *monitor; 117 118 struct GNUNET_CHAT_InternalLobbies *lobbies_head; 119 struct GNUNET_CHAT_InternalLobbies *lobbies_tail; 120 121 struct GNUNET_CHAT_UriLookups *lookups_head; 122 struct GNUNET_CHAT_UriLookups *lookups_tail; 123 124 struct GNUNET_CHAT_AttributeProcess *attributes_head; 125 struct GNUNET_CHAT_AttributeProcess *attributes_tail; 126 127 struct GNUNET_CHAT_TicketProcess *tickets_head; 128 struct GNUNET_CHAT_TicketProcess *tickets_tail; 129 130 struct GNUNET_CONTAINER_MultiHashMap *files; 131 struct GNUNET_CONTAINER_MultiHashMap *contexts; 132 struct GNUNET_CONTAINER_MultiShortmap *contacts; 133 struct GNUNET_CONTAINER_MultiHashMap *groups; 134 struct GNUNET_CONTAINER_MultiHashMap *invitations; 135 136 struct GNUNET_ARM_Handle *arm; 137 struct GNUNET_FS_Handle *fs; 138 struct GNUNET_GNS_Handle *gns; 139 struct GNUNET_IDENTITY_Handle *identity; 140 struct GNUNET_MESSENGER_Handle *messenger; 141 struct GNUNET_NAMESTORE_Handle *namestore; 142 struct GNUNET_RECLAIM_Handle *reclaim; 143 144 char *public_key; 145 void *user_pointer; 146 }; 147 148 /** 149 * Creates a chat handle with a selected configuration, 150 * a custom message callback and a custom closure for 151 * the callback. 152 * 153 * @param[in] cfg Configuration 154 * @param[in] msg_cb Message callback 155 * @param[in,out] msg_cls Closure 156 * @return New chat handle 157 */ 158 struct GNUNET_CHAT_Handle* 159 handle_create_from_config (const struct GNUNET_CONFIGURATION_Handle* cfg, 160 GNUNET_CHAT_ContextMessageCallback msg_cb, 161 void *msg_cls); 162 163 /** 164 * Updates the string representation of the public key from 165 * a given chat <i>handle</i>. 166 * 167 * @param[in,out] handle Chat handle 168 */ 169 void 170 handle_update_key (struct GNUNET_CHAT_Handle *handle); 171 172 /** 173 * Destroys a chat <i>handle</i> and frees its memory. 174 * 175 * @param[in,out] handle Chat handle 176 */ 177 void 178 handle_destroy (struct GNUNET_CHAT_Handle *handle); 179 180 /** 181 * Connects a given chat <i>handle</i> to a selected 182 * chat <i>account</i> using it for further operations. 183 * 184 * @param[in,out] handle Chat handle 185 * @param[in] account Chat account 186 * @param[in] secret Chat account secret or NULL 187 */ 188 void 189 handle_connect (struct GNUNET_CHAT_Handle *handle, 190 struct GNUNET_CHAT_Account *account, 191 const struct GNUNET_HashCode *secret); 192 193 /** 194 * Disconnects a given chat <i>handle</i> from its current 195 * connected chat account. 196 * 197 * @param[in,out] handle Chat handle 198 */ 199 void 200 handle_disconnect (struct GNUNET_CHAT_Handle *handle); 201 202 /** 203 * Searches for an existing chat account by <i>name</i> as 204 * identifier for a given chat <i>handle</i>. 205 * 206 * @param[in] handle Chat handle 207 * @param[in] name Chat account name 208 * @param[in] skip_op Whether to skip accounts with active operation 209 * @return Chat account 210 */ 211 struct GNUNET_CHAT_Account* 212 handle_get_account_by_name (const struct GNUNET_CHAT_Handle *handle, 213 const char *name, 214 enum GNUNET_GenericReturnValue skip_op); 215 216 /** 217 * Enqueues a creation for a chat account with a specific 218 * <i>name</i> as identifier for a given chat <i>handle</i>. 219 * 220 * @param[in,out] handle Chat handle 221 * @param[in] name Chat account name 222 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 223 */ 224 enum GNUNET_GenericReturnValue 225 handle_create_account (struct GNUNET_CHAT_Handle *handle, 226 const char *name); 227 228 /** 229 * Enqueues a deletion for a chat <i>account</i> of a 230 * given chat <i>handle</i>. 231 * 232 * @param[in,out] handle Chat handle 233 * @param[in] account Chat account 234 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 235 */ 236 enum GNUNET_GenericReturnValue 237 handle_delete_account (struct GNUNET_CHAT_Handle *handle, 238 const struct GNUNET_CHAT_Account *account); 239 240 /** 241 * Renames a chat <i>account</i> of a given chat 242 * <i>handle</i> to another specific <i>new_name</i>. 243 * 244 * @param[in,out] handle Chat handle 245 * @param[in] account Chat account 246 * @param[in] new_name New chat account name 247 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 248 */ 249 enum GNUNET_GenericReturnValue 250 handle_rename_account (struct GNUNET_CHAT_Handle *handle, 251 const struct GNUNET_CHAT_Account *account, 252 const char *new_name); 253 254 /** 255 * Enqueues a deletion for a chat <i>lobby</i> for a 256 * given chat <i>handle</i>. 257 * 258 * @param[in,out] handle Chat handle 259 * @param[in] lobby Chat lobby 260 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 261 */ 262 enum GNUNET_GenericReturnValue 263 handle_delete_lobby (struct GNUNET_CHAT_Handle *handle, 264 const struct GNUNET_CHAT_Lobby *lobby); 265 266 /** 267 * Returns the main directory path to store information 268 * of a given chat <i>handle</i>. 269 * 270 * @param[in] handle Chat handle 271 * @return Directory path 272 */ 273 const char* 274 handle_get_directory (const struct GNUNET_CHAT_Handle *handle); 275 276 /** 277 * Returns an allocated string providing the full path to 278 * a file stored by a chat <i>handle</i> with a given 279 * <i>hash</i>. 280 * 281 * @param[in] handle Chat handle 282 * @param[in] hash File hash 283 * @return File path 284 */ 285 char* 286 handle_create_file_path (const struct GNUNET_CHAT_Handle *handle, 287 const struct GNUNET_HashCode *hash); 288 289 /** 290 * Updates the used private key by creating a new identity 291 * using the same identifier as currently in use, replacing 292 * the old identity. 293 * 294 * @param[in,out] handle Chat handle 295 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 296 */ 297 enum GNUNET_GenericReturnValue 298 handle_update (struct GNUNET_CHAT_Handle *handle); 299 300 /** 301 * Returns the private key from the current connected chat 302 * account of a given chat <i>handle</i>. 303 * 304 * @param[in] handle Chat handle 305 * @return EGOs private key or NULL 306 */ 307 const struct GNUNET_CRYPTO_BlindablePrivateKey* 308 handle_get_key (const struct GNUNET_CHAT_Handle *handle); 309 310 /** 311 * Sends an internal chat message from a given chat 312 * <i>handle</i> with an optional chat <i>account</i> or 313 * <i>context</i>, a custom <i>flag</i> and an optional 314 * <i>warning</i> text. 315 * 316 * You can select whether the callback for the internal 317 * message should be scheduled dynamically or be called 318 * as instant feedback. 319 * 320 * @param[in,out] handle Chat handle 321 * @param[in,out] account Chat account or NULL 322 * @param[in,out] context Chat context or NULL 323 * @param[in] flag Chat message flag 324 * @param[in] warning Warning text 325 * @param[in] feedback Instant feedback 326 */ 327 void 328 handle_send_internal_message (struct GNUNET_CHAT_Handle *handle, 329 struct GNUNET_CHAT_Account *account, 330 struct GNUNET_CHAT_Context *context, 331 enum GNUNET_CHAT_MessageFlag flag, 332 const char *warning, 333 enum GNUNET_GenericReturnValue feedback); 334 335 /** 336 * Sends a name message to a messenger <i>room</i> with 337 * a selected chat <i>handle</i>. 338 * 339 * @param[in,out] handle Chat handle 340 * @param[in,out] room Messenger room 341 */ 342 void 343 handle_send_room_name (struct GNUNET_CHAT_Handle *handle, 344 struct GNUNET_MESSENGER_Room *room); 345 346 /** 347 * Checks a given chat <i>handle</i> for any chat context 348 * connected with a messenger <i>room</i>, creates it if 349 * necessary and manages its context type. 350 * 351 * @param[in,out] handle Chat handle 352 * @param[in,out] room Messenger room 353 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 354 */ 355 enum GNUNET_GenericReturnValue 356 handle_request_context_by_room (struct GNUNET_CHAT_Handle *handle, 357 struct GNUNET_MESSENGER_Room *room); 358 359 /** 360 * Returns the chat contact registered for a given messenger 361 * <i>contact</i> by a selected chat <i>handle</i>. 362 * 363 * @param[in] handle Chat handle 364 * @param[in] contact Messenger contact 365 * @return Chat contact or NULL 366 */ 367 struct GNUNET_CHAT_Contact* 368 handle_get_contact_from_messenger (const struct GNUNET_CHAT_Handle *handle, 369 const struct GNUNET_MESSENGER_Contact *contact); 370 371 /** 372 * Returns the chat group registered for a given messenger 373 * <i>room</i> by a selected chat <i>handle</i>. 374 * 375 * @param[in] handle Chat handle 376 * @param[in] room Messenger room 377 * @return Chat group or NULL 378 */ 379 struct GNUNET_CHAT_Group* 380 handle_get_group_from_messenger (const struct GNUNET_CHAT_Handle *handle, 381 const struct GNUNET_MESSENGER_Room *room); 382 383 /** 384 * Processes the <i>data</i> of records under a given 385 * <i>label</i> and creates a matching chat <i>context</i> 386 * with it if it does not exist already, registered by a chat 387 * <i>handle</i>, to be updated. 388 * 389 * @param[in,out] handle Chat handle 390 * @param[in] label Namestore label 391 * @param[in] count Count of data 392 * @param[in] data Records data 393 * @return Chat context or NULL 394 */ 395 struct GNUNET_CHAT_Context* 396 handle_process_records (struct GNUNET_CHAT_Handle *handle, 397 const char *label, 398 unsigned int count, 399 const struct GNUNET_GNSRECORD_Data *data); 400 401 #endif /* GNUNET_CHAT_HANDLE_H_ */