From ca912f85dae6b61dd80ab02d0e3f0b20a556da7c Mon Sep 17 00:00:00 2001 From: TheJackiMonster Date: Thu, 12 Nov 2020 20:58:07 +0100 Subject: -remerge branch 'jacki/messenger' This reverts commit e11d1e59e4ae5f7d89c33df3ae9ca8f1ece990cf. --- src/include/gnunet_messenger_service.h | 436 +++++++++++++++++++++++++++++++++ 1 file changed, 436 insertions(+) create mode 100644 src/include/gnunet_messenger_service.h (limited to 'src/include/gnunet_messenger_service.h') diff --git a/src/include/gnunet_messenger_service.h b/src/include/gnunet_messenger_service.h new file mode 100644 index 000000000..8f5315c30 --- /dev/null +++ b/src/include/gnunet_messenger_service.h @@ -0,0 +1,436 @@ +/* + This file is part of GNUnet. + Copyright (C) 2020 GNUnet e.V. + + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. + + GNUnet is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + + SPDX-License-Identifier: AGPL3.0-or-later + */ +/** + * @author Tobias Frisch + * + * @file + * MESSENGER service; manages decentralized chat groups + * + * @defgroup messenger MESSENGER service + * Instant messaging based on the CADET subsystem + * + * @{ + */ + +#ifndef GNUNET_MESSENGER_SERVICE_H +#define GNUNET_MESSENGER_SERVICE_H + +#ifdef __cplusplus +extern "C" { +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +#include "platform.h" +#include "gnunet_configuration_lib.h" +#include "gnunet_crypto_lib.h" +#include "gnunet_identity_service.h" +#include "gnunet_mq_lib.h" +#include "gnunet_protocols.h" +#include "gnunet_scheduler_lib.h" +#include "gnunet_time_lib.h" + +#define GNUNET_MESSENGER_SERVICE_NAME "messenger" + +/** + * Opaque handle to the messenger + */ +struct GNUNET_MESSENGER_Handle; + +/** + * Opaque handle to a room + */ +struct GNUNET_MESSENGER_Room; + +/** + * Opaque handle to a contact + */ +struct GNUNET_MESSENGER_Contact; + +/** + * Enum for the different supported kinds of messages + */ +enum GNUNET_MESSENGER_MessageKind +{ + GNUNET_MESSENGER_KIND_INFO = 1, + + GNUNET_MESSENGER_KIND_JOIN = 2, + GNUNET_MESSENGER_KIND_LEAVE = 3, + + GNUNET_MESSENGER_KIND_NAME = 4, + GNUNET_MESSENGER_KIND_KEY = 5, + GNUNET_MESSENGER_KIND_PEER = 6, + GNUNET_MESSENGER_KIND_ID = 7, + + GNUNET_MESSENGER_KIND_MISS = 8, + GNUNET_MESSENGER_KIND_MERGE = 9, + GNUNET_MESSENGER_KIND_REQUEST = 10, + + GNUNET_MESSENGER_KIND_INVITE = 11, + GNUNET_MESSENGER_KIND_TEXT = 12, + GNUNET_MESSENGER_KIND_FILE = 13, + + GNUNET_MESSENGER_KIND_PRIVATE = 14, + + GNUNET_MESSENGER_KIND_UNKNOWN = 0 +}__attribute__((__packed__)); + +/** + * Get the name of a message kind. + * + * @param kind Kind of a message + * @return Name of that kind + */ +const char* +GNUNET_MESSENGER_name_of_kind (enum GNUNET_MESSENGER_MessageKind kind); + +struct GNUNET_MESSENGER_MessageHeader +{ + struct GNUNET_IDENTITY_Signature signature; + + struct GNUNET_TIME_AbsoluteNBO timestamp; + + struct GNUNET_ShortHashCode sender_id; + struct GNUNET_HashCode previous; + + enum GNUNET_MESSENGER_MessageKind kind; +}; + +struct GNUNET_MESSENGER_MessageInfo +{ + struct GNUNET_IDENTITY_PublicKey host_key; + struct GNUNET_ShortHashCode unique_id; +}; + +struct GNUNET_MESSENGER_MessageJoin +{ + struct GNUNET_IDENTITY_PublicKey key; +}; + +struct GNUNET_MESSENGER_MessageLeave +{ +}; + +struct GNUNET_MESSENGER_MessageName +{ + char *name; +}; + +struct GNUNET_MESSENGER_MessageKey +{ + struct GNUNET_IDENTITY_PublicKey key; +}; + +struct GNUNET_MESSENGER_MessagePeer +{ + struct GNUNET_PeerIdentity peer; +}; + +struct GNUNET_MESSENGER_MessageId +{ + struct GNUNET_ShortHashCode id; +}; + +struct GNUNET_MESSENGER_MessageMiss +{ + struct GNUNET_PeerIdentity peer; +}; + +struct GNUNET_MESSENGER_MessageMerge +{ + struct GNUNET_HashCode previous; +}; + +struct GNUNET_MESSENGER_MessageRequest +{ + struct GNUNET_HashCode hash; +}; + +struct GNUNET_MESSENGER_MessageInvite +{ + struct GNUNET_PeerIdentity door; + struct GNUNET_HashCode key; +}; + +struct GNUNET_MESSENGER_MessageText +{ + char *text; +}; + +struct GNUNET_MESSENGER_MessageFile +{ + struct GNUNET_CRYPTO_SymmetricSessionKey key; + struct GNUNET_HashCode hash; + char name[NAME_MAX]; + char *uri; +}; + +struct GNUNET_MESSENGER_MessagePrivate +{ + struct GNUNET_CRYPTO_EcdhePublicKey key; + + uint16_t length; + char *data; +}; + +struct GNUNET_MESSENGER_MessageBody +{ + union + { + struct GNUNET_MESSENGER_MessageInfo info; + + struct GNUNET_MESSENGER_MessageJoin join; + struct GNUNET_MESSENGER_MessageLeave leave; + + struct GNUNET_MESSENGER_MessageName name; + struct GNUNET_MESSENGER_MessageKey key; + struct GNUNET_MESSENGER_MessagePeer peer; + struct GNUNET_MESSENGER_MessageId id; + + struct GNUNET_MESSENGER_MessageMiss miss; + struct GNUNET_MESSENGER_MessageMerge merge; + struct GNUNET_MESSENGER_MessageRequest request; + + struct GNUNET_MESSENGER_MessageInvite invite; + struct GNUNET_MESSENGER_MessageText text; + struct GNUNET_MESSENGER_MessageFile file; + + struct GNUNET_MESSENGER_MessagePrivate private; + }; +}; + +/** + * Struct to a message + */ +struct GNUNET_MESSENGER_Message +{ + struct GNUNET_MESSENGER_MessageHeader header; + struct GNUNET_MESSENGER_MessageBody body; +}; + +/** + * Method called whenever the EGO of a handle changes or if the first connection fails + * to load a valid EGO and the anonymous keypair will be used instead. + * + * @param cls Closure from GNUNET_MESSENGER_connect + * @param handle Messenger handle + */ +typedef void +(*GNUNET_MESSENGER_IdentityCallback) (void *cls, struct GNUNET_MESSENGER_Handle *handle); + +/** + * Method called whenever a message is sent or received from a room. + * + * @param cls Closure from GNUNET_MESSENGER_connect + * @param room Room handle + * @param message Newly received or sent message + * @param hash Hash identifying the message + */ +typedef void +(*GNUNET_MESSENGER_MessageCallback) (void *cls, const struct GNUNET_MESSENGER_Room *room, + const struct GNUNET_MESSENGER_Message *message, const struct GNUNET_HashCode *hash); + +/** + * Set up a handle for the messenger related functions and connects to all necessary services. It will look up the ego + * key identified by its name and use it for signing all messages from the handle. + * + * @param cfg Configuration to use + * @param name Name to look up an ego or NULL to stay anonymous + * @param identity_callback Function called when the EGO of the handle changes + * @param identity_cls Closure for the identity_callback handler + * @param msg_callback Function called when a new message is sent or received + * @param msg_cls Closure for the msg_callback handler + * @return Messenger handle to use, NULL on error + */ +struct GNUNET_MESSENGER_Handle* +GNUNET_MESSENGER_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, const char *name, + GNUNET_MESSENGER_IdentityCallback identity_callback, void *identity_cls, + GNUNET_MESSENGER_MessageCallback msg_callback, void *msg_cls); + +/** + * Update a handle of the messenger to use a different ego key and replace the old one with a newly generated one. All + * participated rooms get informed about the key renewal. The handle requires a set name for this function to work and + * it needs to be unused by other egos. + * + * Keep in mind that this will fully delete the old ego key (if any is used) even if any other service wants to use it + * as default. + * + * @param handle Messenger handle to use + * @return GNUNET_OK on success, GNUNET_SYSERR on failure + */ +int +GNUNET_MESSENGER_update (struct GNUNET_MESSENGER_Handle *handle); + +/** + * Disconnect all of the messengers used services and clears up its used memory. + * + * @param handle Messenger handle to use + */ +void +GNUNET_MESSENGER_disconnect (struct GNUNET_MESSENGER_Handle *handle); + +/** + * Get the name (if specified, otherwise NULL) used by the messenger. + * + * @param handle Messenger handle to use + * @return Name used by the messenger or NULL + */ +const char* +GNUNET_MESSENGER_get_name (const struct GNUNET_MESSENGER_Handle *handle); + +/** + * Set the name for the messenger. This will rename the currently used ego and move all stored files related to the current + * name to its new directory. If anything fails during this process the function returns GNUNET_NO and the name for + * the messenger won't change as specified. + * + * @param handle Messenger handle to use + * @param name Name for the messenger to change to + * @return GNUNET_YES on success, GNUNET_NO on failure and GNUNET_SYSERR if handle is NULL + */ +int +GNUNET_MESSENGER_set_name (struct GNUNET_MESSENGER_Handle *handle, const char *name); + +/** + * Get the public key used by the messenger. + * + * @param handle Messenger handle to use + * @return Used ego's public key + */ +const struct GNUNET_IDENTITY_PublicKey* +GNUNET_MESSENGER_get_key (const struct GNUNET_MESSENGER_Handle *handle); + +/** + * Open a room to send and receive messages. The room will use the specified key as port for the underlying cadet + * service. Opening a room results in opening the port for incoming connections as possible door. + * + * Notice that there can only be one room related to a specific key. So trying to open two rooms with the same + * key will result in opening the room once but returning the handle both times because the room stays open. + * + * You can also open a room after entering it through a door using GNUNET_MESSENGER_entry_room(...). This + * will notify all entered doors to list you as new door. + * + * ( All doors form a ring structured network to shorten the latency sending and receiving messages. ) + * + * @param handle Messenger handle to use + * @param key Hash identifying the port + * @return Room handle, NULL on error + */ +struct GNUNET_MESSENGER_Room* +GNUNET_MESSENGER_open_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_HashCode *key); + +/** + * Enter a room to send and receive messages through a door opened using GNUNET_MESSENGER_open_room(...). + * + * Notice that there can only be one room related to a specific key. So trying to enter two rooms with the same + * key will result in entering the room once but returning the handle both times because the room stays entered. + * You can however enter a room through multiple doors in parallel which results in connecting both ends. But + * entering the room through the same door won't have any effect after the first time. + * + * You can also enter a room through a door after opening it using GNUNET_MESSENGER_open_room(...). But the + * door may not be your own peer identity. + * + * ( All doors form a ring structured network to shorten the latency sending and receiving messages. ) + * + * @param handle Messenger handle to use + * @param door Peer identity of an open door + * @param key Hash identifying the port + * @return Room handle, NULL on error + */ +struct GNUNET_MESSENGER_Room* +GNUNET_MESSENGER_entry_room (struct GNUNET_MESSENGER_Handle *handle, const struct GNUNET_PeerIdentity *door, + const struct GNUNET_HashCode *key); + +/** + * Close a room which was entered, opened or both in various order and variety. Closing a room will destroy all connections + * from your peer to another and the other way around. + * + * ( After a member closes a door, all members entered through that specific door have to use another one + * or open the room on their own. ) + * + * @param room Room handle + */ +void +GNUNET_MESSENGER_close_room (struct GNUNET_MESSENGER_Room *room); + +/** + * Get the contact of a member in a room identified by their id. + * + * Notice that contacts are independent of rooms but will be removed if all rooms containing these contacts get closed. + * + * @param room Room handle + * @param id Hash identifying a member + * @return Contact handle, NULL if id is not in use + */ +struct GNUNET_MESSENGER_Contact* +GNUNET_MESSENGER_get_member (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_ShortHashCode *id); + +/** + * Get the name used by the contact. + * + * @param contact Contact handle + * @return Name of contact or NULL + */ +const char* +GNUNET_MESSENGER_contact_get_name (const struct GNUNET_MESSENGER_Contact *contact); + +/** + * Get the public key used by the contact. + * + * @param contact Contact handle + * @return Public key of the ego used by contact + */ +const struct GNUNET_IDENTITY_PublicKey* +GNUNET_MESSENGER_contact_get_key (const struct GNUNET_MESSENGER_Contact *contact); + +/** + * Send a message into a room. If you opened the room all entered members will receive the + * message. If you entered the room through a door all so entered doors will receive the + * message as well. All members receiving the message will also propagate this message recursively + * as long as the message is unknown to them. + * + * Notice that all messages sent and received are also stored and can be propagated to new members entering the room. + * + * @param room Room handle + * @param message New message to send + */ +void +GNUNET_MESSENGER_send_message (struct GNUNET_MESSENGER_Room *room, const struct GNUNET_MESSENGER_Message *message); + +/** + * Get the message in a room identified by its hash. + * + * @param room Room handle + * @param hash Hash identifying a message + * @return Message struct or NULL if no message with that hash is known + */ +const struct GNUNET_MESSENGER_Message* +GNUNET_MESSENGER_get_message (const struct GNUNET_MESSENGER_Room *room, const struct GNUNET_HashCode *hash); + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +#endif //GNUNET_MESSENGER_SERVICE_H + +/** @} *//* end of group */ -- cgit v1.2.3