diff --git a/calls.doap b/calls.doap index 50c32d3..1754562 100644 --- a/calls.doap +++ b/calls.doap @@ -10,7 +10,7 @@ A phone call dialer Calls is a dialer for phone calls, initially PSTN calls but eventually other systems like SIP in future. - + C diff --git a/doc/calls-docs.xml b/doc/calls-docs.xml new file mode 100644 index 0000000..c5958e9 --- /dev/null +++ b/doc/calls-docs.xml @@ -0,0 +1,38 @@ + + + + %gtkdocentities; +]> + + + &package_name; Reference Manual + + This document is the API reference for &package_name; &package_version; + + Calls is a dialer program for telephony calls. + + + If you find any issues in this API reference, please report it + using at the + bugtracker + + + + + 2018 + Purism SPC + + + + + Provider abstraction + + + + + + + diff --git a/doc/meson.build b/doc/meson.build new file mode 100644 index 0000000..e726f18 --- /dev/null +++ b/doc/meson.build @@ -0,0 +1,31 @@ +if get_option('gtk_doc') + +subdir('xml') + +glib_prefix = dependency('glib-2.0').get_pkgconfig_variable('prefix') +glib_docpath = join_paths(glib_prefix, 'share', 'gtk-doc', 'html') +docpath = join_paths(get_option('datadir'), 'gtk-doc', 'html') + +gnome.gtkdoc('calls', + main_xml: 'calls-docs.xml', + src_dir: [ + join_paths(meson.source_root(), 'src'), + join_paths(meson.build_root(), 'src'), + join_paths(meson.build_root(), 'libgdbofono'), + ], + dependencies: calls_deps, + scan_args: [ + '--rebuild-types', + ], + fixxref_args: [ + '--html-dir=@0@'.format(docpath), + '--extra-dir=@0@'.format(join_paths(glib_docpath, 'glib')), + '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gobject')), + '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gio')), + '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gi')), + '--extra-dir=@0@'.format(join_paths(glib_docpath, 'gtk3')), + ], + install_dir: 'calls', + install: true) + +endif diff --git a/doc/xml/gtkdocentities.ent.in b/doc/xml/gtkdocentities.ent.in new file mode 100644 index 0000000..fd86c16 --- /dev/null +++ b/doc/xml/gtkdocentities.ent.in @@ -0,0 +1,7 @@ + + + + + + + diff --git a/doc/xml/meson.build b/doc/xml/meson.build new file mode 100644 index 0000000..0f2bde7 --- /dev/null +++ b/doc/xml/meson.build @@ -0,0 +1,9 @@ +ent_conf = configuration_data() +ent_conf.set('PACKAGE', 'Calls') +ent_conf.set('PACKAGE_BUGREPORT', 'https://code.puri.sm/Librem5/calls/issues') +ent_conf.set('PACKAGE_NAME', 'Calls') +ent_conf.set('PACKAGE_STRING', 'calls') +ent_conf.set('PACKAGE_TARNAME', 'calls-' + meson.project_version()) +ent_conf.set('PACKAGE_URL', 'https://code.puri.sm/Librem5/calls') +ent_conf.set('PACKAGE_VERSION', meson.project_version()) +configure_file(input: 'gtkdocentities.ent.in', output: 'gtkdocentities.ent', configuration: ent_conf) diff --git a/meson.build b/meson.build index 5414ca9..b7dd235 100644 --- a/meson.build +++ b/meson.build @@ -29,3 +29,4 @@ project('call', 'c', subdir('libgdbofono') subdir('src') +subdir('doc') diff --git a/meson_options.txt b/meson_options.txt new file mode 100644 index 0000000..1c4e8e7 --- /dev/null +++ b/meson_options.txt @@ -0,0 +1,3 @@ +option('gtk_doc', + type: 'boolean', value: false, + description: 'Whether to generate the API reference for Calls') diff --git a/src/calls-call-data.c b/src/calls-call-data.c index d7d6e52..7b1bb58 100644 --- a/src/calls-call-data.c +++ b/src/calls-call-data.c @@ -31,7 +31,9 @@ /** * SECTION:calls-call-data * @short_description: An object to hold both a #CallsCall object and - * the #CallsParty participating in the call + * the #CallsParty participating in the call. These data are passed + * to both #CallsCallDisplay and #CallsCallSelectorItem so we create a + * convenient object to keep them together. * @Title: CallsCallData */ @@ -54,52 +56,9 @@ enum { static GParamSpec *props[PROP_LAST_PROP]; -CallsCallData * -calls_call_data_new (CallsCall *call, CallsParty *party) -{ - return g_object_new (CALLS_TYPE_CALL_DATA, - "call", call, - "party", party, - NULL); -} - -CallsCall * -calls_call_data_get_call (CallsCallData *data) -{ - g_return_val_if_fail (CALLS_IS_CALL_DATA (data), NULL); - return data->call; -} - - -CallsParty * -calls_call_data_get_party (CallsCallData *data) -{ - g_return_val_if_fail (CALLS_IS_CALL_DATA (data), NULL); - return data->party; -} - - static void -get_property (GObject *object, - guint property_id, - GValue *value, - GParamSpec *pspec) +calls_call_data_init (CallsCallData *self) { - CallsCallData *self = CALLS_CALL_DATA (object); - - switch (property_id) { - case PROP_CALL: - g_value_set_object (value, self->call); - break; - - case PROP_PARTY: - g_value_set_object (value, self->party); - break; - - default: - G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec); - break; - } } @@ -128,8 +87,26 @@ set_property (GObject *object, static void -calls_call_data_init (CallsCallData *self) +get_property (GObject *object, + guint property_id, + GValue *value, + GParamSpec *pspec) { + CallsCallData *self = CALLS_CALL_DATA (object); + + switch (property_id) { + case PROP_CALL: + g_value_set_object (value, self->call); + break; + + case PROP_PARTY: + g_value_set_object (value, self->party); + break; + + default: + G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec); + break; + } } @@ -151,8 +128,8 @@ calls_call_data_class_init (CallsCallDataClass *klass) { GObjectClass *object_class = G_OBJECT_CLASS (klass); - object_class->get_property = get_property; object_class->set_property = set_property; + object_class->get_property = get_property; object_class->dispose = dispose; props[PROP_CALL] = @@ -171,3 +148,53 @@ calls_call_data_class_init (CallsCallDataClass *klass) g_object_class_install_properties (object_class, PROP_LAST_PROP, props); } + + +/** + * calls_call_data_new: + * + * Create a new #CallsCallData object. + * + * Returns: the newly created #CallsCallData + */ +CallsCallData * +calls_call_data_new (CallsCall *call, + CallsParty *party) +{ + return g_object_new (CALLS_TYPE_CALL_DATA, + "call", call, + "party", party, + NULL); +} + + +/** + * calls_call_data_get_call: + * @self: a #CallsCallData + * + * Get the #CallsCall stored in the object. + * + * Returns: the #CallsCall + */ +CallsCall * +calls_call_data_get_call (CallsCallData *self) +{ + g_return_val_if_fail (CALLS_IS_CALL_DATA (self), NULL); + return self->call; +} + + +/** + * calls_call_data_get_party: + * @self: a #CallsCallData + * + * Get the #CallsParty stored in the object. + * + * Returns: the #CallsParty + */ +CallsParty * +calls_call_data_get_party (CallsCallData *self) +{ + g_return_val_if_fail (CALLS_IS_CALL_DATA (self), NULL); + return self->party; +} diff --git a/src/calls-call-data.h b/src/calls-call-data.h index 1a95015..1a5fbcc 100644 --- a/src/calls-call-data.h +++ b/src/calls-call-data.h @@ -34,9 +34,10 @@ G_BEGIN_DECLS G_DECLARE_FINAL_TYPE (CallsCallData, calls_call_data, CALLS, CALL_DATA, GObject); -CallsCallData *calls_call_data_new (CallsCall *call, CallsParty *party); -CallsCall *calls_call_data_get_call (CallsCallData *data); -CallsParty *calls_call_data_get_party (CallsCallData *data); +CallsCallData *calls_call_data_new (CallsCall *call, + CallsParty *party); +CallsCall *calls_call_data_get_call (CallsCallData *data); +CallsParty *calls_call_data_get_party (CallsCallData *data); G_END_DECLS diff --git a/src/calls-call.c b/src/calls-call.c index 992f84e..69d30bc 100644 --- a/src/calls-call.c +++ b/src/calls-call.c @@ -29,8 +29,8 @@ void -calls_call_state_to_string (GString *string, - CallsCallState state) +calls_call_state_to_string (GString *string, + CallsCallState state) { GEnumClass *klass; GEnumValue *value; @@ -78,6 +78,15 @@ calls_call_state_parse_nick (CallsCallState *state, * SECTION:calls-call * @short_description: A call. * @Title: CallsCall + * + * This is the interface to a call. It has a number, name and a + * state. Only the state changes after creation. If the state is + * #CALL_CALL_STATE_INCOMING, the call can be answered with #answer. + * The call can also be hung up at any time with #hang_up. + * + * DTMF tones can be played the call using #tone_start and + * #tone_stop. Valid characters for the key are 0-9, '*', '#', 'A', + * 'B', 'C' and 'D'. */ @@ -89,11 +98,20 @@ enum { }; static guint signals [SIGNAL_LAST_SIGNAL]; + static void calls_call_default_init (CallsCallInterface *iface) { GType arg_types = CALLS_TYPE_CALL_STATE; + /** + * CallsCall::state-changed: + * @self: The #CallsCall instance. + * @state: The new state of the call. + * + * This signal is emitted when the state of the call changes, for + * example when it's answered or when the call is disconnected. + */ signals[SIGNAL_STATE_CHANGED] = g_signal_newv ("state-changed", G_TYPE_FROM_INTERFACE (iface), @@ -112,20 +130,55 @@ calls_call_default_init (CallsCallInterface *iface) CALLS_DEFINE_IFACE_FUNC_VOID(call, Call, CALL, function) +/** + * calls_call_get_number: + * @self: a #CallsCall + * + * Get the number the call is connected to. It is possible that this + * could return NULL if the number is not known, for example if an + * incoming PTSN call has no caller ID information. + * + * Returns: the number, or NULL + */ DEFINE_CALL_FUNC(get_number, const gchar *, NULL); + +/** + * calls_call_get_name: + * @self: a #CallsCall + * + * Get the name of the party the call is connected to, if the network + * provides it. + * + * Returns: the number, or NULL + */ DEFINE_CALL_FUNC(get_name, const gchar *, NULL); /** * calls_call_get_state: * @self: a #CallsCall * - * Get the current state of the call + * Get the current state of the call. * * Returns: the state */ DEFINE_CALL_FUNC(get_state, CallsCallState, ((CallsCallState)0)); +/** + * calls_call_answer: + * @self: a #CallsCall + * + * If the call is incoming, answer it. + * + */ DEFINE_CALL_FUNC_VOID(answer); + +/** + * calls_call_hang_up: + * @self: a #CallsCall + * + * Hang up the call. + * + */ DEFINE_CALL_FUNC_VOID(hang_up); @@ -155,5 +208,25 @@ tone_key_is_valid (gchar key) return iface->tone_##which (self, key); \ } +/** + * calls_call_tone_start: + * @self: a #CallsCall + * @key: which tone to start + * + * Start playing a DTMF tone for the specified key. Implementations + * will stop playing the tone either after an implementation-specific + * timeout, or after #calls_call_tone_stop is called with the same + * value for @key. + * + */ DEFINE_CALL_TONE_FUNC (start); + +/** + * calls_call_tone_stop: + * @self: a #CallsCall + * @key: which tone to stop + * + * Stop playing a DTMF tone previously started with #calls_call_tone_start. + * + */ DEFINE_CALL_TONE_FUNC (stop); diff --git a/src/calls-call.h b/src/calls-call.h index d18a3e2..6dbd54f 100644 --- a/src/calls-call.h +++ b/src/calls-call.h @@ -44,8 +44,8 @@ typedef enum CALLS_CALL_STATE_DISCONNECTED } CallsCallState; -void calls_call_state_to_string (GString *string, - CallsCallState state); +void calls_call_state_to_string (GString *string, + CallsCallState state); gboolean calls_call_state_parse_nick (CallsCallState *state, const gchar *nick); @@ -53,23 +53,28 @@ struct _CallsCallInterface { GTypeInterface parent_iface; - const gchar * (*get_number) (CallsCall *self); - const gchar * (*get_name) (CallsCall *self); - CallsCallState (*get_state) (CallsCall *self); - void (*answer) (CallsCall *self); - void (*hang_up) (CallsCall *self); - void (*tone_start) (CallsCall *self, gchar key); - void (*tone_stop) (CallsCall *self, gchar key); + const gchar * (*get_number) (CallsCall *self); + const gchar * (*get_name) (CallsCall *self); + CallsCallState (*get_state) (CallsCall *self); + void (*answer) (CallsCall *self); + void (*hang_up) (CallsCall *self); + void (*tone_start) (CallsCall *self, + gchar key); + void (*tone_stop) (CallsCall *self, + gchar key); }; -const gchar * calls_call_get_number (CallsCall *self); -const gchar * calls_call_get_name (CallsCall *self); -CallsCallState calls_call_get_state (CallsCall *self); -void calls_call_answer (CallsCall *self); -void calls_call_hang_up (CallsCall *self); -void calls_call_tone_start (CallsCall *self, gchar key); -void calls_call_tone_stop (CallsCall *self, gchar key); +const gchar * calls_call_get_number (CallsCall *self); +const gchar * calls_call_get_name (CallsCall *self); +CallsCallState calls_call_get_state (CallsCall *self); +void calls_call_answer (CallsCall *self); +void calls_call_hang_up (CallsCall *self); +void calls_call_tone_start (CallsCall *self, + gchar key); +void calls_call_tone_stop (CallsCall *self, + gchar key); + G_END_DECLS diff --git a/src/calls-message-source.c b/src/calls-message-source.c index c0906f8..05f5efc 100644 --- a/src/calls-message-source.c +++ b/src/calls-message-source.c @@ -24,6 +24,15 @@ #include "calls-message-source.h" +/** + * SECTION:calls-message-source + * @short_description: A source of messages for the user. + * @Title: CallsMessageSource + * + * All three of the main interfaces, #CallsProvider, #CallsOrigin and + * #CallsCall require #CallsMessageSource. They use this interface's + * message signal to emit messages intended for display to the user. + */ G_DEFINE_INTERFACE (CallsMessageSource, calls_message_source, G_TYPE_OBJECT); @@ -37,29 +46,23 @@ static guint signals [SIGNAL_LAST_SIGNAL]; static void calls_message_source_default_init (CallsMessageSourceInterface *iface) { + GType arg_types[2] = { G_TYPE_STRING, GTK_TYPE_MESSAGE_TYPE }; + + /** + * CallsMessageSource::message: + * @self: The #CallsMessageSource instance. + * @text: The message text. + * @type: The type of the message; error, warning, etc. + * + * This signal is emitted when an implementing-object needs to emit + * a message to the user. The message should be suitable for + * presentation to the user as-is. + */ signals[SIGNAL_MESSAGE] = g_signal_newv ("message", G_TYPE_FROM_INTERFACE (iface), G_SIGNAL_RUN_LAST, NULL, NULL, NULL, NULL, G_TYPE_NONE, - 2, calls_message_signal_arg_types()); -} - - -GType * -calls_message_signal_arg_types() -{ - static gsize initialization_value = 0; - static GType arg_types[2]; - - if (g_once_init_enter (&initialization_value)) - { - arg_types[0] = G_TYPE_STRING; - arg_types[1] = GTK_TYPE_MESSAGE_TYPE; - - g_once_init_leave (&initialization_value, 1); - } - - return arg_types; + 2, arg_types); } diff --git a/src/calls-message-source.h b/src/calls-message-source.h index a97fa84..57754fd 100644 --- a/src/calls-message-source.h +++ b/src/calls-message-source.h @@ -40,11 +40,38 @@ struct _CallsMessageSourceInterface GTypeInterface parent_iface; }; -#define CALLS_ERROR(obj,error) \ - CALLS_EMIT_ERROR (CALLS_MESSAGE_SOURCE (obj), error) -/** Array of GTypes for message signals */ -GType * calls_message_signal_arg_types(); + +/** + * CALLS_EMIT_MESSAGE: + * @obj: an object which can be cast to a #CallsMesssageSource + * @text: the message text as a string + * @type: the type of the message + * + * Emit a message signal with the specified information. This is a + * convenience macro for objects implementing interfaces that + * require #CallsMessageSource. + * + */ +#define CALLS_EMIT_MESSAGE(obj,text,type) \ + g_signal_emit_by_name (CALLS_MESSAGE_SOURCE(obj), \ + "message", text, type) + + +/** + * CALLS_ERROR: + * @obj: an object which can be cast to a #CallsMesssageSource + * @error: a pointer to a #GError containing the error message + * + * Emit a message signal with an error type, the text of which is + * contained as the message in a #GError. This is a convenience + * macro for objects implementing interfaces that require + * #CallsMessageSource. + * + */ +#define CALLS_ERROR(obj,error) \ + CALLS_EMIT_MESSAGE (obj, error->message, GTK_MESSAGE_ERROR) + G_END_DECLS diff --git a/src/calls-ofono-call.c b/src/calls-ofono-call.c index 201c8a3..e024923 100644 --- a/src/calls-ofono-call.c +++ b/src/calls-ofono-call.c @@ -177,10 +177,8 @@ set_properties (CallsOfonoCall *self, g_variant_lookup (props, "Name", "s", &self->name); g_variant_lookup (props, "State", "&s", &str); - if (str) - { - calls_call_state_parse_nick (&self->state, str); - } + g_return_if_fail (str != NULL); + calls_call_state_parse_nick (&self->state, str); } diff --git a/src/meson.build b/src/meson.build index 7ada3ef..0100f6e 100644 --- a/src/meson.build +++ b/src/meson.build @@ -23,19 +23,10 @@ gnome = import('gnome') -#libgd = subproject('libgd', -# default_options: [ -# 'with-main-box=true' -# ] -#) - - -#libgd_dep = libgd.get_variable('libgd_dep') -deps = [ dependency('gobject-2.0'), - dependency('gtk+-3.0'), - dependency('libhandy-0.0'), -# libgd.get_variable('libgd_dep') - ] +calls_deps = [ dependency('gobject-2.0'), + dependency('gtk+-3.0'), + dependency('libhandy-0.0'), + ] enum_headers = ['calls-call.h'] sources = ['calls-message-source.c', 'calls-message-source.h', @@ -64,9 +55,7 @@ calls_resources = gnome.compile_resources( c_name: 'call', ) -# Pass as dependency to another target - executable('calls', sources, enum_sources, calls_resources, - dependencies : deps, + dependencies : calls_deps, link_with : gdbofono_lib, include_directories : include_directories('..')) diff --git a/src/util.h b/src/util.h index 85851d3..02511a1 100644 --- a/src/util.h +++ b/src/util.h @@ -99,13 +99,6 @@ G_BEGIN_DECLS ptr = new_value; -#define CALLS_EMIT_MESSAGE(obj,text,type) \ - g_signal_emit_by_name (obj, "message", text, type) - -#define CALLS_EMIT_ERROR(obj,error) \ - CALLS_EMIT_MESSAGE (obj, error->message, GTK_MESSAGE_ERROR) - - /** Find a particular pointer value in a GtkListStore */ gboolean calls_list_store_find (GtkListStore *store,