gnunet_chat_contact.h (5836B)
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_contact.h 23 */ 24 25 #ifndef GNUNET_CHAT_CONTACT_H_ 26 #define GNUNET_CHAT_CONTACT_H_ 27 28 #include <gnunet/gnunet_common.h> 29 #include <gnunet/gnunet_messenger_service.h> 30 #include <gnunet/gnunet_util_lib.h> 31 32 #include "gnunet_chat_lib.h" 33 34 struct GNUNET_CHAT_Handle; 35 struct GNUNET_CHAT_Contact; 36 struct GNUNET_CHAT_Context; 37 struct GNUNET_CHAT_Ticket; 38 39 struct GNUNET_CHAT_InternalTickets 40 { 41 struct GNUNET_CHAT_Ticket *ticket; 42 43 struct GNUNET_CHAT_InternalTickets *next; 44 struct GNUNET_CHAT_InternalTickets *prev; 45 }; 46 47 struct GNUNET_CHAT_Contact 48 { 49 struct GNUNET_CHAT_Handle *handle; 50 struct GNUNET_CHAT_Context *context; 51 52 struct GNUNET_SCHEDULER_Task *destruction; 53 54 const struct GNUNET_MESSENGER_Contact *member; 55 struct GNUNET_CONTAINER_MultiHashMap *joined; 56 57 struct GNUNET_CHAT_InternalTickets *tickets_head; 58 struct GNUNET_CHAT_InternalTickets *tickets_tail; 59 60 char *public_key; 61 void *user_pointer; 62 63 enum GNUNET_GenericReturnValue owned; 64 }; 65 66 /** 67 * Creates a chat contact using a given messenger <i>contact</i> 68 * with a selected chat <i>handle</i>. 69 * 70 * @param[in,out] handle Chat handle 71 * @param[in] member Messenger contact 72 * @return New chat contact 73 */ 74 struct GNUNET_CHAT_Contact* 75 contact_create_from_member (struct GNUNET_CHAT_Handle *handle, 76 const struct GNUNET_MESSENGER_Contact *member); 77 78 /** 79 * Updates the latest <i>hash</i> of a join message from a given 80 * chat <i>contact</i> in a current chat <i>context</i>. 81 * 82 * @param[in,out] contact Chat contact 83 * @param[in,out] context Chat context 84 * @param[in] hash Join message hash 85 * @param[in] flags Join message flags 86 */ 87 void 88 contact_update_join (struct GNUNET_CHAT_Contact *contact, 89 struct GNUNET_CHAT_Context *context, 90 const struct GNUNET_HashCode *hash, 91 enum GNUNET_MESSENGER_MessageFlags flags); 92 93 /** 94 * Removes local chat <i>contact</i> from a given chat 95 * <i>context</i>. 96 * 97 * @param[in,out] contact Chat contact 98 * @param[in,out] context Chat context 99 */ 100 void 101 contact_leave (struct GNUNET_CHAT_Contact *contact, 102 struct GNUNET_CHAT_Context *context); 103 104 /** 105 * Updates the string representation of the public key from 106 * a given chat <i>contact</i>. 107 * 108 * @param[in,out] contact Chat contact 109 */ 110 void 111 contact_update_key (struct GNUNET_CHAT_Contact *contact); 112 113 /** 114 * Returns the public key from a given chat <i>contact</i>. 115 * 116 * @param[in] contact Chat contact 117 */ 118 const struct GNUNET_CRYPTO_BlindablePublicKey* 119 contact_get_key (const struct GNUNET_CHAT_Contact *contact); 120 121 /** 122 * Searches for a chat context containing a given chat 123 * <i>contact</i> and the least amount of other members. 124 * 125 * @param[in] contact Chat contact 126 * @param[in] room_required Flag to suggest a room is required 127 * @return Chat context or NULL 128 */ 129 struct GNUNET_CHAT_Context* 130 contact_find_context (const struct GNUNET_CHAT_Contact *contact, 131 enum GNUNET_GenericReturnValue room_required); 132 133 /** 134 * Returns whether a chat <i>contact</i> is tagged in 135 * a given chat <i>context</i> with a specific <i>tag</i>. 136 * 137 * @param[in] contact Chat contact 138 * @param[in] context Chat context or NULL (optional) 139 * @param[in] tag Tag or NULL 140 * @return #GNUNET_YES if tagged, otherwise #GNUNET_NO 141 */ 142 enum GNUNET_GenericReturnValue 143 contact_is_tagged (const struct GNUNET_CHAT_Contact *contact, 144 const struct GNUNET_CHAT_Context *context, 145 const char *tag); 146 147 /** 148 * Untags a given chat <i>contact</i> in 149 * a given chat <i>context</i> from a specific <i>tag</i>. 150 * 151 * @param[in,out] contact Chat contact 152 * @param[in,out] context Chat context 153 */ 154 void 155 contact_untag (struct GNUNET_CHAT_Contact *contact, 156 struct GNUNET_CHAT_Context *context, 157 const char *tag); 158 159 /** 160 * Tags a given chat <i>contact</i> in 161 * a given chat <i>context</i> with a specific <i>tag</i>. 162 * 163 * @param[in,out] contact Chat contact 164 * @param[in,out] context Chat context 165 * @param[in] tag Tag or NULL 166 */ 167 void 168 contact_tag (struct GNUNET_CHAT_Contact *contact, 169 struct GNUNET_CHAT_Context *context, 170 const char *tag); 171 172 /** 173 * Iterate through all tags of a given chat <i>contact</i> 174 * in a specific chat <i>context</i> (or all of them) using 175 * an optional <i>callback</i> with its closure. 176 * 177 * @param[in,out] contact Chat contact 178 * @param[in,out] context Chat context or NULL 179 * @param[in] callback Callback for tag iteration or NULL 180 * @param[in,out] cls Closure for tag iteration or NULL 181 * @return Amount of tags iterated or #GNUNET_SYSERR on error 182 */ 183 int 184 contact_iterate_tags (struct GNUNET_CHAT_Contact *contact, 185 struct GNUNET_CHAT_Context *context, 186 GNUNET_CHAT_ContactTagCallback callback, 187 void *cls); 188 189 /** 190 * Destroys a chat <i>contact</i> and frees its memory. 191 * 192 * @param[in,out] contact Chat contact 193 */ 194 void 195 contact_destroy (struct GNUNET_CHAT_Contact* contact); 196 197 #endif /* GNUNET_CHAT_CONTACT_H_ */