/*
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 */