From f39a3010daf2a10f71188701fd58b93d61ec992c Mon Sep 17 00:00:00 2001
From: Pierre-Luc Beaudoin <pierre-luc.beaudoin@savoirfairelinux.com>
Date: Thu, 20 Sep 2007 10:52:51 -0400
Subject: [PATCH] Doxygen doc
---
.gitignore | 4 +-
sflphone-gtk/src/accountlist.h | 37 ++++++++++++++++--
sflphone-gtk/src/accountwindow.h | 6 ++-
sflphone-gtk/src/actions.c | 46 ++---------------------
sflphone-gtk/src/actions.h | 41 +++++++++++++++-----
sflphone-gtk/src/calllist.h | 64 ++++++++++++++++++++++++++++----
sflphone-gtk/src/calltree.h | 3 ++
sflphone-gtk/src/configwindow.c | 14 +++----
sflphone-gtk/src/configwindow.h | 4 +-
sflphone-gtk/src/dbus.c | 4 --
sflphone-gtk/src/dbus.h | 3 ++
sflphone-gtk/src/dialpad.h | 4 +-
sflphone-gtk/src/main.c | 56 +++++++++++++++++++++++++++-
sflphone-gtk/src/mainwindow.h | 3 ++
sflphone-gtk/src/menus.h | 4 +-
sflphone-gtk/src/screen.h | 3 ++
sflphone-gtk/src/sliders.h | 4 +-
17 files changed, 216 insertions(+), 84 deletions(-)
diff --git a/.gitignore b/.gitignore
index 6cd92af8c8..51c1dce088 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,8 +15,8 @@ Makefile.in
# Ignore rendered docs
doc/doxygen/html-everything
doc/doxygen/html-sflphoned
-doc/doxygen/html-gui-qt
doc/*.html
+sflphone-gtk/doc/html/*
# Ignore buildsys stuff
/autom4te.cache
@@ -101,4 +101,4 @@ tools/portaudio
# Les foutus .svn
-*.svn*
\ No newline at end of file
+*.svn*
diff --git a/sflphone-gtk/src/accountlist.h b/sflphone-gtk/src/accountlist.h
index 5408d271d8..56d0d016dd 100644
--- a/sflphone-gtk/src/accountlist.h
+++ b/sflphone-gtk/src/accountlist.h
@@ -21,6 +21,9 @@
#define __ACCOUNTLIST_H__
#include <gtk/gtk.h>
+/** @file accountlist.h
+ * @brief A list to hold accounts.
+ */
#define ACCOUNT_TYPE "Account.type"
#define ACCOUNT_ALIAS "Account.alias"
@@ -39,6 +42,9 @@
#define ACCOUNT_IAX_USER "IAX.user"
#define ACCOUNT_IAX_PASS "IAX.pass"
+/** @enum account_state_t
+ * This enum have all the states an account can take.
+ */
typedef enum
{
ACCOUNT_STATE_INVALID = 0,
@@ -46,27 +52,50 @@ typedef enum
ACCOUNT_STATE_UNREGISTERED
} account_state_t;
-
+/** @struct account_t
+ * @brief Account information.
+ * This struct holds information about an account. All values are stored in the
+ * properties GHashTable except the accountID and state. This match how the
+ * server internally works and the dbus API to save and retrieve the accounts details.
+ *
+ * To retrieve the Alias for example, use g_hash_table_lookup(a->properties, ACCOUNT_ALIAS).
+ */
typedef struct {
gchar * accountID;
- account_state_t state;
- GHashTable * properties;
+ account_state_t state; GHashTable * properties;
} account_t;
+/** This function initialize the account list. */
void account_list_init ();
+/** This function empty and free the account list. */
void account_list_clean ();
+/** This function append an account to list.
+ * @param a The account you want to add */
void account_list_add (account_t * a);
+/** This function remove an account from list.
+ * @param accountID The accountID of the account you want to remove
+ */
void account_list_remove (const gchar * accountID);
-/** Return the first account that corresponds to the state */
+/** Return the first account that corresponds to the state
+ * @param s The state
+ * @return An account or NULL */
account_t * account_list_get_by_state ( account_state_t state);
+/** Return the number of accounts in the list
+ * @return The number of accounts in the list */
guint account_list_get_size ( );
+/** Return the account at the nth position in the list
+ * @param n The position of the account you want
+ * @return An account or NULL */
account_t * account_list_get_nth ( guint n );
+/** This function maps account_state_t enums to a description.
+ * @param s The state
+ * @return The full text description of the state */
const gchar * account_state_name(account_state_t s);
#endif
diff --git a/sflphone-gtk/src/accountwindow.h b/sflphone-gtk/src/accountwindow.h
index f724c2dfee..057e30c736 100644
--- a/sflphone-gtk/src/accountwindow.h
+++ b/sflphone-gtk/src/accountwindow.h
@@ -19,8 +19,10 @@
#ifndef __ACCOUNTWINDOW_H__
#define __ACCOUNTWINDOW_H__
-
+/** @file accountwindow.h
+ * @brief The window to edit account details.
+ */
+
void show_account_window ( account_t * a );
-
#endif
diff --git a/sflphone-gtk/src/actions.c b/sflphone-gtk/src/actions.c
index 62268d2742..e661f2281f 100644
--- a/sflphone-gtk/src/actions.c
+++ b/sflphone-gtk/src/actions.c
@@ -29,9 +29,7 @@
#include <dbus.h>
#include <accountlist.h>
-/**
- * Terminate the gtk program
- */
+
gboolean
sflphone_quit ()
{
@@ -53,9 +51,7 @@ sflphone_quit ()
return quit;
}
-/**
- * Put the line on hold
- */
+
void
sflphone_hold(call_t * c )
{
@@ -64,9 +60,6 @@ sflphone_hold(call_t * c )
screen_clear();
}
-/**
- * Put the call in Ringing state
- */
void
sflphone_ringing(call_t * c )
{
@@ -75,7 +68,7 @@ sflphone_ringing(call_t * c )
}
-/* Fill account list */
+/** Internal to actions: Fill account list */
void
sflphone_fill_account_list()
{
@@ -131,20 +124,6 @@ sflphone_init()
}
}
-/**
- * Put the line on hold
- */
-void
-sflphone_unhold(call_t * c )
-{
- c->state = CALL_STATE_CURRENT;
- update_call_tree(c);
- screen_set_call(c);
-}
-
-/**
- * Hang up the line
- */
void
sflphone_hang_up( call_t * c )
{
@@ -153,9 +132,6 @@ sflphone_hang_up( call_t * c )
screen_clear();
}
-/**
- * Incoming call
- */
void
sflphone_current( call_t * c )
{
@@ -164,9 +140,6 @@ sflphone_current( call_t * c )
screen_set_call(c);
}
-/**
- * Transfert the line
- */
void
sflphone_transfert( call_t * c, gchar * to )
{
@@ -174,18 +147,13 @@ sflphone_transfert( call_t * c, gchar * to )
update_call_tree_remove(c);
}
-/**
- * Signal Incoming Call
- */
void
sflphone_incoming_call (call_t * c)
{
call_list_add ( c );
update_call_tree_add(c);
}
-/**
- * Signal Hung up
- */
+
void
sflphone_hung_up (call_t * c )
{
@@ -317,10 +285,4 @@ sflphone_place_call ( call_t * c )
}
}
-void
-sflphone_remove_account ( account_t * a )
-{
- dbus_remove_account (a->accountID);
-}
-
diff --git a/sflphone-gtk/src/actions.h b/sflphone-gtk/src/actions.h
index 89fd60d197..6a9dda052a 100644
--- a/sflphone-gtk/src/actions.h
+++ b/sflphone-gtk/src/actions.h
@@ -23,6 +23,13 @@
#include <calllist.h>
#include <accountlist.h>
+/** @file actions.h
+ * @brief General functions that change the state of the application.
+ * All of these functions are called when dbus signals are triggered. Exceptions
+ * are sflphone_init() sflphone_quit(), sflphone_keypad() and sflphone_place_call().
+ */
+
+
/**
* Initialize lists and configurations
* @return TRUE if succeeded, FALSE otherwise
@@ -35,36 +42,52 @@ gboolean sflphone_init ( ) ;
*/
gboolean sflphone_quit ( ) ;
+/**
+ * Hang up the call
+ */
void sflphone_hang_up ( call_t * c);
+/**
+ * Transfert the call
+ */
void sflphone_transfert ( call_t * c, gchar * to );
+/**
+ * Put the call on hold
+ */
void sflphone_hold ( call_t * c);
+/**
+ * Put the call in Ringing state
+ */
void sflphone_ringing(call_t * c );
+/**
+ * Put the call in Current state
+ */
void sflphone_current ( call_t * c);
-void sflphone_remove_account ( account_t * a );
-
-void sflphone_unhold ( call_t * c);
-
-/* signals */
+/**
+ * The callee has hung up
+ */
void sflphone_hung_up( call_t * c);
-/* void sflphone_ring */
+/**
+ * Incoming call
+ */
void sflphone_incoming_call ( call_t * c);
/**
* Dial the number
* If the call is in DIALING state, the char will be append to the number
- * TODO If the call is in CURRENT state, the char will be also sent to the server
- * @param c A call in CALL_STATE_DIALING state
+ * @TODO If the call is in CURRENT state, the char will be also sent to the server
+ * @param keyval The unique int representing the key
+ * @param keyval The char value of the key
*/
void sflphone_keypad ( guint keyval, gchar * key);
/**
- * Place a call
+ * Place a call with a filled call_t.to
* @param c A call in CALL_STATE_DIALING state
*/
void sflphone_place_call ( call_t * c );
diff --git a/sflphone-gtk/src/calllist.h b/sflphone-gtk/src/calllist.h
index a878c0206d..4de7286d34 100644
--- a/sflphone-gtk/src/calllist.h
+++ b/sflphone-gtk/src/calllist.h
@@ -21,42 +21,90 @@
#define __CALLLIST_H__
#include <gtk/gtk.h>
-
+/** @file calllist.h
+ * @brief A list to hold calls.
+ */
+
+/** @enum call_state_t
+ * This enum have all the states a call can take.
+ */
typedef enum
-{
- CALL_STATE_INVALID = 0,
- CALL_STATE_INCOMING, /* Ringing incoming call */
- CALL_STATE_RINGING, /* Ringing outgoing call */
- CALL_STATE_CURRENT,
- CALL_STATE_DIALING,
- CALL_STATE_HOLD
+{ /** Invalid state */
+ CALL_STATE_INVALID = 0,
+ /** Ringing incoming call */
+ CALL_STATE_INCOMING,
+ /** Ringing outgoing call */
+ CALL_STATE_RINGING,
+ /** Call to which the user can speak and hear */
+ CALL_STATE_CURRENT,
+ /** Call which numbers are being added by the user */
+ CALL_STATE_DIALING,
+ /** Call is on hold */
+ CALL_STATE_HOLD
} call_state_t;
+
+/** @struct call_t
+ * @brief Call information.
+ * This struct holds information about a call.
+ */
typedef struct {
+ /** Unique identifier of the call */
gchar * callID;
+ /** The account used to place/receive the call */
gchar * accountID;
+ /** The information about the calling person. See call_get_name() and call_get_number()
+ * on how to get the name and number separately. */
gchar * from;
+ /** The number we are calling. Only used when dialing out */
gchar * to;
+ /* The current state of the call */
call_state_t state;
} call_t;
+/** This function initialize the call list. */
void call_list_init ();
+/** This function empty and free the call list. */
void call_list_clean ();
+/** This function append a call to list.
+ * @param c The call you want to add */
void call_list_add (call_t * c);
+/** This function remove a call from list.
+ * @param callID The callID of the call you want to remove
+ */
void call_list_remove (const gchar * callID);
+/** Return the first call that corresponds to the state.
+ * This is usefull for unique states as DIALING and CURRENT.
+ * @param state The state
+ * @return A call or NULL */
call_t * call_list_get_by_state ( call_state_t state);
+/** Return the number of calls in the list
+ * @return The number of calls in the list */
guint call_list_get_size ( );
+/** Return the call at the nth position in the list
+ * @param n The position of the call you want
+ * @return A call or NULL */
call_t * call_list_get_nth ( guint n );
+
+/** Return the call corresponding to the callID
+ * @param n The callID of the call you want
+ * @return A call or NULL */
call_t * call_list_get ( const gchar * callID );
+/** This function parse the call_t.from field to return the name
+ * @param c The call
+ * @return The full name of the caller or an empty string */
gchar * call_get_name (const call_t * c);
+/** This function parse the call_t.from field to return the number
+ * @param c The call
+ * @return The number of the caller */
gchar * call_get_number (const call_t * c);
#endif
diff --git a/sflphone-gtk/src/calltree.h b/sflphone-gtk/src/calltree.h
index 26a3ed01dd..8e66be11fb 100644
--- a/sflphone-gtk/src/calltree.h
+++ b/sflphone-gtk/src/calltree.h
@@ -23,6 +23,9 @@
#include <gtk/gtk.h>
#include <calllist.h>
+/** @file calltree.h
+ * @brief The GtkTreeView that list calls in the main window.
+ */
GtkWidget * create_call_tree();
void update_call_tree_add (call_t * c);
diff --git a/sflphone-gtk/src/configwindow.c b/sflphone-gtk/src/configwindow.c
index 75fd1ef6de..7a77235e06 100644
--- a/sflphone-gtk/src/configwindow.c
+++ b/sflphone-gtk/src/configwindow.c
@@ -17,11 +17,12 @@
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
-#include <config.h>
-#include <mainwindow.h>
#include <accountlist.h>
#include <accountwindow.h>
#include <actions.h>
+#include <config.h>
+#include <dbus.h>
+#include <mainwindow.h>
#include <gtk/gtk.h>
@@ -49,14 +50,13 @@ fill_account_list ()
gtk_list_store_append (account_store, &iter);
gtk_list_store_set(account_store, &iter,
- 0, g_hash_table_lookup(a->properties, ACCOUNT_ALIAS), // Name
+ 0, g_hash_table_lookup(a->properties, ACCOUNT_ALIAS), // Name
1, g_hash_table_lookup(a->properties, ACCOUNT_TYPE), // Protocol
2, account_state_name(a->state), // Status
- 3, a, // Pointer
+ 3, a, // Pointer
-1);
}
-
}
gtk_widget_set_sensitive( GTK_WIDGET(editButton), FALSE);
@@ -70,7 +70,7 @@ delete_account( GtkWidget *widget, gpointer data )
{
if(selectedAccount)
{
- sflphone_remove_account(selectedAccount);
+ dbus_remove_account(selectedAccount->accountID);
fill_account_list ();
}
}
@@ -146,7 +146,7 @@ create_accounts_tab()
gtk_widget_show(label);
sw = gtk_scrolled_window_new(NULL,NULL);
- gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(sw), GTK_POLICY_AUTOMATIC, GTK_POLICY_ALWAYS);
+ gtk_scrolled_window_set_policy(GTK_SCROLLED_WINDOW(sw), GTK_POLICY_AUTOMATIC, GTK_POLICY_AUTOMATIC);
gtk_scrolled_window_set_shadow_type(GTK_SCROLLED_WINDOW(sw), GTK_SHADOW_IN);
gtk_box_pack_start(GTK_BOX(ret), sw, TRUE, TRUE, 0);
diff --git a/sflphone-gtk/src/configwindow.h b/sflphone-gtk/src/configwindow.h
index 0acea098d7..111acaacb6 100644
--- a/sflphone-gtk/src/configwindow.h
+++ b/sflphone-gtk/src/configwindow.h
@@ -22,7 +22,9 @@
#include <calllist.h>
-
+/** @file configwindow.h
+ * @brief The Preferences window.
+ */
void show_config_window ( );
diff --git a/sflphone-gtk/src/dbus.c b/sflphone-gtk/src/dbus.c
index 5f320fe0aa..7135721306 100644
--- a/sflphone-gtk/src/dbus.c
+++ b/sflphone-gtk/src/dbus.c
@@ -100,10 +100,6 @@ call_state_cb (DBusGProxy *proxy,
{
sflphone_hold (c);
}
- else if ( strcmp(state, "UNHOLD") == 0 )
- {
- sflphone_unhold (c);
- }
else if ( strcmp(state, "RINGING") == 0 )
{
sflphone_ringing (c);
diff --git a/sflphone-gtk/src/dbus.h b/sflphone-gtk/src/dbus.h
index 2545765e9d..2493a0de73 100644
--- a/sflphone-gtk/src/dbus.h
+++ b/sflphone-gtk/src/dbus.h
@@ -24,6 +24,9 @@
#include <accountlist.h>
#include <calllist.h>
+/** @file dbus.h
+ * @brief General DBus functions wrappers.
+ */
/** @return TRUE if connection succeeded, FALSE otherwise */
gboolean dbus_connect ();
void dbus_clean ();
diff --git a/sflphone-gtk/src/dialpad.h b/sflphone-gtk/src/dialpad.h
index 940aedd8bb..82047abdda 100644
--- a/sflphone-gtk/src/dialpad.h
+++ b/sflphone-gtk/src/dialpad.h
@@ -21,7 +21,9 @@
#define __DIALPAD_H__
#include <gtk/gtk.h>
-
+/** @file dialpad.h
+ * @brief The dialpad widgets.
+ */
GtkWidget * create_dialpad();
#endif
diff --git a/sflphone-gtk/src/main.c b/sflphone-gtk/src/main.c
index fa6272b546..92cb8286a8 100644
--- a/sflphone-gtk/src/main.c
+++ b/sflphone-gtk/src/main.c
@@ -25,8 +25,6 @@
#include <gtk/gtk.h>
-
-
int
main (int argc, char *argv[])
{
@@ -48,3 +46,57 @@ There is NO WARRANTY, to the extent permitted by law.\n\n");
return 0;
}
+/** @mainpage SFLphone GTK+ Client Documentation
+ * SFLphone GTK+ Client was started as a debuging tool for the new dbus API but
+ * ended being a full featured client.
+ * @section intro_sec Architecture
+ * SFLphone respects the MVC principle. Since the internal workings and the UI
+ * are too different programs, dbus is used to exchange data between them. Dbus
+ * is thereby inforcing MVC by only allowing access to high level functions and data.
+ *
+ * Therefore, when a button is clicked, a direct dbus API call should happen
+ * (defined in dbus.h). The UI should only be updated when signals are received
+ * from dbus. The call back to those signals are defined in dbus.c, but they call
+ * functions in actions.h. This makes things cleaner as one signal could have many
+ * actions.
+ *
+ * Accounts are stored in form of a account_t in an account list with access functions
+ * defined in accountlist.h.
+ *
+ * Calls are stored in form of a call_t in a call list with access functions defined
+ * in calllist.h.
+ *
+ */
+
+// This doc is for generated files that get overridden by tools.
+/** @file marshaller.h
+ * @brief This file contains marshallers functions for dbus signals.
+ * This file is generated by glib-genmarshall.
+ * Every dbus signal has to have a marshaller. To generate a new marshaller function,
+ * add its signature to the marshaller.list. Then run :
+ * <pre>glib-genmarshal --body --g-fatal-warnings marshaller.list > marshaller.c
+ *glib-genmarshal --header --g-fatal-warnings marshaller.list > marshaller.h </pre>
+ *
+ * to get the generated marshallers.
+ * Just before connecting to the dbus signal, register the marshaller with:
+ * dbus_g_object_register_marshaller().
+ */
+
+/** @file callmanager-glue.h
+ * @brief CallManager dbus API.
+ * This file is generated by dbus-binding-tool using the server's
+ * callmanager-introspec.xml.
+ *
+ * This file dbus calls wrapper functions to simplify access to dbus API.
+ *
+ */
+
+
+/** @file configurationmanager-glue.h
+ * @brief ConfigurationManager dbus API.
+ * This file is generated by dbus-binding-tool using the server's
+ * configurationmanager-introspec.xml.
+ *
+ * This file dbus calls wrapper functions to simplify access to dbus API.
+ *
+ */
diff --git a/sflphone-gtk/src/mainwindow.h b/sflphone-gtk/src/mainwindow.h
index 49bb69913a..e8937213f9 100644
--- a/sflphone-gtk/src/mainwindow.h
+++ b/sflphone-gtk/src/mainwindow.h
@@ -22,6 +22,9 @@
#include <calllist.h>
+/** @file mainwindow.h
+ * @brief The main window of the client.
+ */
GtkAccelGroup * get_accel_group();
GtkWidget * get_main_window();
diff --git a/sflphone-gtk/src/menus.h b/sflphone-gtk/src/menus.h
index f4b84d32db..6b5b785a18 100644
--- a/sflphone-gtk/src/menus.h
+++ b/sflphone-gtk/src/menus.h
@@ -21,7 +21,9 @@
#define __MENUS_H__
#include <gtk/gtk.h>
-
+/** @file menus.h
+ * @brief The menus of the main window.
+ */
GtkWidget * create_menus();
#endif
diff --git a/sflphone-gtk/src/screen.h b/sflphone-gtk/src/screen.h
index 44db782f2c..5cc848e602 100644
--- a/sflphone-gtk/src/screen.h
+++ b/sflphone-gtk/src/screen.h
@@ -23,6 +23,9 @@
#include <gtk/gtk.h>
#include <calllist.h>
+/** @file screen.h
+ * @brief The screen at the top of the main window.
+ */
GtkWidget * create_screen();
void screen_clear();
diff --git a/sflphone-gtk/src/sliders.h b/sflphone-gtk/src/sliders.h
index f2436c4a72..a3ef0fcfb1 100644
--- a/sflphone-gtk/src/sliders.h
+++ b/sflphone-gtk/src/sliders.h
@@ -21,7 +21,9 @@
#define __SLIDERS_H__
#include <gtk/gtk.h>
-
+/** @file sliders.h
+ * @brief Volume sliders at the bottom of the main window.
+ */
GtkWidget * create_mic_slider();
GtkWidget * create_slider(const gchar * device);
--
GitLab