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
32 #ifndef GNUNET_CONVERSATION_SERVICE_H
33 #define GNUNET_CONVERSATION_SERVICE_H
38 #if 0 /* keep Emacsens' auto-indent happy */
43 #include "gnunet_util_lib.h"
46 * Version of the conversation API.
48 #define GNUNET_CONVERSATION_VERSION 0x00000001
51 enum GNUNET_CONVERSATION_RejectReason
53 GNUNET_CONVERSATION_REJECT_REASON_GENERIC = 0,
54 GNUNET_CONVERSATION_REJECT_REASON_NOT_AVAILABLE,
55 GNUNET_CONVERSATION_REJECT_REASON_NO_CLIENT,
56 GNUNET_CONVERSATION_REJECT_REASON_ACTIVE_CALL,
57 GNUNET_CONVERSATION_REJECT_REASON_NOT_WANTED,
58 GNUNET_CONVERSATION_REJECT_REASON_NO_ANSWER
63 enum GNUNET_CONVERSATION_NotificationType
65 GNUNET_CONVERSATION_NT_SERVICE_BLOCKED = 0,
66 GNUNET_CONVERSATION_NT_NO_PEER,
67 GNUNET_CONVERSATION_NT_NO_ANSWER,
68 GNUNET_CONVERSATION_NT_AVAILABLE_AGAIN,
69 GNUNET_CONVERSATION_NT_CALL_ACCEPTED,
70 GNUNET_CONVERSATION_NT_CALL_TERMINATED
77 struct GNUNET_CONVERSATION_MissedCall
79 struct GNUNET_PeerIdentity peer;
80 struct GNUNET_TIME_Absolute time;
84 struct GNUNET_CONVERSATION_MissedCallNotification
87 struct GNUNET_CONVERSATION_MissedCall *calls;
90 struct GNUNET_CONVERSATION_CallInformation;
92 struct GNUNET_CONVERSATION_Handle;
96 * Method called whenever a call is incoming
99 * @param handle to the conversation session
100 * @param caller peer that calls you
102 typedef void (GNUNET_CONVERSATION_CallHandler) (void *cls,
103 struct GNUNET_CONVERSATION_Handle *handle,
104 const struct GNUNET_PeerIdentity *caller);
108 * Method called whenever a call is rejected
111 * @param handle to the conversation session
112 * @param reason reason given for rejecting the call
113 * @param peer peer that rejected your call
115 typedef void (GNUNET_CONVERSATION_RejectHandler) (void *cls,
116 struct GNUNET_CONVERSATION_Handle *handle,
117 enum GNUNET_CONVERSATION_RejectReason reason,
118 const struct GNUNET_PeerIdentity *peer);
122 * Method called whenever a notification is there
125 * @param handle to the conversation session
126 * @param type the type of the notification
127 * @param peer peer that the notification is about
129 typedef void (GNUNET_CONVERSATION_NotificationHandler) (void *cls,
130 struct GNUNET_CONVERSATION_Handle *handle,
131 enum GNUNET_CONVERSATION_NotificationType type,
132 const struct GNUNET_PeerIdentity *peer);
136 * Method called whenever a notification for missed calls is there
139 * @param handle to the conversation session
140 * @param missed_calls a list of missed calls
142 typedef void (GNUNET_CONVERSATION_MissedCallHandler) (void *cls,
143 struct GNUNET_CONVERSATION_Handle *handle,
144 struct GNUNET_CONVERSATION_MissedCallNotification *missed_calls);
148 * Connect to the VoIP service
150 * @param cfg configuration
152 * @param call_handler the callback which is called when a call is incoming
153 * @param reject_handler the callback which is called when a call is rejected
154 * @param notification_handler the callback which is called when there is a notification
155 * @param missed_call_handler the callback which is called when the service notifies the client about missed clients
156 * @return handle to the connection to the conversation service
158 struct GNUNET_CONVERSATION_Handle *
159 GNUNET_CONVERSATION_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
161 GNUNET_CONVERSATION_CallHandler call_handler,
162 GNUNET_CONVERSATION_RejectHandler reject_handler,
163 GNUNET_CONVERSATION_NotificationHandler notification_handler,
164 GNUNET_CONVERSATION_MissedCallHandler missed_call_handler);
168 * Disconnect from the VoIP service
170 * @param handle handle to the VoIP connection
173 GNUNET_CONVERSATION_disconnect (struct GNUNET_CONVERSATION_Handle *handle);
179 * @param handle handle to the VoIP connection
180 * @param callee the peer (PeerIdentity or GNS name) to call
181 * @param doGnsLookup 0 = no GNS lookup or 1 = GNS lookup
184 GNUNET_CONVERSATION_call (struct GNUNET_CONVERSATION_Handle *handle,
190 * Terminate the active call
192 * @param handle handle to the VoIP connection
195 GNUNET_CONVERSATION_hangup (struct GNUNET_CONVERSATION_Handle *handle);
199 * Accept an incoming call
201 * @param handle handle to the VoIP connection
204 GNUNET_CONVERSATION_accept (struct GNUNET_CONVERSATION_Handle *handle);
208 * Reject an incoming call
210 * @param handle handle to the VoIP connection
213 GNUNET_CONVERSATION_reject (struct GNUNET_CONVERSATION_Handle *handle);
217 ////////////////////////////////////////////////////////////////////
218 ////////////////////////// NEW API /////////////////////////////////
219 ////////////////////////////////////////////////////////////////////
222 NOTE: This API is deliberately deceptively simple; the idea
223 is that advanced features (such as answering machines) will
224 be done with a separate service (an answering machine service)
225 with its own APIs; the speaker/microphone abstractions are
226 used to facilitate plugging in custom logic for implementing
227 such a service later by creating "software" versions of
228 speakers and microphones that record to disk or play a file.
229 Notifications about missed calls should similarly be done
230 using a separate service; CONVERSATION is supposed to be just
231 the "bare bones" voice service.
233 Meta data passing is supported so that advanced services
234 can identify themselves appropriately.
236 As this is supposed to be a "secure" service, caller ID is of
237 course provided as part of the basic implementation, as only the
238 CONVERSATION service can know for sure who it is that we are
243 #include "gnunet_util_lib.h"
244 #include "gnunet_identity_service.h"
245 #include "gnunet_namestore_service.h"
246 #include "gnunet_speaker_lib.h"
247 #include "gnunet_microphone_lib.h"
251 * Information about the current status of a call. Each call
252 * progresses from ring over ready to terminated. Steps may
255 enum GNUNET_CONVERSATION_EventCode
258 * The phone is ringing, caller ID is provided in the varargs as
259 * a `const char *`. The caller ID will be a GNS name.
261 GNUNET_CONVERSATION_EC_RING,
264 * We are the caller and are now ringing the other party.
265 * The varargs will be empty.
267 GNUNET_CONVERSATION_EC_RINGING,
270 * We are ready to talk, metadata about the call may be supplied
271 * as a `const char *` in the varargs.
273 GNUNET_CONVERSATION_EC_READY,
276 * We failed to locate a phone record in GNS.
278 GNUNET_CONVERSATION_EC_GNS_FAIL,
281 * The phone is busy. Varargs will be empty.
283 GNUNET_CONVERSATION_EC_BUSY,
286 * The conversation was terminated, a reason may be supplied
287 * as a `const char *` in the varargs.
289 GNUNET_CONVERSATION_EC_TERMINATED
295 * Function called with an event emitted by a phone.
298 * @param code type of the event on the phone
299 * @param ... additional information, depends on @a code
301 typedef void (*GNUNET_CONVERSATION_EventHandler)(void *cls,
302 enum GNUNET_CONVERSATION_EventCode code,
307 * A phone is a device that can ring to signal an incoming call and
308 * that you can pick up to answer the call and hang up to terminate
309 * the call. You can also hang up a ringing phone immediately
310 * (without picking it up) to stop it from ringing. Phones have
311 * caller ID. You can ask the phone for its record and make that
312 * record available (via GNS) to enable others to call you.
313 * Multiple phones maybe connected to the same line (the line is
314 * something rather internal to a phone and not obvious from it).
315 * You can only have one conversation per phone at any time.
317 struct GNUNET_CONVERSATION_Phone;
321 * Create a new phone.
323 * @param cfg configuration for the phone; specifies the phone service and
324 * which line the phone is to be connected to
325 * @param ego ego to use for name resolution (when determining caller ID)
326 * @param event_handler how to notify the owner of the phone about events
327 * @param event_handler_cls closure for @a event_handler
329 struct GNUNET_CONVERSATION_Phone *
330 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
331 const struct GNUNET_IDENTITY_Ego *ego,
332 GNUNET_CONVERSATION_EventHandler event_handler,
333 void *event_handler_cls);
337 * Fill in a namestore record with the contact information
338 * for this phone. Note that the filled in "data" value
339 * is only valid until the phone is destroyed.
341 * @param phone phone to create a record for
342 * @param rd namestore record to fill in
345 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
346 struct GNUNET_NAMESTORE_RecordData *rd);
350 * Picks up a (ringing) phone. This will connect the speaker
351 * to the microphone of the other party, and vice versa.
353 * @param phone phone to pick up
354 * @param metadata meta data to give to the other user about the pick up event
355 * @param speaker speaker to use
356 * @param mic microphone to use
359 GNUNET_CONVERSATION_phone_pick_up (struct GNUNET_CONVERSATION_Phone *phone,
360 const char *metadata,
361 struct GNUNET_SPEAKER_Handle *speaker,
362 struct GNUNET_MICROPHONE_Handle *mic);
366 * Hang up up a (possibly ringing) phone. This will notify the other
367 * party that we are no longer interested in talking with them.
369 * @param phone phone to pick up
370 * @param reason text we give to the other party about why we terminated the conversation
373 GNUNET_CONVERSATION_phone_hang_up (struct GNUNET_CONVERSATION_Phone *phone,
380 * @param phone phone to destroy
383 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
387 * Handle for an outgoing call.
389 struct GNUNET_CONVERSATION_Call;
393 * Call the phone of another user.
395 * @param cfg configuration to use, specifies our phone service
396 * @param caller_id identity of the caller
397 * @param callee GNS name of the callee (used to locate the callee's record)
398 * @param speaker speaker to use (will be used automatically immediately once the
399 * #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
400 * a ring tone on the speaker
401 * @param mic microphone to use (will be used automatically immediately once the
402 * #GNUNET_CONVERSATION_EC_READY event is generated)
403 * @param event_handler how to notify the owner of the phone about events
404 * @param event_handler_cls closure for @a event_handler
406 struct GNUNET_CONVERSATION_Call *
407 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
408 struct GNUNET_IDENTITY_Ego *caller_id,
410 struct GNUNET_SPEAKER_Handle *speaker,
411 struct GNUNET_MICROPHONE_Handle *mic,
412 GNUNET_CONVERSATION_EventHandler event_handler,
413 void *event_handler_cls);
417 * Terminate a call. The call may be ringing or ready at this time.
419 * @param call call to terminate
420 * @param reason if the call was active (ringing or ready) this will be the
421 * reason given to the other user for why we hung up
424 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call,
428 #if 0 /* keep Emacsens' auto-indent happy */