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 ready to talk, metadata about the call may be supplied
265 * as a `const char *` in the varargs.
267 GNUNET_CONVERSATION_EC_READY,
270 * We failed to locate a phone record in GNS.
272 GNUNET_CONVERSATION_EC_GNS_FAIL,
275 * The phone is busy. Varargs will be empty.
277 GNUNET_CONVERSATION_EC_BUSY,
280 * The conversation was terminated, a reason may be supplied
281 * as a `const char *` in the varargs.
283 GNUNET_CONVERSATION_EC_TERMINATED
289 * Function called with an event emitted by a phone.
292 * @param code type of the event on the phone
293 * @param ... additional information, depends on @a code
295 typedef void (*GNUNET_CONVERSATION_EventHandler)(void *cls,
296 enum GNUNET_CONVERSATION_EventCode code,
301 * A phone is a device that can ring to signal an incoming call and
302 * that you can pick up to answer the call and hang up to terminate
303 * the call. You can also hang up a ringing phone immediately
304 * (without picking it up) to stop it from ringing. Phones have
305 * caller ID. You can ask the phone for its record and make that
306 * record available (via GNS) to enable others to call you.
307 * Multiple phones maybe connected to the same line (the line is
308 * something rather internal to a phone and not obvious from it).
309 * You can only have one conversation per phone at any time.
311 struct GNUNET_CONVERSATION_Phone;
315 * Create a new phone.
317 * @param cfg configuration for the phone; specifies the phone service and
318 * which line the phone is to be connected to
319 * @param ego ego to use for name resolution (when determining caller ID)
320 * @param event_handler how to notify the owner of the phone about events
321 * @param event_handler_cls closure for @a event_handler
323 struct GNUNET_CONVERSATION_Phone *
324 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
325 const struct GNUNET_IDENTITY_Ego *ego,
326 GNUNET_CONVERSATION_EventHandler event_handler,
327 void *event_handler_cls);
331 * Fill in a namestore record with the contact information
332 * for this phone. Note that the filled in "data" value
333 * is only valid until the phone is destroyed.
335 * @param phone phone to create a record for
336 * @param rd namestore record to fill in
339 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
340 struct GNUNET_NAMESTORE_RecordData *rd);
344 * Picks up a (ringing) phone. This will connect the speaker
345 * to the microphone of the other party, and vice versa.
347 * @param phone phone to pick up
348 * @param metadata meta data to give to the other user about the pick up event
349 * @param speaker speaker to use
350 * @param mic microphone to use
353 GNUNET_CONVERSTATION_phone_pick_up (struct GNUNET_CONVERSATION_Phone *phone,
354 const char *metadata,
355 struct GNUNET_SPEAKER_Handle *speaker,
356 struct GNUNET_MICROPHONE_Handle *mic);
360 * Hang up up a (possibly ringing) phone. This will notify the other
361 * party that we are no longer interested in talking with them.
363 * @param phone phone to pick up
364 * @param reason text we give to the other party about why we terminated the conversation
367 GNUNET_CONVERSTATION_phone_hang_up (struct GNUNET_CONVERSATION_Phone *phone,
374 * @param phone phone to destroy
377 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
381 * Handle for an outgoing call.
383 struct GNUNET_CONVERSATION_Call;
387 * Call the phone of another user.
389 * @param cfg configuration to use, specifies our phone service
390 * @param caller_id identity of the caller
391 * @param callee GNS name of the callee (used to locate the callee's record)
392 * @param speaker speaker to use (will be used automatically immediately once the
393 * #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
394 * a ring tone on the speaker
395 * @param mic microphone to use (will be used automatically immediately once the
396 * #GNUNET_CONVERSATION_EC_READY event is generated)
397 * @param event_handler how to notify the owner of the phone about events
398 * @param event_handler_cls closure for @a event_handler
400 struct GNUNET_CONVERSATION_Call *
401 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
402 struct GNUNET_IDENTITY_Ego *caller_id,
404 struct GNUNET_SPEAKER_Handle *speaker,
405 struct GNUNET_MICROPHONE_Handle *mic,
406 GNUNET_CONVERSATION_EventHandler event_handler,
407 void *event_handler_cls);
411 * Terminate a call. The call may be ringing or ready at this time.
413 * @param call call to terminate
414 * @param reason if the call was active (ringing or ready) this will be the
415 * reason given to the other user for why we hung up
418 GNUNET_CONVERSATION_call_stop (struct GNUNET_CONVERSATION_Call *call,
422 #if 0 /* keep Emacsens' auto-indent happy */