2 This file is part of GNUnet
3 (C) 2013 Christian Grothoff (and other contributing authors)
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
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 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18 Boston, MA 02111-1307, USA.
22 * @file include/gnunet_conversation_service.h
23 * @brief API to the conversation service
24 * @author Simon Dieterle
25 * @author Andreas Fuchs
26 * @author Christian Grothoff
28 #ifndef GNUNET_CONVERSATION_SERVICE_H
29 #define GNUNET_CONVERSATION_SERVICE_H
34 #if 0 /* keep Emacsens' auto-indent happy */
39 #include "gnunet_util_lib.h"
42 * Version of the conversation API.
44 #define GNUNET_CONVERSATION_VERSION 0x00000001
47 enum GNUNET_CONVERSATION_RejectReason
49 GNUNET_CONVERSATION_REJECT_REASON_GENERIC = 0,
50 GNUNET_CONVERSATION_REJECT_REASON_NOT_AVAILABLE,
51 GNUNET_CONVERSATION_REJECT_REASON_NO_CLIENT,
52 GNUNET_CONVERSATION_REJECT_REASON_ACTIVE_CALL,
53 GNUNET_CONVERSATION_REJECT_REASON_NOT_WANTED,
54 GNUNET_CONVERSATION_REJECT_REASON_NO_ANSWER
59 enum GNUNET_CONVERSATION_NotificationType
61 GNUNET_CONVERSATION_NT_SERVICE_BLOCKED = 0,
62 GNUNET_CONVERSATION_NT_NO_PEER,
63 GNUNET_CONVERSATION_NT_NO_ANSWER,
64 GNUNET_CONVERSATION_NT_AVAILABLE_AGAIN,
65 GNUNET_CONVERSATION_NT_CALL_ACCEPTED,
66 GNUNET_CONVERSATION_NT_CALL_TERMINATED
73 struct GNUNET_CONVERSATION_MissedCall
75 struct GNUNET_PeerIdentity peer;
76 struct GNUNET_TIME_Absolute time;
80 struct GNUNET_CONVERSATION_MissedCallNotification
83 struct GNUNET_CONVERSATION_MissedCall *calls;
86 struct GNUNET_CONVERSATION_CallInformation;
88 struct GNUNET_CONVERSATION_Handle;
92 * Method called whenever a call is incoming
95 * @param handle to the conversation session
96 * @param caller peer that calls you
98 typedef void (GNUNET_CONVERSATION_CallHandler) (void *cls,
99 struct GNUNET_CONVERSATION_Handle *handle,
100 const struct GNUNET_PeerIdentity *caller);
104 * Method called whenever a call is rejected
107 * @param handle to the conversation session
108 * @param reason reason given for rejecting the call
109 * @param peer peer that rejected your call
111 typedef void (GNUNET_CONVERSATION_RejectHandler) (void *cls,
112 struct GNUNET_CONVERSATION_Handle *handle,
113 enum GNUNET_CONVERSATION_RejectReason reason,
114 const struct GNUNET_PeerIdentity *peer);
118 * Method called whenever a notification is there
121 * @param handle to the conversation session
122 * @param type the type of the notification
123 * @param peer peer that the notification is about
125 typedef void (GNUNET_CONVERSATION_NotificationHandler) (void *cls,
126 struct GNUNET_CONVERSATION_Handle *handle,
127 enum GNUNET_CONVERSATION_NotificationType type,
128 const struct GNUNET_PeerIdentity *peer);
132 * Method called whenever a notification for missed calls is there
135 * @param handle to the conversation session
136 * @param missed_calls a list of missed calls
138 typedef void (GNUNET_CONVERSATION_MissedCallHandler) (void *cls,
139 struct GNUNET_CONVERSATION_Handle *handle,
140 struct GNUNET_CONVERSATION_MissedCallNotification *missed_calls);
144 * Connect to the VoIP service
146 * @param cfg configuration
148 * @param call_handler the callback which is called when a call is incoming
149 * @param reject_handler the callback which is called when a call is rejected
150 * @param notification_handler the callback which is called when there is a notification
151 * @param missed_call_handler the callback which is called when the service notifies the client about missed clients
152 * @return handle to the connection to the conversation service
154 struct GNUNET_CONVERSATION_Handle *
155 GNUNET_CONVERSATION_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
157 GNUNET_CONVERSATION_CallHandler call_handler,
158 GNUNET_CONVERSATION_RejectHandler reject_handler,
159 GNUNET_CONVERSATION_NotificationHandler notification_handler,
160 GNUNET_CONVERSATION_MissedCallHandler missed_call_handler);
164 * Disconnect from the VoIP service
166 * @param handle handle to the VoIP connection
169 GNUNET_CONVERSATION_disconnect (struct GNUNET_CONVERSATION_Handle *handle);
175 * @param handle handle to the VoIP connection
176 * @param callee the peer (PeerIdentity or GNS name) to call
177 * @param doGnsLookup 0 = no GNS lookup or 1 = GNS lookup
180 GNUNET_CONVERSATION_call (struct GNUNET_CONVERSATION_Handle *handle,
186 * Terminate the active call
188 * @param handle handle to the VoIP connection
191 GNUNET_CONVERSATION_hangup (struct GNUNET_CONVERSATION_Handle *handle);
195 * Accept an incoming call
197 * @param handle handle to the VoIP connection
200 GNUNET_CONVERSATION_accept (struct GNUNET_CONVERSATION_Handle *handle);
204 * Reject an incoming call
206 * @param handle handle to the VoIP connection
209 GNUNET_CONVERSATION_reject (struct GNUNET_CONVERSATION_Handle *handle);
213 ////////////////////////////////////////////////////////////////////
214 ////////////////////////// NEW API /////////////////////////////////
215 ////////////////////////////////////////////////////////////////////
218 NOTE: This API is deliberately deceptively simple; the idea
219 is that advanced features (such as answering machines) will
220 be done with a separate service (an answering machine service)
221 with its own APIs; the speaker/microphone abstractions are
222 used to facilitate plugging in custom logic for implementing
223 such a service later by creating "software" versions of
224 speakers and microphones that record to disk or play a file.
225 Notifications about missed calls should similarly be done
226 using a separate service; CONVERSATION is supposed to be just
227 the "bare bones" voice service.
229 Meta data passing is supported so that advanced services
230 can identify themselves appropriately.
232 As this is supposed to be a "secure" service, caller ID is of
233 course provided as part of the basic implementation, as only the
234 CONVERSATION service can know for sure who it is that we are
238 #include "gnunet_util_lib.h"
239 #include "gnunet_identity_service.h"
240 #include "gnunet_namestore_service.h"
241 #include "gnunet_speaker_lib.h"
242 #include "gnunet_microphone_lib.h"
246 * Information about the current status of a call. Each call
247 * progresses from ring over ready to terminated. Steps may
250 enum GNUNET_CONVERSATION_EventCode
253 * The phone is ringing, caller ID is provided in the varargs as
254 * a `const char *`. The caller ID will be a GNS name.
256 GNUNET_CONVERSATION_EC_RING,
259 * We are ready to talk, metadata about the call may be supplied
260 * as a `const char *` in the varargs.
262 GNUNET_CONVERSATION_EC_READY,
265 * The conversation was terminated, a reason may be supplied
266 * as a `const char *` in the varargs.
268 GNUNET_CONVERSATION_EC_TERMINATED
274 * Function called with an event emitted by a phone.
277 * @param code type of the event on the phone
278 * @param ... additional information, depends on @a code
280 typedef void (*GNUNET_CONVERSATION_EventHandler)(void *cls,
281 enum GNUNET_CONVERSATION_EventCode code,
286 * A phone is a device that can ring to signal an incoming call and
287 * that you can pick up to answer the call and hang up to terminate
288 * the call. You can also hang up a ringing phone immediately
289 * (without picking it up) to stop it from ringing. Phones have
290 * caller ID. You can ask the phone for its record and make that
291 * record available (via GNS) to enable others to call you.
292 * Multiple phones maybe connected to the same line (the line is
293 * something rather internal to a phone and not obvious from it).
294 * You can only have one conversation per phone at any time.
296 struct GNUNET_CONVERSATION_Phone;
300 * Create a new phone.
302 * @param cfg configuration for the phone; specifies the phone service and
303 * which line the phone is to be connected to
304 * @param event_handler how to notify the owner of the phone about events
305 * @param event_handler_cls closure for @a event_handler
307 struct GNUNET_CONVERSATION_Phone *
308 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
309 GNUNET_CONVERSATION_EventHandler event_handler,
310 void *event_handler_cls);
314 * Fill in a namestore record with the contact information
315 * for this phone. Note that the filled in "data" value
316 * is only valid until the phone is destroyed.
318 * @param phone phone to create a record for
319 * @param rd namestore record to fill in
322 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
323 struct GNUNET_NAMESTORE_RecordData *rd);
327 * Picks up a (ringing) phone. This will connect the speaker
328 * to the microphone of the other party, and vice versa.
330 * @param phone phone to pick up
331 * @param metadata meta data to give to the other user about the pick up event
332 * @param speaker speaker to use
333 * @param mic microphone to use
336 GNUNET_CONVERSTATION_phone_pick_up (struct GNUNET_CONVERSATION_Phone *phone,
337 const char *metadata,
338 struct GNUNET_SPEAKER_Handle *speaker,
339 struct GNUNET_MICROPHONE_Handle *mic);
343 * Hang up up a (possibly ringing) phone. This will notify the other
344 * party that we are no longer interested in talking with them.
346 * @param phone phone to pick up
347 * @param reason text we give to the other party about why we terminated the conversation
350 GNUNET_CONVERSTATION_phone_hang_up (struct GNUNET_CONVERSATION_Phone *phone,
357 * @param phone phone to destroy
360 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
364 * Handle for an outgoing call.
366 struct GNUNET_CONVERSATION_Call;
370 * Call the phone of another user.
372 * @param cfg configuration to use, specifies our phone service
373 * @param caller_id identity of the caller
374 * @param callee GNS name of the callee (used to locate the callee's record)
375 * @param speaker speaker to use (will be used automatically immediately once the
376 * #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
377 * a ring tone on the speaker
378 * @param mic microphone to use (will be used automatically immediately once the
379 * #GNUNET_CONVERSATION_EC_READY event is generated)
380 * @param event_handler how to notify the owner of the phone about events
381 * @param event_handler_cls closure for @a event_handler
383 struct GNUNET_CONVERSATION_Call *
384 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
385 struct GNUNET_IDENTITY_Ego *caller_id,
387 struct GNUNET_SPEAKER_Handle *speaker,
388 struct GNUNET_MICROPHONE_Handle *mic,
389 GNUNET_CONVERSATION_EventHandler event_handler,
390 void *event_handler_cls);
394 * Terminate a call. The call may be ringing or ready at this time.
396 * @param call call to terminate
397 * @param reason if the call was active (ringing or ready) this will be the
398 * reason given to the other user for why we hung up
401 GNUNET_CONVERSATION_call_stop (const struct GNUNET_CONVERSATION_Call *call,
405 #if 0 /* keep Emacsens' auto-indent happy */