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