/*
This file is part of GNUnet
- (C) 2013 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2013, 2014, 2016 GNUnet e.V.
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
You should have received a copy of the GNU General Public License
along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_conversation_service.h
- * @brief API to the conversation service
* @author Simon Dieterle
* @author Andreas Fuchs
* @author Christian Grothoff
*
+ * @file
+ * API to the conversation service
+ *
+ * @defgroup conversation Conversation service
+ * One-to-one voice communication over CADET
*
* NOTE: This API is deliberately deceptively simple; the idea
* is that advanced features (such as answering machines) will
* course provided as part of the basic implementation, as only the
* CONVERSATION service can know for sure who it is that we are
* talking to.
+ *
+ * @{
*/
#ifndef GNUNET_CONVERSATION_SERVICE_H
#define GNUNET_CONVERSATION_SERVICE_H
/**
* Version of the conversation API.
*/
-#define GNUNET_CONVERSATION_VERSION 0x00000003
+#define GNUNET_CONVERSATION_VERSION 0x00000004
/**
* Handle to identify a particular caller. A caller is an entity that
{
/**
- * Version of the phone record, for now always zero. We may
+ * Version of the phone record, for now always one. We may
* use other versions for anonymously hosted phone lines in
* the future.
*/
uint32_t version GNUNET_PACKED;
/**
- * Phone line to use at the peer.
+ * Reserved. In v1. always zero.
*/
- uint32_t line GNUNET_PACKED;
+ uint32_t reserved GNUNET_PACKED;
/**
* Identity of the peer hosting the phone service.
*/
struct GNUNET_PeerIdentity peer;
+ /**
+ * Phone line (CADET port) to connect to.
+ */
+ struct GNUNET_HashCode line_port;
+
};
GNUNET_NETWORK_STRUCT_END
* @param cls closure
* @param code type of the event
* @param caller handle for the caller
- * @param caller_id name of the caller in GNS
+ * @param caller_id public key of the caller (in GNS)
*/
-typedef void (*GNUNET_CONVERSATION_PhoneEventHandler)(void *cls,
- enum GNUNET_CONVERSATION_PhoneEventCode code,
- struct GNUNET_CONVERSATION_Caller *caller,
- const char *caller_id);
+typedef void
+(*GNUNET_CONVERSATION_PhoneEventHandler)(void *cls,
+ enum GNUNET_CONVERSATION_PhoneEventCode code,
+ struct GNUNET_CONVERSATION_Caller *caller,
+ const struct GNUNET_CRYPTO_EcdsaPublicKey *caller_id);
/**
* @param cls closure
* @param code type of the event for this caller
*/
-typedef void (*GNUNET_CONVERSATION_CallerEventHandler)(void *cls,
- enum GNUNET_CONVERSATION_CallerEventCode code);
+typedef void
+(*GNUNET_CONVERSATION_CallerEventHandler)(void *cls,
+ enum GNUNET_CONVERSATION_CallerEventCode code);
/**
*/
enum GNUNET_CONVERSATION_CallEventCode
{
+
/**
* We are the caller and are now ringing the other party (GNS lookup
* succeeded).
* both sides can independently suspend and resume calls; a call is
* only "working" of both sides are active.
*/
- GNUNET_CONVERSATION_EC_CALL_RESUMED
+ GNUNET_CONVERSATION_EC_CALL_RESUMED,
+
+ /**
+ * We had an error handing the call, and are now restarting it
+ * (back to lookup). This happens, for example, if the peer
+ * is restarted during a call.
+ */
+ GNUNET_CONVERSATION_EC_CALL_ERROR
};
* @param cls closure
* @param code type of the event on the call
*/
-typedef void (*GNUNET_CONVERSATION_CallEventHandler)(void *cls,
- enum GNUNET_CONVERSATION_CallEventCode code);
+typedef void
+(*GNUNET_CONVERSATION_CallEventHandler)(void *cls,
+ enum GNUNET_CONVERSATION_CallEventCode code);
/**
*
* @param cfg configuration to use, specifies our phone service
* @param caller_id identity of the caller
+ * @param zone_id GNS zone to use to resolve @a callee
* @param callee GNS name of the callee (used to locate the callee's record)
* @param speaker speaker to use (will be used automatically immediately once the
* #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated); we will NOT generate
* #GNUNET_CONVERSATION_EC_CALL_PICKED_UP event is generated)
* @param event_handler how to notify the owner of the phone about events
* @param event_handler_cls closure for @a event_handler
+ * @return handle for the call
*/
struct GNUNET_CONVERSATION_Call *
GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
struct GNUNET_IDENTITY_Ego *caller_id,
+ struct GNUNET_IDENTITY_Ego *zone_id,
const char *callee,
struct GNUNET_SPEAKER_Handle *speaker,
struct GNUNET_MICROPHONE_Handle *mic,
#endif
#endif
+
+/** @} */ /* end of group */