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 */
40 * Version of the conversation API.
42 #define GNUNET_CONVERSATION_VERSION 0x00000001
45 enum GNUNET_CONVERSATION_RejectReason
47 GNUNET_CONVERSATION_REJECT_REASON_GENERIC = 0,
48 GNUNET_CONVERSATION_REJECT_REASON_NOT_AVAILABLE,
49 GNUNET_CONVERSATION_REJECT_REASON_NO_CLIENT,
50 GNUNET_CONVERSATION_REJECT_REASON_ACTIVE_CALL,
51 GNUNET_CONVERSATION_REJECT_REASON_NOT_WANTED,
52 GNUNET_CONVERSATION_REJECT_REASON_NO_ANSWER
57 enum GNUNET_CONVERSATION_NotificationType
59 GNUNET_CONVERSATION_NT_SERVICE_BLOCKED = 0,
60 GNUNET_CONVERSATION_NT_NO_PEER,
61 GNUNET_CONVERSATION_NT_NO_ANSWER,
62 GNUNET_CONVERSATION_NT_AVAILABLE_AGAIN,
63 GNUNET_CONVERSATION_NT_CALL_ACCEPTED,
64 GNUNET_CONVERSATION_NT_CALL_TERMINATED
71 struct GNUNET_CONVERSATION_MissedCall
73 struct GNUNET_PeerIdentity peer;
74 struct GNUNET_TIME_Absolute time;
78 struct GNUNET_CONVERSATION_MissedCallNotification
81 struct GNUNET_CONVERSATION_MissedCall *calls;
84 struct GNUNET_CONVERSATION_CallInformation;
86 struct GNUNET_CONVERSATION_Handle;
90 * Method called whenever a call is incoming
93 * @param handle to the conversation session
94 * @param caller peer that calls you
96 typedef void (GNUNET_CONVERSATION_CallHandler) (void *cls,
97 struct GNUNET_CONVERSATION_Handle *handle,
98 const struct GNUNET_PeerIdentity *caller);
102 * Method called whenever a call is rejected
105 * @param handle to the conversation session
106 * @param reason reason given for rejecting the call
107 * @param peer peer that rejected your call
109 typedef void (GNUNET_CONVERSATION_RejectHandler) (void *cls,
110 struct GNUNET_CONVERSATION_Handle *handle,
111 enum GNUNET_CONVERSATION_RejectReason reason,
112 const struct GNUNET_PeerIdentity *peer);
116 * Method called whenever a notification is there
119 * @param handle to the conversation session
120 * @param type the type of the notification
121 * @param peer peer that the notification is about
123 typedef void (GNUNET_CONVERSATION_NotificationHandler) (void *cls,
124 struct GNUNET_CONVERSATION_Handle *handle,
125 enum GNUNET_CONVERSATION_NotificationType type,
126 const struct GNUNET_PeerIdentity *peer);
130 * Method called whenever a notification for missed calls is there
133 * @param handle to the conversation session
134 * @param missed_calls a list of missed calls
136 typedef void (GNUNET_CONVERSATION_MissedCallHandler) (void *cls,
137 struct GNUNET_CONVERSATION_Handle *handle,
138 struct GNUNET_CONVERSATION_MissedCallNotification *missed_calls);
142 * Connect to the VoIP service
144 * @param cfg configuration
146 * @param call_handler the callback which is called when a call is incoming
147 * @param reject_handler the callback which is called when a call is rejected
148 * @param notification_handler the callback which is called when there is a notification
149 * @param missed_call_handler the callback which is called when the service notifies the client about missed clients
150 * @return handle to the connection to the conversation service
152 struct GNUNET_CONVERSATION_Handle *
153 GNUNET_CONVERSATION_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
155 GNUNET_CONVERSATION_CallHandler call_handler,
156 GNUNET_CONVERSATION_RejectHandler reject_handler,
157 GNUNET_CONVERSATION_NotificationHandler notification_handler,
158 GNUNET_CONVERSATION_MissedCallHandler missed_call_handler);
162 * Disconnect from the VoIP service
164 * @param handle handle to the VoIP connection
167 GNUNET_CONVERSATION_disconnect (struct GNUNET_CONVERSATION_Handle *handle);
173 * @param handle handle to the VoIP connection
174 * @param callee the peer (PeerIdentity or GNS name) to call
175 * @param doGnsLookup 0 = no GNS lookup or 1 = GNS lookup
178 GNUNET_CONVERSATION_call (struct GNUNET_CONVERSATION_Handle *handle,
184 * Terminate the active call
186 * @param handle handle to the VoIP connection
189 GNUNET_CONVERSATION_hangup (struct GNUNET_CONVERSATION_Handle *handle);
193 * Accept an incoming call
195 * @param handle handle to the VoIP connection
198 GNUNET_CONVERSATION_accept (struct GNUNET_CONVERSATION_Handle *handle);
202 * Reject an incoming call
204 * @param handle handle to the VoIP connection
207 GNUNET_CONVERSATION_reject (struct GNUNET_CONVERSATION_Handle *handle);
211 ////////////////////////////////////////////////////////////////////
212 ////////////////////////// NEW API /////////////////////////////////
213 ////////////////////////////////////////////////////////////////////
216 NOTE: This API is deliberately deceptively simple; the idea
217 is that advanced features (such as answering machines) will
218 be done with a separate service (an answering machine service)
219 with its own APIs; the speaker/microphone abstractions are
220 used to facilitate plugging in custom logic for implementing
221 such a service later by creating "software" versions of
222 speakers and microphones that record to disk or play a file.
223 Notifications about missed calls should similarly be done
224 using a separate service; CONVERSATION is supposed to be just
225 the "bare bones" voice service.
227 Meta data passing is supported so that advanced services
228 can identify themselves appropriately.
230 As this is supposed to be a "secure" service, caller ID is of
231 course provided as part of the basic implementation, as only the
232 CONVERSATION service can know for sure who it is that we are
236 #include "gnunet_identity_service.h"
237 #include "gnunet_namestore_service.h"
241 * A speaker is a device that can play or record audio data.
243 struct GNUNET_CONVERSATION_Speaker;
247 * Create a speaker that corresponds to the speaker hardware
250 * @param cfg configuration to use
251 * @return NULL on error
253 struct GNUNET_CONVERSATION_Speaker *
254 GNUNET_CONVERSATION_speaker_create_from_hardware (struct GNUNET_CONFIGURATION_Handle *cfg);
260 * @param speaker speaker to destroy
263 GNUNET_CONVERSATION_speaker_destroy (struct GNUNET_CONVERSATION_Speaker *speaker);
267 * A speaker is a device that can generate audio data.
269 struct GNUNET_CONVERSATION_Microphone;
273 * Create a speaker that corresponds to the speaker hardware
276 * @param cfg configuration to use
277 * @return NULL on error
279 struct GNUNET_CONVERSATION_Microphone *
280 GNUNET_CONVERSATION_microphone_create_from_hardware (struct GNUNET_CONFIGURATION_Handle *cfg);
284 * Destroy a microphone.
286 * @param mic microphone to destroy
289 GNUNET_CONVERSATION_microphone_destroy (struct GNUNET_CONVERSATION_Microphone *mic);
293 * Information about the current status of a call. Each call
294 * progresses from ring over ready to terminated. Steps may
297 enum GNUNET_CONVERSATION_EventCode
300 * The phone is ringing, caller ID is provided in the varargs as
301 * a `const char *`. The caller ID will be a GNS name.
303 GNUNET_CONVERSATION_EC_RING,
306 * We are ready to talk, metadata about the call may be supplied
307 * as a `const char *` in the varargs.
309 GNUNET_CONVERSATION_EC_READY,
312 * The conversation was terminated, a reason may be supplied
313 * as a `const char *` in the varargs.
315 GNUNET_CONVERSATION_EC_TERMINATED
321 * Function called with an event emitted by a phone.
324 * @param code type of the event on the phone
325 * @param ... additional information, depends on @a code
327 typedef void (*GNUNET_CONVERSATION_EventHandler)(void *cls,
328 enum GNUNET_CONVERSATION_EventCode code,
333 * A phone is a device that can ring to signal an incoming call and
334 * that you can pick up to answer the call and hang up to terminate
335 * the call. You can also hang up a ringing phone immediately
336 * (without picking it up) to stop it from ringing. Phones have
337 * caller ID. You can ask the phone for its record and make that
338 * record available (via GNS) to enable others to call you.
339 * Multiple phones maybe connected to the same line (the line is
340 * something rather internal to a phone and not obvious from it).
341 * You can only have one conversation per phone at any time.
343 struct GNUNET_CONVERSATION_Phone;
347 * Create a new phone.
349 * @param cfg configuration for the phone; specifies the phone service and
350 * which line the phone is to be connected to
351 * @param event_handler how to notify the owner of the phone about events
352 * @param event_handler_cls closure for @a event_handler
354 struct GNUNET_CONVERSATION_Phone *
355 GNUNET_CONVERSATION_phone_create (const struct GNUNET_CONFIGURATION_Handle *cfg,
356 GNUNET_CONVERSATION_EventHandler event_handler,
357 void *event_handler_cls);
361 * Fill in a namestore record with the contact information
362 * for this phone. Note that the filled in "data" value
363 * is only valid until the phone is destroyed.
365 * @param phone phone to create a record for
366 * @param rd namestore record to fill in
369 GNUNET_CONVERSATION_phone_get_record (struct GNUNET_CONVERSATION_Phone *phone,
370 struct GNUNET_NAMESTORE_RecordData *rd);
374 * Picks up a (ringing) phone. This will connect the speaker
375 * to the microphone of the other party, and vice versa.
377 * @param phone phone to pick up
378 * @param metadata meta data to give to the other user about the pick up event
379 * @param speaker speaker to use
380 * @param mic microphone to use
383 GNUNET_CONVERSTATION_phone_pick_up (struct GNUNET_CONVERSATION_Phone *phone,
384 const char *metadata,
385 struct GNUNET_CONVERSATION_Speaker *speaker,
386 struct GNUNET_CONVERSATION_Microphone *mic);
390 * Hang up up a (possibly ringing) phone. This will notify the other
391 * party that we are no longer interested in talking with them.
393 * @param phone phone to pick up
394 * @param reason text we give to the other party about why we terminated the conversation
397 GNUNET_CONVERSTATION_phone_hang_up (struct GNUNET_CONVERSATION_Phone *phone,
404 * @param phone phone to destroy
407 GNUNET_CONVERSATION_phone_destroy (struct GNUNET_CONVERSATION_Phone *phone);
411 * Handle for an outgoing call.
413 struct GNUNET_CONVERSATION_Call;
417 * Call the phone of another user.
419 * @param cfg configuration to use, specifies our phone service
420 * @param caller_id identity of the caller
421 * @param callee GNS name of the callee (used to locate the callee's record)
422 * @param speaker speaker to use (will be used automatically immediately once the
423 * #GNUNET_CONVERSATION_EC_READY event is generated); we will NOT generate
424 * a ring tone on the speaker
425 * @param mic microphone to use (will be used automatically immediately once the
426 * #GNUNET_CONVERSATION_EC_READY event is generated)
427 * @param event_handler how to notify the owner of the phone about events
428 * @param event_handler_cls closure for @a event_handler
430 struct GNUNET_CONVERSATION_Call *
431 GNUNET_CONVERSATION_call_start (const struct GNUNET_CONFIGURATION_Handle *cfg,
432 struct GNUNET_IDENTITY_Ego *caller_id,
434 struct GNUNET_CONVERSATION_Speaker *speaker,
435 struct GNUNET_CONVERSATION_Microphone *mic,
436 GNUNET_CONVERSATION_EventHandler event_handler,
437 void *event_handler_cls);
441 * Terminate a call. The call may be ringing or ready at this time.
443 * @param call call to terminate
444 * @param reason if the call was active (ringing or ready) this will be the
445 * reason given to the other user for why we hung up
447 struct GNUNET_CONVERSATION_Call *
448 GNUNET_CONVERSATION_call_stop (const struct GNUNET_CONVERSATION_Call *call,
452 #if 0 /* keep Emacsens' auto-indent happy */