gnunet_chat_lib.h (64859B)
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 The development of this code was supported by the NLnet foundation as part 22 of the NGI Assure initative to have a more free and secure internet. 23 */ 24 /* 25 * @author Tobias Frisch 26 * @file gnunet_chat_lib.h 27 */ 28 29 #ifndef GNUNET_CHAT_LIB_H_ 30 #define GNUNET_CHAT_LIB_H_ 31 32 /** 33 * @defgroup gnunet_chat GNUnet Chat library 34 */ 35 /**@{*/ 36 37 #include <gnunet/gnunet_util_lib.h> 38 39 40 #include <stdint.h> 41 #include <time.h> 42 43 /** 44 * @def GNUNET_CHAT_VERSION The major and minor version should be identical to 45 * the #GNUNET_MESSENGER_VERSION of the GNUnet Messenger 46 * service while the patch version is independent. 47 */ 48 #define GNUNET_CHAT_VERSION 0x000000060001L 49 50 #define GNUNET_CHAT_VERSION_MAJOR ((GNUNET_CHAT_VERSION >> 32L) & 0xFFFFL) 51 #define GNUNET_CHAT_VERSION_MINOR ((GNUNET_CHAT_VERSION >> 16L) & 0xFFFFL) 52 #define GNUNET_CHAT_VERSION_PATCH ((GNUNET_CHAT_VERSION >> 0L) & 0xFFFFL) 53 54 #define GNUNET_CHAT_ATTRIBUTE_AVATAR "chat_avatar" 55 #define GNUNET_CHAT_ATTRIBUTE_BIRTHDAY "chat_birthday" 56 #define GNUNET_CHAT_ATTRIBUTE_EMAIL "chat_email" 57 #define GNUNET_CHAT_ATTRIBUTE_NAME "chat_name" 58 #define GNUNET_CHAT_ATTRIBUTE_PHONE "chat_phone" 59 #define GNUNET_CHAT_ATTRIBUTE_POSTAL "chat_postal" 60 61 #define GNUNET_CHAT_URI_PREFIX "gnunet://chat/" 62 63 /** 64 * Enum for the different types of supported URIs. 65 */ 66 enum GNUNET_CHAT_UriType 67 { 68 /** 69 * The type to share and join a lobby or chat. 70 */ 71 GNUNET_CHAT_URI_TYPE_CHAT = 1, /**< GNUNET_CHAT_URI_TYPE_CHAT */ 72 73 /** 74 * The type to download and query files vis FS service from GNUnet. 75 */ 76 GNUNET_CHAT_URI_TYPE_FS = 2, /**< GNUNET_CHAT_URI_TYPE_FS */ 77 78 /** 79 * An unknown type of uri. 80 */ 81 GNUNET_CHAT_URI_TYPE_UNKNOWN = 0 /**< GNUNET_CHAT_URI_TYPE_UNKNOWN */ 82 }; 83 84 /** 85 * Enum for the different kinds of messages. 86 */ 87 enum GNUNET_CHAT_MessageKind 88 { 89 /** 90 * The kind to inform that something went wrong. 91 */ 92 GNUNET_CHAT_KIND_WARNING = 1, /**< GNUNET_CHAT_KIND_WARNING */ 93 94 /** 95 * The kind to inform that the list of accounts was refreshed. 96 */ 97 GNUNET_CHAT_KIND_REFRESH = 2, /**< GNUNET_CHAT_KIND_REFRESH */ 98 99 /** 100 * The kind to inform that the application can be used. 101 */ 102 GNUNET_CHAT_KIND_LOGIN = 3, /**< GNUNET_CHAT_KIND_LOGIN */ 103 104 /** 105 * The kind to inform that the application needs to cleanup 106 * resources related to the currently connected account. 107 */ 108 GNUNET_CHAT_KIND_LOGOUT = 4, /**< GNUNET_CHAT_KIND_LOGOUT */ 109 110 /** 111 * The kind to inform that an account was successfully created. 112 */ 113 GNUNET_CHAT_KIND_CREATED_ACCOUNT = 5, /**< GNUNET_CHAT_KIND_CREATED_ACCOUNT */ 114 115 /** 116 * The kind to inform that an account was successfully deleted. 117 */ 118 GNUNET_CHAT_KIND_DELETED_ACCOUNT = 6, /**< GNUNET_CHAT_KIND_DELETED_ACCOUNT */ 119 120 /** 121 * The kind to inform that an account was updated. 122 */ 123 GNUNET_CHAT_KIND_UPDATE_ACCOUNT = 7, /**< GNUNET_CHAT_KIND_UPDATE_ACCOUNT */ 124 125 /** 126 * The kind to inform that a context was updated. 127 */ 128 GNUNET_CHAT_KIND_UPDATE_CONTEXT = 8, /**< GNUNET_CHAT_KIND_UPDATE_CONTEXT */ 129 130 /** 131 * The kind to inform that a contact has joined a chat. 132 */ 133 GNUNET_CHAT_KIND_JOIN = 9, /**< GNUNET_CHAT_KIND_JOIN */ 134 135 /** 136 * The kind to inform that a contact has left a chat. 137 */ 138 GNUNET_CHAT_KIND_LEAVE = 10, /**< GNUNET_CHAT_KIND_LEAVE */ 139 140 /** 141 * The kind to inform that a contact has changed. 142 */ 143 GNUNET_CHAT_KIND_CONTACT = 11, /**< GNUNET_CHAT_KIND_CONTACT */ 144 145 /** 146 * The kind to describe an invitation to a different chat. 147 */ 148 GNUNET_CHAT_KIND_INVITATION = 12, /**< GNUNET_CHAT_KIND_INVITATION */ 149 150 /** 151 * The kind to describe a text message. 152 */ 153 GNUNET_CHAT_KIND_TEXT = 13, /**< GNUNET_CHAT_KIND_TEXT */ 154 155 /** 156 * The kind to describe a shared file. 157 */ 158 GNUNET_CHAT_KIND_FILE = 14, /**< GNUNET_CHAT_KIND_FILE */ 159 160 /** 161 * The kind to inform about a deletion of a previous message. 162 */ 163 GNUNET_CHAT_KIND_DELETION = 15, /**< GNUNET_CHAT_KIND_DELETION */ 164 165 /** 166 * The kind to tag a previous message. 167 */ 168 GNUNET_CHAT_KIND_TAG = 16, /**< GNUNET_CHAT_KIND_TAG */ 169 170 /** 171 * The kind to inform that attributes were updated. 172 */ 173 GNUNET_CHAT_KIND_ATTRIBUTES = 17, /**< GNUNET_CHAT_KIND_ATTRIBUTES */ 174 175 /** 176 * The kind to inform that attributes were shared. 177 */ 178 GNUNET_CHAT_KIND_SHARED_ATTRIBUTES = 18, /**< GNUNET_CHAT_KIND_SHARED_ATTRIBUTES */ 179 180 /** 181 * The kind to inform that a discourse was updated. 182 */ 183 GNUNET_CHAT_KIND_DISCOURSE = 19, /**< GNUNET_CHAT_KIND_DISCOURSE */ 184 185 /** 186 * The kind to describe a data message from a discourse. 187 */ 188 GNUNET_CHAT_KIND_DATA = 20, /**< GNUNET_CHAT_KIND_DATA */ 189 190 /** 191 * An unknown kind of message. 192 */ 193 GNUNET_CHAT_KIND_UNKNOWN = 0 /**< GNUNET_CHAT_KIND_UNKNOWN */ 194 }; 195 196 /** 197 * Struct to identify discourses 198 */ 199 struct GNUNET_CHAT_DiscourseId 200 { 201 char identifier [32]; 202 }; 203 204 /** 205 * Struct of a chat handle. 206 */ 207 struct GNUNET_CHAT_Handle; 208 209 /** 210 * Struct of a chat account. 211 */ 212 struct GNUNET_CHAT_Account; 213 214 /** 215 * Struct of a chat URI. 216 */ 217 struct GNUNET_CHAT_Uri; 218 219 /** 220 * Struct of a chat lobby. 221 */ 222 struct GNUNET_CHAT_Lobby; 223 224 /** 225 * Struct of a chat contact. 226 */ 227 struct GNUNET_CHAT_Contact; 228 229 /** 230 * Struct of a chat group. 231 */ 232 struct GNUNET_CHAT_Group; 233 234 /** 235 * Struct of a chat context. 236 */ 237 struct GNUNET_CHAT_Context; 238 239 /** 240 * Struct of a chat message. 241 */ 242 struct GNUNET_CHAT_Message; 243 244 /** 245 * Struct of a chat file. 246 */ 247 struct GNUNET_CHAT_File; 248 249 /** 250 * Struct of a chat invitation. 251 */ 252 struct GNUNET_CHAT_Invitation; 253 254 /** 255 * Struct of a chat discourse. 256 */ 257 struct GNUNET_CHAT_Discourse; 258 259 /** 260 * Iterator over chat accounts of a specific chat handle. 261 * 262 * @param[in,out] cls Closure from #GNUNET_CHAT_iterate_accounts 263 * @param[in,out] handle Chat handle 264 * @param[in,out] account Chat account 265 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 266 */ 267 typedef enum GNUNET_GenericReturnValue 268 (*GNUNET_CHAT_AccountCallback) (void *cls, 269 struct GNUNET_CHAT_Handle *handle, 270 struct GNUNET_CHAT_Account *account); 271 272 /** 273 * Iterator over attributes of a specific chat account. 274 * 275 * @param[in,out] cls Closure from #GNUNET_CHAT_get_attributes 276 * @param[in,out] account Chat account 277 * @param[in] name Attribute name 278 * @param[in] value Attribute value 279 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 280 */ 281 typedef enum GNUNET_GenericReturnValue 282 (*GNUNET_CHAT_AccountAttributeCallback) (void *cls, 283 struct GNUNET_CHAT_Account *account, 284 const char *name, 285 const char *value); 286 287 /** 288 * Iterator over attributes of a specific chat handle. 289 * 290 * @param[in,out] cls Closure from #GNUNET_CHAT_get_attributes 291 * @param[in,out] handle Chat handle 292 * @param[in] name Attribute name 293 * @param[in] value Attribute value 294 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 295 */ 296 typedef enum GNUNET_GenericReturnValue 297 (*GNUNET_CHAT_AttributeCallback) (void *cls, 298 struct GNUNET_CHAT_Handle *handle, 299 const char *name, 300 const char *value); 301 302 /** 303 * Method called when a lobby is opened to share with others via a chat URI. 304 * 305 * @param[in,out] cls Closure from #GNUNET_CHAT_lobby_open 306 * @param[in] uri Chat URI of the lobby or NULL on error 307 */ 308 typedef void 309 (*GNUNET_CHAT_LobbyCallback) (void *cls, 310 const struct GNUNET_CHAT_Uri *uri); 311 312 /** 313 * Iterator over chat files of a specific chat handle. 314 * 315 * @param[in,out] cls Closure from #GNUNET_CHAT_iterate_files 316 * @param[in,out] handle Chat handle 317 * @param[in,out] file Chat file 318 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 319 */ 320 typedef enum GNUNET_GenericReturnValue 321 (*GNUNET_CHAT_FileCallback) (void *cls, 322 struct GNUNET_CHAT_Handle *handle, 323 struct GNUNET_CHAT_File *file); 324 325 /** 326 * Iterator over chat contacts of a specific chat handle. 327 * 328 * @param[in,out] cls Closure from #GNUNET_CHAT_iterate_contacts 329 * @param[in,out] handle Chat handle 330 * @param[in,out] contact Chat contact 331 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 332 */ 333 typedef enum GNUNET_GenericReturnValue 334 (*GNUNET_CHAT_ContactCallback) (void *cls, 335 struct GNUNET_CHAT_Handle *handle, 336 struct GNUNET_CHAT_Contact *contact); 337 338 /** 339 * Iterator over tags of a specific chat contact. 340 * 341 * @param[in,out] cls Closure 342 * @param[in,out] contact Chat contact 343 * @param[in] tag Tag 344 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 345 */ 346 typedef enum GNUNET_GenericReturnValue 347 (*GNUNET_CHAT_ContactTagCallback) (void *cls, 348 struct GNUNET_CHAT_Contact *contact, 349 const char *tag); 350 351 /** 352 * Iterator over accessible attributes of a specific chat contact. 353 * 354 * @param[in,out] cls Closure 355 * @param[in,out] contact Chat contact 356 * @param[in] name Attribute name 357 * @param[in] value Attribute value 358 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 359 */ 360 typedef enum GNUNET_GenericReturnValue 361 (*GNUNET_CHAT_ContactAttributeCallback) (void *cls, 362 struct GNUNET_CHAT_Contact *contact, 363 const char *name, 364 const char *value); 365 366 /** 367 * Iterator over chat groups of a specific chat handle. 368 * 369 * @param[in,out] cls Closure from #GNUNET_CHAT_iterate_groups 370 * @param[in,out] handle Chat handle 371 * @param[in,out] group Chat group 372 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 373 */ 374 typedef enum GNUNET_GenericReturnValue 375 (*GNUNET_CHAT_GroupCallback) (void *cls, 376 struct GNUNET_CHAT_Handle *handle, 377 struct GNUNET_CHAT_Group *group); 378 379 /** 380 * Iterator over chat contacts in a specific chat group. 381 * 382 * @param[in,out] cls Closure from #GNUNET_CHAT_group_iterate_contacts 383 * @param[in,out] group Chat group 384 * @param[in,out] contact Chat contact 385 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 386 */ 387 typedef enum GNUNET_GenericReturnValue 388 (*GNUNET_CHAT_GroupContactCallback) (void *cls, 389 struct GNUNET_CHAT_Group *group, 390 struct GNUNET_CHAT_Contact *contact); 391 392 /** 393 * Iterator over chat messages in a specific chat context. 394 * 395 * @param[in,out] cls Closure from #GNUNET_CHAT_context_iterate_messages 396 * @param[in,out] context Chat context or NULL 397 * @param[in,out] message Chat message 398 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 399 */ 400 typedef enum GNUNET_GenericReturnValue 401 (*GNUNET_CHAT_ContextMessageCallback) (void *cls, 402 struct GNUNET_CHAT_Context *context, 403 struct GNUNET_CHAT_Message *message); 404 405 /** 406 * Iterator over chat files in a specific chat context. 407 * 408 * @param[in,out] cls Closure from #GNUNET_CHAT_context_iterate_files 409 * @param[in,out] context Chat context 410 * @param[in,out] file Chat file 411 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 412 */ 413 typedef enum GNUNET_GenericReturnValue 414 (*GNUNET_CHAT_ContextFileCallback) (void *cls, 415 struct GNUNET_CHAT_Context *context, 416 struct GNUNET_CHAT_File *file); 417 418 /** 419 * Iterator over chat contacts in a chat to check whether they received a 420 * specific message or not. 421 * 422 * @param[in,out] cls Closure from #GNUNET_CHAT_message_get_read_receipt 423 * @param[in,out] message Chat message 424 * @param[in,out] contact Chat contact 425 * @param[in] read_receipt #GNUNET_YES if the message was received by the contact, 426 * #GNUNET_NO otherwise 427 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 428 */ 429 typedef enum GNUNET_GenericReturnValue 430 (*GNUNET_CHAT_MessageReadReceiptCallback) (void *cls, 431 struct GNUNET_CHAT_Message *message, 432 struct GNUNET_CHAT_Contact *contact, 433 int read_receipt); 434 435 /** 436 * Iterator over chat tag messages with a specific target message. 437 * 438 * @param[in,out] cls Closure from #GNUNET_CHAT_message_iterate_tags 439 * @param[in,out] message Chat message 440 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 441 */ 442 typedef enum GNUNET_GenericReturnValue 443 (*GNUNET_CHAT_MessageCallback) (void *cls, 444 struct GNUNET_CHAT_Message *message); 445 446 /** 447 * Method called during an upload of a specific file in a chat to share it. 448 * 449 * @param[in,out] cls Closure from #GNUNET_CHAT_context_send_file 450 * @param[in,out] file Chat file 451 * @param[in] completed Amount of the file being uploaded (in bytes) 452 * @param[in] size Full size of the uploading file (in bytes) 453 */ 454 typedef void 455 (*GNUNET_CHAT_FileUploadCallback) (void *cls, 456 struct GNUNET_CHAT_File *file, 457 uint64_t completed, 458 uint64_t size); 459 460 /** 461 * Method called during a download of a specific file in a chat which was shared. 462 * 463 * @param[in,out] cls Closure from #GNUNET_CHAT_file_start_download 464 * @param[in,out] file Chat file 465 * @param[in] completed Amount of the file being downloaded (in bytes) 466 * @param[in] size Full size of the downloading file (in bytes) 467 */ 468 typedef void 469 (*GNUNET_CHAT_FileDownloadCallback) (void *cls, 470 struct GNUNET_CHAT_File *file, 471 uint64_t completed, 472 uint64_t size); 473 474 /** 475 * Method called during an unindexing of a specific file in a chat which was 476 * uploaded before. 477 * 478 * @param[in,out] cls Closure from #GNUNET_CHAT_file_unindex 479 * @param[in,out] file Chat file 480 * @param[in] completed Amount of the file being unindexed (in bytes) 481 * @param[in] size Full size of the unindexing file (in bytes) 482 */ 483 typedef void 484 (*GNUNET_CHAT_FileUnindexCallback) (void *cls, 485 struct GNUNET_CHAT_File *file, 486 uint64_t completed, 487 uint64_t size); 488 489 /** 490 * Iterator over chat discourses in a specific chat context. 491 * 492 * @param[in,out] cls Closure from #GNUNET_CHAT_context_iterate_discourses 493 * @param[in,out] context Chat context 494 * @param[in,out] discourse Chat discourse 495 */ 496 typedef enum GNUNET_GenericReturnValue 497 (*GNUNET_CHAT_DiscourseCallback) (void *cls, 498 struct GNUNET_CHAT_Context *context, 499 struct GNUNET_CHAT_Discourse *discourse); 500 501 /** 502 * Iterator over chat contacts in a specific chat discourse. 503 * 504 * @param[in,out] cls Closure from #GNUNET_CHAT_discourse_iterate_contacts 505 * @param[in,out] discourse Chat discourse 506 * @param[in,out] contact Chat contact 507 * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. 508 */ 509 typedef enum GNUNET_GenericReturnValue 510 (*GNUNET_CHAT_DiscourseContactCallback) (void *cls, 511 struct GNUNET_CHAT_Discourse *discourse, 512 struct GNUNET_CHAT_Contact *contact); 513 514 /** 515 * Start a chat handle with a certain configuration. 516 * 517 * A custom callback for warnings and message events can be provided optionally 518 * together with their respective closures. 519 * 520 * @param[in] cfg Configuration 521 * @param[in] msg_cb Callback for message events (optional) 522 * @param[in,out] msg_cls Closure for message events (optional) 523 * @return Chat handle 524 */ 525 struct GNUNET_CHAT_Handle* 526 GNUNET_CHAT_start (const struct GNUNET_CONFIGURATION_Handle *cfg, 527 GNUNET_CHAT_ContextMessageCallback msg_cb, 528 void *msg_cls); 529 530 /** 531 * Stops a chat handle closing all its remaining resources and frees the 532 * regarding memory. 533 * 534 * @param[in,out] handle Chat handle 535 */ 536 void 537 GNUNET_CHAT_stop (struct GNUNET_CHAT_Handle *handle); 538 539 /** 540 * Creates a new chat account to use with a given chat <i>handle</i> under a 541 * unique <i>name</i>. 542 * 543 * If a specific name is already in use of another chat accounts, the function 544 * will fail and return #GNUNET_NO. 545 * 546 * @param[in,out] handle Chat handle 547 * @param[in] name Account name 548 * @return #GNUNET_OK on success, #GNUNET_NO on failure and otherwise #GNUNET_SYSERR 549 */ 550 enum GNUNET_GenericReturnValue 551 GNUNET_CHAT_account_create (struct GNUNET_CHAT_Handle *handle, 552 const char *name); 553 554 /** 555 * Deletes an existing chat account of a given chat <i>handle</i> under a 556 * unique <i>name</i>. 557 * 558 * @param[in,out] handle Chat handle 559 * @param[in] name Account name 560 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 561 */ 562 enum GNUNET_GenericReturnValue 563 GNUNET_CHAT_account_delete(struct GNUNET_CHAT_Handle *handle, 564 const char *name); 565 566 /** 567 * Iterates through the accounts of a given chat <i>handle</i> with a selected 568 * callback and custom closure. 569 * 570 * @param[in,out] handle Chat handle 571 * @param[in] callback Callback for account iteration (optional) 572 * @param[in,out] cls Closure for account iteration (optional) 573 * @return Amount of accounts iterated or #GNUNET_SYSERR on failure 574 */ 575 int 576 GNUNET_CHAT_iterate_accounts (struct GNUNET_CHAT_Handle *handle, 577 GNUNET_CHAT_AccountCallback callback, 578 void *cls); 579 580 /** 581 * Searches for an existing chat account of a given chat <i>handle</i> with 582 * a unique <i>name</i>. 583 * 584 * @param[in] handle Chat handle 585 * @param[in] name Account name 586 * @return Found account by the handle or NULL 587 */ 588 struct GNUNET_CHAT_Account* 589 GNUNET_CHAT_find_account (const struct GNUNET_CHAT_Handle *handle, 590 const char *name); 591 592 /** 593 * Connects a chat <i>handle</i> to a selected chat <i>account</i>. 594 * 595 * @param[in,out] handle Chat handle 596 * @param[in,out] account Chat account 597 */ 598 void 599 GNUNET_CHAT_connect (struct GNUNET_CHAT_Handle *handle, 600 struct GNUNET_CHAT_Account *account); 601 602 /** 603 * Disconnects a chat <i>handle</i> from the current chat account. 604 * 605 * @param[in,out] handle Chat handle 606 */ 607 void 608 GNUNET_CHAT_disconnect (struct GNUNET_CHAT_Handle *handle); 609 610 /** 611 * Returns the connected account of a chat <i>handle</i> for related 612 * communication or NULL if no account is set yet. 613 * 614 * @param[in] handle Chat handle 615 * @return Account used by the handle or NULL 616 */ 617 struct GNUNET_CHAT_Account* 618 GNUNET_CHAT_get_connected (const struct GNUNET_CHAT_Handle *handle); 619 620 /** 621 * Updates a chat handle to renew the used ego to sign sent messages in active 622 * chats. 623 * 624 * Updating the chat handle should only be used if necessary because the usage 625 * can require renewed exchanging of GNS entries. 626 * 627 * @param[in,out] handle Chat handle 628 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 629 */ 630 enum GNUNET_GenericReturnValue 631 GNUNET_CHAT_update (struct GNUNET_CHAT_Handle *handle); 632 633 /** 634 * Updates the name of a chat handle for related communication. 635 * 636 * @param[in,out] handle Chat handle 637 * @param[in] name New name or NULL 638 * @return #GNUNET_YES on success, #GNUNET_NO on failure and #GNUNET_SYSERR if <i>handle</i> is NULL 639 */ 640 enum GNUNET_GenericReturnValue 641 GNUNET_CHAT_set_name (struct GNUNET_CHAT_Handle *handle, 642 const char *name); 643 644 /** 645 * Returns the name of a chat handle for related communication or NULL if no 646 * name is set. 647 * 648 * @param[in] handle Chat handle 649 * @return Name used by the handle or NULL 650 */ 651 const char* 652 GNUNET_CHAT_get_name (const struct GNUNET_CHAT_Handle *handle); 653 654 /** 655 * Returns the public key of the used ego to verify signatures of sent messages. 656 * 657 * @param[in] handle Chat handle 658 * @return Public key of the handles ego or NULL 659 */ 660 const char* 661 GNUNET_CHAT_get_key (const struct GNUNET_CHAT_Handle *handle); 662 663 /** 664 * Updates an attribute of a chat handle for related communication under a given 665 * <i>name</i> and a custom <i>value</i>. 666 * 667 * @param[in,out] handle Chat handle 668 * @param[in] name Attribute name 669 * @param[in] value Attribute value 670 */ 671 void 672 GNUNET_CHAT_set_attribute (struct GNUNET_CHAT_Handle *handle, 673 const char *name, 674 const char *value); 675 676 /** 677 * Deletes an attribute of a chat <i>handle</i> for related communication 678 * under a given <i>name</i>. 679 * 680 * @param[in,out] handle Chat handle 681 * @param[in] name Attribute name 682 */ 683 void 684 GNUNET_CHAT_delete_attribute (struct GNUNET_CHAT_Handle *handle, 685 const char *name); 686 687 /** 688 * Calls an optional <i>callback</i> for each attribute of a given chat 689 * <i>handle</i>. 690 * 691 * @param[in,out] handle Chat handle 692 * @param[in] callback Callback for attribute iteration (optional) 693 * @param[in,out] cls Closure for attribute iteration (optional) 694 */ 695 void 696 GNUNET_CHAT_get_attributes (struct GNUNET_CHAT_Handle *handle, 697 GNUNET_CHAT_AttributeCallback callback, 698 void *cls); 699 700 /** 701 * Share an attribute of a chat <i>handle</i> under a given <i>name</i> 702 * with a specific chat <i>contact</i>. 703 * 704 * @param[in,out] handle Chat handle 705 * @param[in,out] contact Chat contact 706 * @param[in] name Attribute name 707 */ 708 void 709 GNUNET_CHAT_share_attribute_with (struct GNUNET_CHAT_Handle *handle, 710 struct GNUNET_CHAT_Contact *contact, 711 const char *name); 712 713 /** 714 * Unshare an attribute of a chat <i>handle</i> under a given <i>name</i> 715 * from a specific chat <i>contact</i>. 716 * 717 * @param[in,out] handle Chat handle 718 * @param[in,out] contact Chat contact 719 * @param[in] name Attribute name 720 */ 721 void 722 GNUNET_CHAT_unshare_attribute_from (struct GNUNET_CHAT_Handle *handle, 723 struct GNUNET_CHAT_Contact *contact, 724 const char *name); 725 726 /** 727 * Calls an optional <i>callback</i> for each attribute of a given chat 728 * <i>handle</i> shared with a specific chat <i>contact</i>. 729 * 730 * @param[in,out] handle Chat handle 731 * @param[in] contact Chat contact 732 * @param[in] callback Callback for attribute iteration (optional) 733 * @param[in,out] cls Closure for attribute iteration (optional) 734 */ 735 void 736 GNUNET_CHAT_get_shared_attributes (struct GNUNET_CHAT_Handle *handle, 737 struct GNUNET_CHAT_Contact *contact, 738 GNUNET_CHAT_ContactAttributeCallback callback, 739 void *cls); 740 741 /** 742 * Convert an UTF-8 String to a chat URI which will be newly allocated. 743 * 744 * @param[in] uri UTF-8 string to parse 745 * @param[out] emsg Where to store the parser error message (if any) 746 * @return URI on success, NULL on error 747 */ 748 struct GNUNET_CHAT_Uri* 749 GNUNET_CHAT_uri_parse (const char *uri, 750 char **emsg); 751 752 /** 753 * Convert a chat URI to a UTF-8 String. 754 * 755 * @param[in] uri Chat URI 756 * @return The UTF-8 string representing the URI 757 */ 758 char* 759 GNUNET_CHAT_uri_to_string (const struct GNUNET_CHAT_Uri *uri); 760 761 /** 762 * Returns the type of a given chat URI. 763 * 764 * @param[in] uri Chat URI 765 * @return The type of URI 766 */ 767 enum GNUNET_CHAT_UriType 768 GNUNET_CHAT_uri_get_type (const struct GNUNET_CHAT_Uri *uri); 769 770 /** 771 * Free an allocated chat URI. 772 * 773 * @param[in,out] uri Chat URI 774 */ 775 void 776 GNUNET_CHAT_uri_destroy (struct GNUNET_CHAT_Uri *uri); 777 778 /** 779 * Opens an empty chat lobby which will expire after a custom <i>delay</i>. 780 * 781 * @param[in,out] handle Chat handle 782 * @param[in] delay Expiration delay 783 * @param[in] callback Callback for the lobby opening 784 * @param[in,out] cls Closure for the lobby opening (optional) 785 * @return Chat lobby 786 */ 787 struct GNUNET_CHAT_Lobby* 788 GNUNET_CHAT_lobby_open (struct GNUNET_CHAT_Handle *handle, 789 unsigned int delay, 790 GNUNET_CHAT_LobbyCallback callback, 791 void *cls); 792 793 /** 794 * Closes a chat <i>lobby</i> overriding the expiration to be now. 795 * 796 * @param[in,out] lobby Chat lobby 797 */ 798 void 799 GNUNET_CHAT_lobby_close (struct GNUNET_CHAT_Lobby *lobby); 800 801 /** 802 * Joins an open lobby via URI with a given chat <i>handle</i> if it can still 803 * be resolved (depends on connection and expiration of the lobby). 804 * 805 * @param[in,out] handle Chat handle 806 * @param[in] uri Chat URI 807 */ 808 void 809 GNUNET_CHAT_lobby_join (struct GNUNET_CHAT_Handle *handle, 810 const struct GNUNET_CHAT_Uri *uri); 811 812 /** 813 * Requests a file with a given chat <i>handle</i> from a selected chat 814 * <i>uri</i> to potentially download it. 815 * 816 * @param[in,out] handle Chat handle 817 * @param[in] uri Chat URI 818 * @return File handle on success, NULL on failure 819 */ 820 struct GNUNET_CHAT_File* 821 GNUNET_CHAT_request_file (struct GNUNET_CHAT_Handle *handle, 822 const struct GNUNET_CHAT_Uri *uri); 823 824 /** 825 * Uploads a local file specified via its <i>path</i> to share its uri 826 * with others afterwards. 827 * 828 * @param[in,out] handle Chat handle 829 * @param[in] path Local file path 830 * @param[in] callback Callback for file uploading (optional) 831 * @param[in,out] cls Closure for file uploading (optional) 832 * @return The file handle on success, NULL on failure 833 */ 834 struct GNUNET_CHAT_File* 835 GNUNET_CHAT_upload_file (struct GNUNET_CHAT_Handle *handle, 836 const char *path, 837 GNUNET_CHAT_FileUploadCallback callback, 838 void *cls); 839 840 /** 841 * Iterates through the files of a given chat <i>handle</i> with a selected 842 * callback and custom closure. 843 * 844 * @param[in,out] handle Chat handle 845 * @param[in] callback Callback for file iteration (optional) 846 * @param[in,out] cls Closure for file iteration (optional) 847 * @return Amount of files iterated or #GNUNET_SYSERR on failure 848 */ 849 int 850 GNUNET_CHAT_iterate_files (struct GNUNET_CHAT_Handle *handle, 851 GNUNET_CHAT_FileCallback callback, 852 void *cls); 853 854 /** 855 * Sets a custom <i>user pointer</i> to a given chat <i>handle</i> so it can 856 * be accessed in all handle related callbacks. 857 * 858 * @param[in,out] handle Chat handle 859 * @param[in] user_pointer Custom user pointer 860 */ 861 void 862 GNUNET_CHAT_set_user_pointer (struct GNUNET_CHAT_Handle *handle, 863 void *user_pointer); 864 865 /** 866 * Returns the custom user pointer of a given chat <i>handle</i> or NULL if it 867 * was not set any. 868 * 869 * @param[in] handle Chat handle 870 * @return Custom user pointer or NULL 871 */ 872 void* 873 GNUNET_CHAT_get_user_pointer (const struct GNUNET_CHAT_Handle *handle); 874 875 /** 876 * Iterates through the contacts of a given chat <i>handle</i> with a selected 877 * callback and custom closure. 878 * 879 * @param[in,out] handle Chat handle 880 * @param[in] callback Callback for contact iteration (optional) 881 * @param[in,out] cls Closure for contact iteration (optional) 882 * @return Amount of contacts iterated or #GNUNET_SYSERR on failure 883 */ 884 int 885 GNUNET_CHAT_iterate_contacts (struct GNUNET_CHAT_Handle *handle, 886 GNUNET_CHAT_ContactCallback callback, 887 void *cls); 888 889 /** 890 * Returns the chat contact matching a given chat <i>handle</i>'s current 891 * account. 892 * 893 * @param[in,out] handle Chat handle 894 * @return Chat contact or NULL 895 */ 896 struct GNUNET_CHAT_Contact* 897 GNUNET_CHAT_get_own_contact (struct GNUNET_CHAT_Handle *handle); 898 899 /** 900 * Returns the provided name of a given <i>account</i> or NULL on failure. 901 * 902 * @param[in] account Chat account 903 * @return Name or NULL 904 */ 905 const char* 906 GNUNET_CHAT_account_get_name (const struct GNUNET_CHAT_Account *account); 907 908 /** 909 * Calls an optional <i>callback</i> for each attribute of a given chat 910 * <i>account</i> using a chat <i>handle</i>. 911 * 912 * @param[in,out] handle Chat handle 913 * @param[in] account Chat account 914 * @param[in] callback Callback for attribute iteration (optional) 915 * @param[in,out] cls Closure for attribute iteration (optional) 916 */ 917 void 918 GNUNET_CHAT_account_get_attributes (struct GNUNET_CHAT_Handle *handle, 919 struct GNUNET_CHAT_Account *account, 920 GNUNET_CHAT_AccountAttributeCallback callback, 921 void *cls); 922 923 /** 924 * Sets a custom <i>user pointer</i> to a given chat <i>account</i> so it can 925 * be accessed in account related callbacks. 926 * 927 * @param[in,out] account Chat account 928 * @param[in] user_pointer Custom user pointer 929 */ 930 void 931 GNUNET_CHAT_account_set_user_pointer (struct GNUNET_CHAT_Account *account, 932 void *user_pointer); 933 934 /** 935 * Returns the custom user pointer of a given <i>contact</i> or NULL if it was 936 * not set any. 937 * 938 * @param[in] account Chat account 939 * @return Custom user pointer or NULL 940 */ 941 void* 942 GNUNET_CHAT_account_get_user_pointer (const struct GNUNET_CHAT_Account *account); 943 944 /** 945 * Creates a new group chat to use with a given chat <i>handle</i> with an 946 * optional public <i>topic</i>. 947 * 948 * If a specific <i>topic</i> is used, the created group will be publically 949 * available to join for others searching for the used topic. Otherwise the 950 * group will be private using a randomly generated key and others can only 951 * join the chat via a private invitation. 952 * 953 * @param[in,out] handle Chat handle 954 * @param[in] topic Public topic (optional) 955 * @return New group chat 956 */ 957 struct GNUNET_CHAT_Group* 958 GNUNET_CHAT_group_create (struct GNUNET_CHAT_Handle *handle, 959 const char* topic); 960 961 /** 962 * Iterates through the groups of a given chat <i>handle</i> with a selected 963 * callback and custom closure. 964 * 965 * @param[in,out] handle Chat handle 966 * @param[in] callback Callback for group iteration (optional) 967 * @param[in,out] cls Closure for group iteration (optional) 968 * @return Amount of groups iterated or #GNUNET_SYSERR on failure 969 */ 970 int 971 GNUNET_CHAT_iterate_groups (struct GNUNET_CHAT_Handle *handle, 972 GNUNET_CHAT_GroupCallback callback, 973 void *cls); 974 975 /** 976 * Leaves the private chat with a specific <i>contact</i> and frees the 977 * regarding memory of the contact if there remains no common chat with it. 978 * 979 * @param[in,out] contact Contact 980 */ 981 void 982 GNUNET_CHAT_contact_delete (struct GNUNET_CHAT_Contact *contact); 983 984 /** 985 * Overrides the name of a given <i>contact</i> with a custom nick <i>name</i> 986 * which will be only used locally. 987 * 988 * @param[in,out] contact Contact 989 * @param[in] name Custom nick name 990 */ 991 void 992 GNUNET_CHAT_contact_set_name (struct GNUNET_CHAT_Contact *contact, 993 const char *name); 994 995 /** 996 * Returns the provided name of a given <i>contact</i> or its custom nick name 997 * if it was overriden. 998 * 999 * @param[in] contact Contact 1000 * @return Name or custom nick name 1001 */ 1002 const char* 1003 GNUNET_CHAT_contact_get_name (const struct GNUNET_CHAT_Contact *contact); 1004 1005 /** 1006 * Returns the public key of the used ego by a specific <i>contact</i> to 1007 * verify signatures of sent messages. 1008 * 1009 * @param[in] contact Contact 1010 * @return Public key of the contacts ego or NULL 1011 */ 1012 const char* 1013 GNUNET_CHAT_contact_get_key (const struct GNUNET_CHAT_Contact *contact); 1014 1015 /** 1016 * Returns the chat context for a private chat with a given <i>contact</i>. 1017 * 1018 * @param[in,out] contact Contact 1019 * @return Chat context 1020 */ 1021 struct GNUNET_CHAT_Context* 1022 GNUNET_CHAT_contact_get_context (struct GNUNET_CHAT_Contact *contact); 1023 1024 /** 1025 * Sets a custom <i>user pointer</i> to a given <i>contact</i> so it can be 1026 * accessed in contact related callbacks. 1027 * 1028 * @param[in,out] contact Contact 1029 * @param[in] user_pointer Custom user pointer 1030 */ 1031 void 1032 GNUNET_CHAT_contact_set_user_pointer (struct GNUNET_CHAT_Contact *contact, 1033 void *user_pointer); 1034 1035 /** 1036 * Returns the custom user pointer of a given <i>contact</i> or NULL if it was 1037 * not set any. 1038 * 1039 * @param[in] contact Contact 1040 * @return Custom user pointer or NULL 1041 */ 1042 void* 1043 GNUNET_CHAT_contact_get_user_pointer (const struct GNUNET_CHAT_Contact *contact); 1044 1045 /** 1046 * Returns if a given <i>contact</i> is owned by the current account and whether 1047 * it has sent messages with. 1048 * 1049 * @param[in] contact Contact 1050 * @return #GNUNET_YES if the contact is owned, otherwise# GNUNET_NO 1051 * and #GNUNET_SYSERR on failure 1052 */ 1053 enum GNUNET_GenericReturnValue 1054 GNUNET_CHAT_contact_is_owned (const struct GNUNET_CHAT_Contact *contact); 1055 1056 /** 1057 * Blocks or unblocks a given <i>contact</i> by the current account. 1058 * 1059 * @param[in,out] contact Contact 1060 * @param[in] blocked #GNUNET_YES to block, #GNUNET_NO to unblock 1061 */ 1062 void 1063 GNUNET_CHAT_contact_set_blocked (struct GNUNET_CHAT_Contact *contact, 1064 enum GNUNET_GenericReturnValue blocked); 1065 1066 /** 1067 * Returns if a given <i>contact</i> is blocked by the current account and 1068 * whether messages of it should be filtered. 1069 * 1070 * @param[in] contact Contact 1071 * @return #GNUNET_YES if the contact is blocked, #GNUNET_SYSERR on failure and 1072 * #GNUNET_NO otherwise 1073 */ 1074 enum GNUNET_GenericReturnValue 1075 GNUNET_CHAT_contact_is_blocked (const struct GNUNET_CHAT_Contact *contact); 1076 1077 /** 1078 * Tags a given <i>contact</i> by the current account with a specific 1079 * <i>tag</i>. 1080 * 1081 * @param[in,out] contact Contact 1082 * @param[in] tag Tag 1083 */ 1084 void 1085 GNUNET_CHAT_contact_tag (struct GNUNET_CHAT_Contact *contact, 1086 const char *tag); 1087 1088 /** 1089 * Untags a given <i>contact</i> by the current account with a specific 1090 * <i>tag</i>. 1091 * 1092 * @param[in,out] contact Contact 1093 * @param[in] tag Tag 1094 */ 1095 void 1096 GNUNET_CHAT_contact_untag (struct GNUNET_CHAT_Contact *contact, 1097 const char *tag); 1098 1099 /** 1100 * Returns if a given <i>contact</i> is tagged by the current account with 1101 * a specific <i>tag</i>. 1102 * 1103 * @param[in] contact Contact 1104 * @param[in] tag Tag 1105 * @return #GNUNET_YES if the contact is tagged, #GNUNET_SYSERR on failure and 1106 * #GNUNET_NO otherwise 1107 */ 1108 enum GNUNET_GenericReturnValue 1109 GNUNET_CHAT_contact_is_tagged (const struct GNUNET_CHAT_Contact *contact, 1110 const char *tag); 1111 1112 /** 1113 * Calls an optional <i>callback</i> for each tag of a given chat 1114 * <i>contact</i>. 1115 * 1116 * @param[in] contact Chat contact 1117 * @param[in] callback Callback for tag iteration (optional) 1118 * @param[in,out] cls Closure for tag iteration (optional) 1119 * @return Amount of tags iterated or #GNUNET_SYSERR on failure 1120 */ 1121 int 1122 GNUNET_CHAT_contact_iterate_tags (struct GNUNET_CHAT_Contact *contact, 1123 GNUNET_CHAT_ContactTagCallback callback, 1124 void *cls); 1125 1126 /** 1127 * Calls an optional <i>callback</i> for each attribute of a given chat 1128 * <i>contact</i>. 1129 * 1130 * @param[in,out] contact Chat contact 1131 * @param[in] callback Callback for attribute iteration (optional) 1132 * @param[in,out] cls Closure for attribute iteration (optional) 1133 */ 1134 void 1135 GNUNET_CHAT_contact_get_attributes (struct GNUNET_CHAT_Contact *contact, 1136 GNUNET_CHAT_ContactAttributeCallback callback, 1137 void *cls); 1138 1139 /** 1140 * Leaves a specific <i>group</i> chat and frees its memory if it is not shared 1141 * with other groups or contacts. 1142 * 1143 * @param[in,out] group Group 1144 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1145 */ 1146 enum GNUNET_GenericReturnValue 1147 GNUNET_CHAT_group_leave (struct GNUNET_CHAT_Group *group); 1148 1149 /** 1150 * Sets the name of a given <i>group</i> to a custom nick <i>name</i> 1151 * which will be only used locally. 1152 * 1153 * @param[in,out] group Group 1154 * @param[in] name Custom nick name 1155 */ 1156 void 1157 GNUNET_CHAT_group_set_name (struct GNUNET_CHAT_Group *group, 1158 const char *name); 1159 1160 /** 1161 * Returns the custom nick name of a given <i>group</i> if it was overriden. 1162 * 1163 * @param[in] group Group 1164 * @return Custom nick name or NULL 1165 */ 1166 const char* 1167 GNUNET_CHAT_group_get_name (const struct GNUNET_CHAT_Group *group); 1168 1169 /** 1170 * Sets a custom <i>user pointer</i> to a given <i>group</i> so it can be 1171 * accessed in group related callbacks. 1172 * 1173 * @param[in,out] group Group 1174 * @param[in] user_pointer Custom user pointer 1175 */ 1176 void 1177 GNUNET_CHAT_group_set_user_pointer (struct GNUNET_CHAT_Group *group, 1178 void *user_pointer); 1179 1180 /** 1181 * Returns the custom user pointer of a given <i>group</i> or NULL if it was 1182 * not set any. 1183 * 1184 * @param[in] group Group 1185 * @return Custom user pointer or NULL 1186 */ 1187 void* 1188 GNUNET_CHAT_group_get_user_pointer (const struct GNUNET_CHAT_Group *group); 1189 1190 /** 1191 * Invites a specific <i>contact</i> to a given <i>group</i> via a privately 1192 * sent invitation. 1193 * 1194 * @param[in,out] group Group 1195 * @param[in,out] contact Contact 1196 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1197 */ 1198 enum GNUNET_GenericReturnValue 1199 GNUNET_CHAT_group_invite_contact (struct GNUNET_CHAT_Group *group, 1200 struct GNUNET_CHAT_Contact *contact); 1201 1202 /** 1203 * Iterates through the contacts of a given <i>group</i> with a selected 1204 * callback and custom closure. 1205 * 1206 * @param[in,out] group Group 1207 * @param[in] callback Callback for contact iteration (optional) 1208 * @param[in,out] cls Closure for contact iteration (optional) 1209 * @return Amount of contacts iterated or #GNUNET_SYSERR on failure 1210 */ 1211 int 1212 GNUNET_CHAT_group_iterate_contacts (struct GNUNET_CHAT_Group *group, 1213 GNUNET_CHAT_GroupContactCallback callback, 1214 void *cls); 1215 1216 /** 1217 * Sets a custom <i>user pointer</i> to a given <i>member</i> relative to a 1218 * <i>group</i> so it can be accessed in member related callbacks. 1219 * 1220 * @param[in,out] group Chat group 1221 * @param[in] member Contact 1222 * @param[in] user_pointer Custom user pointer 1223 */ 1224 void 1225 GNUNET_CHAT_member_set_user_pointer (struct GNUNET_CHAT_Group *group, 1226 const struct GNUNET_CHAT_Contact *member, 1227 void *user_pointer); 1228 1229 /** 1230 * Returns the custom user pointer of a given <i>member</i> relative to a 1231 * <i>group</i> or NULL if it was not set any. 1232 * 1233 * @param[in] group Chat group 1234 * @param[in] member Contact 1235 * @return Custom user pointer or NULL 1236 */ 1237 void* 1238 GNUNET_CHAT_member_get_user_pointer (const struct GNUNET_CHAT_Group *group, 1239 const struct GNUNET_CHAT_Contact *member); 1240 1241 /** 1242 * Returns the chat context for a chat with a given <i>group</i>. 1243 * 1244 * @param[in,out] group Group 1245 * @return Chat context 1246 */ 1247 struct GNUNET_CHAT_Context* 1248 GNUNET_CHAT_group_get_context (struct GNUNET_CHAT_Group *group); 1249 1250 /** 1251 * Returns the current status of a given <i>context</i> whether it is usable 1252 * or not to communicate with other contacts. 1253 * 1254 * @param[in] context Context 1255 * @return #GNUNET_OK if usable, #GNUNET_NO if the context has been requested, 1256 * #GNUNET_SYSERR otherwise. 1257 */ 1258 enum GNUNET_GenericReturnValue 1259 GNUNET_CHAT_context_get_status (struct GNUNET_CHAT_Context *context); 1260 1261 /** 1262 * Requests a <i>context</i> to get established between all required contacts. 1263 * The current status of this request can be tracked via 1264 * #GNUNET_CHAT_context_get_status() and will only change through the 1265 * receivement of new messages. 1266 * 1267 * @param[in,out] context Context 1268 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1269 */ 1270 enum GNUNET_GenericReturnValue 1271 GNUNET_CHAT_context_request (struct GNUNET_CHAT_Context *context); 1272 1273 /** 1274 * Returns the chat contact which uses a given <i>context</i>. 1275 * 1276 * @param[in] context Context 1277 * @return Chat contact 1278 */ 1279 struct GNUNET_CHAT_Contact* 1280 GNUNET_CHAT_context_get_contact (struct GNUNET_CHAT_Context *context); 1281 1282 /** 1283 * Returns the chat group which uses a given <i>context</i>. 1284 * 1285 * @param[in] context Context 1286 * @return Chat group 1287 */ 1288 struct GNUNET_CHAT_Group* 1289 GNUNET_CHAT_context_get_group (struct GNUNET_CHAT_Context *context); 1290 1291 /** 1292 * Sets a custom <i>user pointer</i> to a given chat <i>context</i> so it can 1293 * be accessed in chat context related callbacks. 1294 * 1295 * @param[in,out] context Chat context 1296 * @param[in] user_pointer Custom user pointer 1297 */ 1298 void 1299 GNUNET_CHAT_context_set_user_pointer (struct GNUNET_CHAT_Context *context, 1300 void *user_pointer); 1301 1302 /** 1303 * Returns the custom user pointer of a given chat <i>context</i> or NULL if it 1304 * was not set any. 1305 * 1306 * @param[in] context Chat context 1307 * @return Custom user pointer or NULL 1308 */ 1309 void* 1310 GNUNET_CHAT_context_get_user_pointer (const struct GNUNET_CHAT_Context *context); 1311 1312 /** 1313 * Sends a selected <i>text</i> into a given chat <i>context</i>. 1314 * 1315 * @param[in,out] context Chat context 1316 * @param[in] text Text 1317 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1318 */ 1319 enum GNUNET_GenericReturnValue 1320 GNUNET_CHAT_context_send_text (struct GNUNET_CHAT_Context *context, 1321 const char *text); 1322 1323 /** 1324 * Sends a read receipt depending on a selected <i>message</i> into a given 1325 * chat <i>context</i>. 1326 * 1327 * @param[in,out] context Chat context 1328 * @param[in,out] message Message (optional) 1329 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1330 */ 1331 enum GNUNET_GenericReturnValue 1332 GNUNET_CHAT_context_send_read_receipt (struct GNUNET_CHAT_Context *context, 1333 struct GNUNET_CHAT_Message *message); 1334 1335 /** 1336 * Uploads a local file specified via its <i>path</i> using symmetric encryption 1337 * and shares the regarding information to download and decrypt it in a given 1338 * chat <i>context</i>. 1339 * 1340 * @param[in,out] context Chat context 1341 * @param[in] path Local file path 1342 * @param[in] callback Callback for file uploading (optional) 1343 * @param[in,out] cls Closure for file uploading (optional) 1344 * @return The file handle on success, NULL on failure 1345 */ 1346 struct GNUNET_CHAT_File* 1347 GNUNET_CHAT_context_send_file (struct GNUNET_CHAT_Context *context, 1348 const char *path, 1349 GNUNET_CHAT_FileUploadCallback callback, 1350 void *cls); 1351 1352 /** 1353 * Shares the information to download and decrypt a specific <i>file</i> from 1354 * another chat in a given chat <i>context</i>. 1355 * 1356 * @param[in,out] context Chat context 1357 * @param[in,out] file File handle 1358 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1359 */ 1360 enum GNUNET_GenericReturnValue 1361 GNUNET_CHAT_context_share_file (struct GNUNET_CHAT_Context *context, 1362 struct GNUNET_CHAT_File *file); 1363 1364 /** 1365 * Sends a tag message targeting a selected <i>message</i> into a given 1366 * chat <i>context</i> with a given <i>tag</i> value. 1367 * 1368 * @param[in,out] context Chat context 1369 * @param[in,out] message Message 1370 * @param[in] tag Tag value 1371 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1372 */ 1373 enum GNUNET_GenericReturnValue 1374 GNUNET_CHAT_context_send_tag (struct GNUNET_CHAT_Context *context, 1375 struct GNUNET_CHAT_Message *message, 1376 const char *tag); 1377 1378 /** 1379 * Opens a chat discourse under a specific <i>id</i> in a given chat 1380 * <i>context</i> to send data live to other contacts. 1381 * 1382 * @param[in,out] context Chat context 1383 * @param[in] id Discourse id 1384 * @return Chat discourse 1385 */ 1386 struct GNUNET_CHAT_Discourse* 1387 GNUNET_CHAT_context_open_discourse (struct GNUNET_CHAT_Context *context, 1388 const struct GNUNET_CHAT_DiscourseId *id); 1389 1390 /** 1391 * Iterates through the contacts of a given chat <i>context</i> with a selected 1392 * callback and custom closure. 1393 * 1394 * @param[in,out] context Chat context 1395 * @param[in] callback Callback for contact iteration (optional) 1396 * @param[in,out] cls Closure for contact iteration (optional) 1397 * @return Amount of contacts iterated or #GNUNET_SYSERR on failure 1398 */ 1399 int 1400 GNUNET_CHAT_context_iterate_messages (struct GNUNET_CHAT_Context *context, 1401 GNUNET_CHAT_ContextMessageCallback callback, 1402 void *cls); 1403 1404 /** 1405 * Iterates through the files of a given chat <i>context</i> with a selected 1406 * callback and custom closure. 1407 * 1408 * @param[in,out] context Chat context 1409 * @param[in] callback Callback for file iteration (optional) 1410 * @param[in,out] cls Closure for file iteration (optional) 1411 * @return Amount of files iterated or #GNUNET_SYSERR on failure 1412 */ 1413 int 1414 GNUNET_CHAT_context_iterate_files (struct GNUNET_CHAT_Context *context, 1415 GNUNET_CHAT_ContextFileCallback callback, 1416 void *cls); 1417 1418 /** 1419 * Iterates through the discourses of a given chat <i>context</i> with a 1420 * selected callback and custom closure. 1421 * 1422 * @param[in,out] context Chat context 1423 * @param[in] callback Callback for file iteration (optional) 1424 * @param[in,out] cls Closure for file iteration (optional) 1425 * @return Amount of discourses iterated or #GNUNET_SYSERR on failure 1426 */ 1427 int 1428 GNUNET_CHAT_context_iterate_discourses (struct GNUNET_CHAT_Context *context, 1429 GNUNET_CHAT_DiscourseCallback callback, 1430 void *cls); 1431 1432 /** 1433 * Returns the kind of a given <i>message</i> to determine its content and 1434 * related usage. 1435 * 1436 * @param[in] message Message 1437 * @return The kind of message 1438 */ 1439 enum GNUNET_CHAT_MessageKind 1440 GNUNET_CHAT_message_get_kind (const struct GNUNET_CHAT_Message *message); 1441 1442 /** 1443 * Returns the timestamp of a given <i>message</i> in absolute measure. 1444 * 1445 * @param[in] message Message 1446 * @return The timestamp of message 1447 */ 1448 time_t 1449 GNUNET_CHAT_message_get_timestamp (const struct GNUNET_CHAT_Message *message); 1450 1451 /** 1452 * Returns the contact of the sender from a given <i>message</i>. 1453 * 1454 * @param[in] message Message 1455 * @return Contact of the messages sender 1456 */ 1457 struct GNUNET_CHAT_Contact* 1458 GNUNET_CHAT_message_get_sender (const struct GNUNET_CHAT_Message *message); 1459 1460 /** 1461 * Returns the contact of the recipient from a given <i>message</i>. 1462 * 1463 * @param[in] message Message 1464 * @return Contact of the messages recipient or NULL 1465 */ 1466 struct GNUNET_CHAT_Contact* 1467 GNUNET_CHAT_message_get_recipient (const struct GNUNET_CHAT_Message *message); 1468 1469 /** 1470 * Returns #GNUNET_YES if the <i>message</i> was sent by the related chat 1471 * handle, otherwise it returns #GNUNET_NO. 1472 * 1473 * @param[in] message Message 1474 * @return #GNUNET_YES if the message was sent, otherwise #GNUNET_NO 1475 */ 1476 enum GNUNET_GenericReturnValue 1477 GNUNET_CHAT_message_is_sent (const struct GNUNET_CHAT_Message *message); 1478 1479 /** 1480 * Returns #GNUNET_YES if the <i>message</i> was received privately encrypted 1481 * by the related chat handle, otherwise it returns #GNUNET_NO. 1482 * 1483 * @param[in] message Message 1484 * @return #GNUNET_YES if the message was privately received, 1485 * otherwise #GNUNET_NO 1486 */ 1487 enum GNUNET_GenericReturnValue 1488 GNUNET_CHAT_message_is_private (const struct GNUNET_CHAT_Message *message); 1489 1490 /** 1491 * Returns #GNUNET_YES if the <i>message</i> was received recently by related 1492 * chat handle, otherwise it returns #GNUNET_NO. 1493 * 1494 * @param[in] message Message 1495 * @return #GNUNET_YES if the message was received recently, 1496 * otherwise #GNUNET_NO 1497 */ 1498 enum GNUNET_GenericReturnValue 1499 GNUNET_CHAT_message_is_recent (const struct GNUNET_CHAT_Message *message); 1500 1501 /** 1502 * Returns #GNUNET_YES if the <i>message</i> was received because of an 1503 * update by related chat handle, otherwise it returns #GNUNET_NO. 1504 * 1505 * @param[in] message Message 1506 * @return #GNUNET_YES if the message was received to update 1507 * a previous message, otherwise #GNUNET_NO 1508 */ 1509 enum GNUNET_GenericReturnValue 1510 GNUNET_CHAT_message_is_update (const struct GNUNET_CHAT_Message *message); 1511 1512 /** 1513 * Returns #GNUNET_YES if the <i>message</i> was received because of a 1514 * deletion by related chat handle or if it has been deleted internally, 1515 * otherwise it returns #GNUNET_NO. 1516 * 1517 * @param[in] message Message 1518 * @return #GNUNET_YES if the message was received to delete 1519 * a previous message, otherwise #GNUNET_NO 1520 */ 1521 enum GNUNET_GenericReturnValue 1522 GNUNET_CHAT_message_is_deleted (const struct GNUNET_CHAT_Message *message); 1523 1524 /** 1525 * Returns #GNUNET_YES if the <i>message</i> was tagged with a custom 1526 * <i>tag</i> value, otherwise it returns #GNUNET_NO. 1527 * 1528 * @param[in] message Message 1529 * @return #GNUNET_YES if the message was tagged with 1530 * the given tag value, otherwise #GNUNET_NO 1531 */ 1532 enum GNUNET_GenericReturnValue 1533 GNUNET_CHAT_message_is_tagged (const struct GNUNET_CHAT_Message *message, 1534 const char *tag); 1535 1536 /** 1537 * Iterates through the contacts of the context related to a given chat 1538 * <i>message</i> to check whether it was received by each of the contacts. 1539 * 1540 * @param[in,out] message Message 1541 * @param[in] callback Callback for contact iteration (optional) 1542 * @param[in,out] cls Closure for contact iteration (optional) 1543 * @return Amount of contacts iterated or #GNUNET_SYSERR on failure 1544 */ 1545 int 1546 GNUNET_CHAT_message_get_read_receipt (struct GNUNET_CHAT_Message *message, 1547 GNUNET_CHAT_MessageReadReceiptCallback callback, 1548 void *cls); 1549 1550 /** 1551 * Returns the text of a given <i>message</i> if its kind is 1552 * #GNUNET_CHAT_KIND_TEXT or #GNUNET_CHAT_KIND_WARNING, 1553 * otherwise it returns NULL. 1554 * 1555 * @param[in] message Message 1556 * @return The text of message or NULL 1557 */ 1558 const char* 1559 GNUNET_CHAT_message_get_text (const struct GNUNET_CHAT_Message *message); 1560 1561 /** 1562 * Sets a custom <i>user pointer</i> to a given <i>message</i> so it can 1563 * be accessed in message related callbacks. 1564 * 1565 * @param[in,out] message Message 1566 * @param[in] user_pointer Custom user pointer 1567 */ 1568 void 1569 GNUNET_CHAT_message_set_user_pointer (struct GNUNET_CHAT_Message *message, 1570 void *user_pointer); 1571 1572 /** 1573 * Returns the custom user pointer of a given <i>message</i> or NULL if it 1574 * was not set any. 1575 * 1576 * @param[in] message Message 1577 * @return Custom user pointer 1578 */ 1579 void* 1580 GNUNET_CHAT_message_get_user_pointer (const struct GNUNET_CHAT_Message *message); 1581 1582 /** 1583 * Returns the account of a given <i>message</i> which is either 1584 * its sender or target of the message depending on the kind of 1585 * the message, otherwise it returns NULL. 1586 * 1587 * @param[in] message Message 1588 * @return The account of message or NULL 1589 */ 1590 struct GNUNET_CHAT_Account* 1591 GNUNET_CHAT_message_get_account (const struct GNUNET_CHAT_Message *message); 1592 1593 /** 1594 * Returns the file handle of a given <i>message</i> if its kind is 1595 * #GNUNET_CHAT_KIND_FILE, otherwise it returns NULL. 1596 * 1597 * @param[in] message Message 1598 * @return The file handle of message or NULL 1599 */ 1600 struct GNUNET_CHAT_File* 1601 GNUNET_CHAT_message_get_file (const struct GNUNET_CHAT_Message *message); 1602 1603 /** 1604 * Returns the invitation of a given <i>message</i> if its kind is 1605 * #GNUNET_CHAT_KIND_INVITATION, otherwise it returns NULL. 1606 * 1607 * @param[in] message Message 1608 * @return The invitation of message or NULL 1609 */ 1610 struct GNUNET_CHAT_Invitation* 1611 GNUNET_CHAT_message_get_invitation (const struct GNUNET_CHAT_Message *message); 1612 1613 /** 1614 * Returns the discourse of a given <i>message</i> if its kind is 1615 * #GNUNET_CHAT_KIND_DISCOURSE or #GNUNET_CHAT_KIND_DATA, 1616 * otherwise it returns NULL. 1617 * 1618 * @param[in] message Message 1619 * @return The discourse of message or NULL 1620 */ 1621 struct GNUNET_CHAT_Discourse* 1622 GNUNET_CHAT_message_get_discourse (const struct GNUNET_CHAT_Message *message); 1623 1624 /** 1625 * Returns the target message of an operation represented by a given 1626 * <i>message</i> if its kind is #GNUNET_CHAT_KIND_DELETION, otherwise it 1627 * returns NULL. 1628 * 1629 * @param[in] message Message 1630 * @return The target of message or NULL 1631 */ 1632 struct GNUNET_CHAT_Message* 1633 GNUNET_CHAT_message_get_target (const struct GNUNET_CHAT_Message *message); 1634 1635 /** 1636 * Deletes a given <i>message</i> with a specific relative <i>delay</i> 1637 * in seconds. 1638 * 1639 * @param[in,out] message Message 1640 * @param[in] delay Relative delay 1641 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1642 */ 1643 enum GNUNET_GenericReturnValue 1644 GNUNET_CHAT_message_delete (struct GNUNET_CHAT_Message *message, 1645 unsigned int delay); 1646 1647 /** 1648 * Iterates through the tag messages in the context of a given 1649 * <i>message</i>. 1650 * 1651 * @param[in,out] message Message 1652 * @param[in] callback Callback for tag message iteration (optional) 1653 * @param[in,out] cls Closure for tag message iteration (optional) 1654 * @return Amount of tag messages iterated or #GNUNET_SYSERR on failure 1655 */ 1656 int 1657 GNUNET_CHAT_message_iterate_tags (struct GNUNET_CHAT_Message *message, 1658 GNUNET_CHAT_MessageCallback callback, 1659 void *cls); 1660 1661 /** 1662 * Returns the amount of data from a given chat <i>message</i> if its 1663 * kind is #GNUNET_CHAT_KIND_DATA, otherwise it returns zero. 1664 * 1665 * @param[in] message Message 1666 * @return The amount of data or zero 1667 */ 1668 uint64_t 1669 GNUNET_CHAT_message_available (const struct GNUNET_CHAT_Message *message); 1670 1671 /** 1672 * Reads the data from a given chat <i>message</i> if its kind is 1673 * #GNUNET_CHAT_KIND_DATA into a specific <i>data</i> buffer 1674 * up to a selected <i>size</i>. 1675 * 1676 * @param[in] message Message 1677 * @param[out] data Data buffer 1678 * @param[in] size Data size 1679 * @return #GNUNET_OK on success, #GNUNET_NO if there's missing data 1680 * to read, otherwise #GNUNET_SYSERR on failure 1681 */ 1682 enum GNUNET_GenericReturnValue 1683 GNUNET_CHAT_message_read (const struct GNUNET_CHAT_Message *message, 1684 char *data, 1685 uint64_t size); 1686 1687 /** 1688 * Feeds the data from a given chat <i>message</i> if its kind is 1689 * #GNUNET_CHAT_KIND_DATA into a specific file descriptor (of pipe for 1690 * example). 1691 * 1692 * @param[in] message Message 1693 * @param[in] fd File descriptor 1694 * @return #GNUNET_OK on success, #GNUNET_NO if there's not enough data 1695 * to read, otherwise #GNUNET_SYSERR on failure 1696 */ 1697 enum GNUNET_GenericReturnValue 1698 GNUNET_CHAT_message_feed (const struct GNUNET_CHAT_Message *message, 1699 int fd); 1700 1701 /** 1702 * Returns the name of a given <i>file</i> handle. 1703 * 1704 * @param[in] file File handle 1705 * @return The file name of file 1706 */ 1707 const char* 1708 GNUNET_CHAT_file_get_name (const struct GNUNET_CHAT_File *file); 1709 1710 /** 1711 * Returns the hash of a given <i>file</i> handle. 1712 * 1713 * @param[in] file File handle 1714 * @return The hash of file 1715 */ 1716 const char* 1717 GNUNET_CHAT_file_get_hash (const struct GNUNET_CHAT_File *file); 1718 1719 /** 1720 * Returns the actual file size of a given <i>file</i> handle. 1721 * 1722 * @param[in] file File handle 1723 * @return The file size of file 1724 */ 1725 uint64_t 1726 GNUNET_CHAT_file_get_size (const struct GNUNET_CHAT_File *file); 1727 1728 /** 1729 * Returns the local file size of a given <i>file</i> handle. 1730 * 1731 * This can be less than the actual size of the file once its download 1732 * has been completed! 1733 * 1734 * @param[in] file File handle 1735 * @return The local file size of file 1736 */ 1737 uint64_t 1738 GNUNET_CHAT_file_get_local_size (const struct GNUNET_CHAT_File *file); 1739 1740 /** 1741 * Returns a new allocated uri to access the content of a given 1742 * <i>file</i> handle. 1743 * 1744 * @param[in] file File handle 1745 * @return URI on success, NULL on error 1746 */ 1747 struct GNUNET_CHAT_Uri* 1748 GNUNET_CHAT_file_get_uri (const struct GNUNET_CHAT_File *file); 1749 1750 /** 1751 * Returns if a given <i>file</i> handle is currently uploading. 1752 * 1753 * @param[in] file File handle 1754 * @return #GNUNET_YES during active upload, #GNUNET_NO otherwise 1755 */ 1756 enum GNUNET_GenericReturnValue 1757 GNUNET_CHAT_file_is_uploading (const struct GNUNET_CHAT_File *file); 1758 1759 /** 1760 * Returns if a given <i>file</i> handle is currently ready 1761 * for previewing its content. 1762 * 1763 * @param[in] file File handle 1764 * @return #GNUNET_YES when ready, #GNUNET_NO otherwise 1765 */ 1766 enum GNUNET_GenericReturnValue 1767 GNUNET_CHAT_file_is_ready (const struct GNUNET_CHAT_File *file); 1768 1769 /** 1770 * Returns the temporary file name of the decrypted file preview 1771 * of a given <i>file</i> handle. 1772 * 1773 * This can only be used when the file handle is ready to preview! 1774 * @see GNUNET_CHAT_file_is_ready() 1775 * 1776 * @param[in,out] file File handle 1777 * @return The temporary file name or NULL on error 1778 */ 1779 const char* 1780 GNUNET_CHAT_file_open_preview (struct GNUNET_CHAT_File *file); 1781 1782 /** 1783 * Deletes the temporary decrypted file preview of a given <i>file</i> 1784 * handle. 1785 * 1786 * This can only be used when the file handle is ready to preview! 1787 * @see GNUNET_CHAT_file_is_ready() 1788 * 1789 * @param[out] file File handle 1790 */ 1791 void 1792 GNUNET_CHAT_file_close_preview (struct GNUNET_CHAT_File *file); 1793 1794 /** 1795 * Sets a custom <i>user pointer</i> to a given <i>file</i> handle so it can 1796 * be accessed in file related callbacks. 1797 * 1798 * @param[in,out] file File handle 1799 * @param[in] user_pointer Custom user pointer 1800 */ 1801 void 1802 GNUNET_CHAT_file_set_user_pointer (struct GNUNET_CHAT_File *file, 1803 void *user_pointer); 1804 1805 /** 1806 * Returns the custom user pointer of a given <i>file</i> handle or NULL if it 1807 * was not set any. 1808 * 1809 * @param[in] file File handle 1810 * @return Custom user pointer 1811 */ 1812 void* 1813 GNUNET_CHAT_file_get_user_pointer (const struct GNUNET_CHAT_File *file); 1814 1815 /** 1816 * Returns if a given <i>file</i> handle is currently downloading. 1817 * 1818 * @param[in] file File handle 1819 * @return #GNUNET_YES during active download, #GNUNET_NO otherwise 1820 */ 1821 enum GNUNET_GenericReturnValue 1822 GNUNET_CHAT_file_is_downloading (const struct GNUNET_CHAT_File *file); 1823 1824 /** 1825 * Starts downloading a file from a given <i>file</i> handle and sets up a 1826 * selected callback and custom closure for its progress. 1827 * 1828 * @param[in,out] file File handle 1829 * @param[in] callback Callback for file downloading (optional) 1830 * @param[in,out] cls Closure for file downloading (optional) 1831 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1832 */ 1833 enum GNUNET_GenericReturnValue 1834 GNUNET_CHAT_file_start_download (struct GNUNET_CHAT_File *file, 1835 GNUNET_CHAT_FileDownloadCallback callback, 1836 void *cls); 1837 1838 /** 1839 * Pause downloading a file from a given <i>file</i> handle. 1840 * 1841 * @param[in,out] file File handle 1842 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1843 */ 1844 enum GNUNET_GenericReturnValue 1845 GNUNET_CHAT_file_pause_download (struct GNUNET_CHAT_File *file); 1846 1847 /** 1848 * Resume downloading a file from a given <i>file</i> handle. 1849 * 1850 * @param[in,out] file File handle 1851 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1852 */ 1853 enum GNUNET_GenericReturnValue 1854 GNUNET_CHAT_file_resume_download (struct GNUNET_CHAT_File *file); 1855 1856 /** 1857 * Stops downloading a file from a given <i>file</i> handle. 1858 * 1859 * @param[in,out] file File handle 1860 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1861 */ 1862 enum GNUNET_GenericReturnValue 1863 GNUNET_CHAT_file_stop_download (struct GNUNET_CHAT_File *file); 1864 1865 /** 1866 * Returns if a given <i>file</i> handle is currently unindexing. 1867 * 1868 * @param[in] file File handle 1869 * @return #GNUNET_YES during active unindexing, #GNUNET_NO otherwise 1870 */ 1871 enum GNUNET_GenericReturnValue 1872 GNUNET_CHAT_file_is_unindexing (const struct GNUNET_CHAT_File *file); 1873 1874 /** 1875 * Unindexes an uploaded file from a given <i>file</i> handle with a selected 1876 * callback and a custom closure. 1877 * 1878 * @param[in,out] file File handle 1879 * @param[in] callback Callback for file unindexing (optional) 1880 * @param[in,out] cls Closure for file unindexing (optional) 1881 * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure 1882 */ 1883 enum GNUNET_GenericReturnValue 1884 GNUNET_CHAT_file_unindex (struct GNUNET_CHAT_File *file, 1885 GNUNET_CHAT_FileUnindexCallback callback, 1886 void *cls); 1887 1888 /** 1889 * Accepts a given chat <i>invitation</i> to enter another chat. 1890 * 1891 * @param[in,out] invitation Chat invitation 1892 */ 1893 void 1894 GNUNET_CHAT_invitation_accept (struct GNUNET_CHAT_Invitation *invitation); 1895 1896 /** 1897 * Rejects a given chat <i>invitation</i> to enter another chat. 1898 * 1899 * @param[in,out] invitation Chat invitation 1900 */ 1901 void 1902 GNUNET_CHAT_invitation_reject (struct GNUNET_CHAT_Invitation *invitation); 1903 1904 /** 1905 * Returns if a given <i>invitation</i> got accepted. 1906 * 1907 * @param[in] invitation Chat invitation 1908 * @return #GNUNET_YES if accepted, #GNUNET_NO otherwise 1909 */ 1910 enum GNUNET_GenericReturnValue 1911 GNUNET_CHAT_invitation_is_accepted (const struct GNUNET_CHAT_Invitation *invitation); 1912 1913 /** 1914 * Returns if a given <i>invitation</i> got rejected. 1915 * 1916 * @param[in] invitation Chat invitation 1917 * @return #GNUNET_YES if rejected, #GNUNET_NO otherwise 1918 */ 1919 enum GNUNET_GenericReturnValue 1920 GNUNET_CHAT_invitation_is_rejected (const struct GNUNET_CHAT_Invitation *invitation); 1921 1922 /** 1923 * Returns whether the intend from a given 1924 * <i>invitation</i>. is to open a direct chat or 1925 * a group chat. 1926 * 1927 * @param[in] invitation Chat invitation 1928 * @return #GNUNET_YES if it is a direct chat request, #GNUNET_NO otherwise 1929 */ 1930 enum GNUNET_GenericReturnValue 1931 GNUNET_CHAT_invitation_is_direct (const struct GNUNET_CHAT_Invitation *invitation); 1932 1933 /** 1934 * Returns the discourse id of a given chat <i>discourse</i>. 1935 * 1936 * @param[in] discourse Chat discourse 1937 * @return Discourse id 1938 */ 1939 const struct GNUNET_CHAT_DiscourseId* 1940 GNUNET_CHAT_discourse_get_id (const struct GNUNET_CHAT_Discourse *discourse); 1941 1942 /** 1943 * Returns whether a chat <i>discourse</i> is currently open. 1944 * 1945 * @param[in] discourse Chat discourse 1946 * @return #GNUNET_YES if the discourse is open, #GNUNET_SYSERR on failure and 1947 * #GNUNET_NO otherwise. 1948 */ 1949 enum GNUNET_GenericReturnValue 1950 GNUNET_CHAT_discourse_is_open (const struct GNUNET_CHAT_Discourse *discourse); 1951 1952 /** 1953 * Sets a custom <i>user pointer</i> to a given chat <i>discourse</i> so it can 1954 * be accessed in chat discourse related callbacks. 1955 * 1956 * @param[in,out] discourse Chat discourse 1957 * @param[in] user_pointer Custom user pointer 1958 */ 1959 void 1960 GNUNET_CHAT_discourse_set_user_pointer (struct GNUNET_CHAT_Discourse *discourse, 1961 void *user_pointer); 1962 1963 /** 1964 * Returns the custom user pointer of a given chat <i>discourse</i> or NULL if it 1965 * was not set any. 1966 * 1967 * @param[in] discourse Chat discourse 1968 * @return Custom user pointer or NULL 1969 */ 1970 void* 1971 GNUNET_CHAT_discourse_get_user_pointer (const struct GNUNET_CHAT_Discourse *discourse); 1972 1973 /** 1974 * Closes a given chat <i>discourse</i> to stop receiving any data messages 1975 * from the specific discourse. 1976 * 1977 * @param[in,out] discourse Chat discourse 1978 */ 1979 void 1980 GNUNET_CHAT_discourse_close (struct GNUNET_CHAT_Discourse *discourse); 1981 1982 /** 1983 * Sends messages to a given chat <i>discourse</i> containing the 1984 * specified <i>data</i> of a custom <i>size</i> in bytes. 1985 * 1986 * @param[in,out] discourse Chat discourse 1987 * @param[in] data Data buffer 1988 * @param[in] size Data size 1989 * @return #GNUNET_OK on success, otherwise #GNUNET_SYSERR 1990 */ 1991 enum GNUNET_GenericReturnValue 1992 GNUNET_CHAT_discourse_write (struct GNUNET_CHAT_Discourse *discourse, 1993 const char *data, 1994 uint64_t size); 1995 1996 /** 1997 * Returns a file descriptor of a pipe to write data via IPC 1998 * into the given chat <i>discourse</i>. 1999 * 2000 * @param[in] discourse Chat discourse 2001 * @return File descriptor of pipe end or #GNUNET_SYSERR on failure 2002 */ 2003 int 2004 GNUNET_CHAT_discourse_get_fd (const struct GNUNET_CHAT_Discourse *discourse); 2005 2006 /** 2007 * Iterates through the subscribed chat contacts of a given chat <i>discourse</i> 2008 * with a selected callback and custom closure. 2009 * 2010 * @param[in,out] discourse Chat discourse 2011 * @param[in] callback Callback for contact iteration (optional) 2012 * @param[in,out] cls Closure for contact iteration (optional) 2013 * @return Amount of contacts iterated or #GNUNET_SYSERR on failure 2014 */ 2015 int 2016 GNUNET_CHAT_discourse_iterate_contacts (struct GNUNET_CHAT_Discourse *discourse, 2017 GNUNET_CHAT_DiscourseContactCallback callback, 2018 void *cls); 2019 2020 /**@}*/ 2021 2022 #endif /* GNUNET_CHAT_LIB_H_ */