# HG changeset patch
# User rosfran
# Date 1174403315 0
# Node ID 18916d01fd457a30f2b48e36225265cecc44324b
# Parent  fb1b1b2f16cc304662e1b5fc41d6d9796e2ee087
[svn r424] Added documention.

diff -r fb1b1b2f16cc -r 18916d01fd45 gmyth/src/gmyth_file_transfer.c
--- a/gmyth/src/gmyth_file_transfer.c	Tue Mar 20 14:46:32 2007 +0000
+++ b/gmyth/src/gmyth_file_transfer.c	Tue Mar 20 15:08:35 2007 +0000
@@ -224,7 +224,11 @@
   G_OBJECT_CLASS (gmyth_file_transfer_parent_class)->finalize (object);
 }
 
-// fixme: do we need the card_id????
+/** 
+ * Creates a new instance of GMyth File Transfer.
+ * 
+ * @return a new instance of the File Transfer. 
+ */
 GMythFileTransfer*
 gmyth_file_transfer_new ( const GMythBackendInfo *backend_info)
 {
diff -r fb1b1b2f16cc -r 18916d01fd45 gmyth/src/gmyth_monitor_handler.c
--- a/gmyth/src/gmyth_monitor_handler.c	Tue Mar 20 14:46:32 2007 +0000
+++ b/gmyth/src/gmyth_monitor_handler.c	Tue Mar 20 15:08:35 2007 +0000
@@ -153,7 +153,7 @@
 	{
 		g_main_context_acquire( context );
 		
-		source = g_main_context_find_source_by_id( g_main_context_default(), 
+		source = g_main_context_find_source_by_id( context, 
 						monitor->sid_io_watch );
 		
 		if ( source != NULL )
@@ -165,6 +165,7 @@
 		
 	}
 
+  /* mutex to control access to the event socket consumer thread */
   if ( monitor->mutex != NULL )
   {
   	g_mutex_free( monitor->mutex );
@@ -209,19 +210,28 @@
   G_OBJECT_CLASS (gmyth_monitor_handler_parent_class)->finalize (object);
 }
 
-// fixme: do we need the card_id????
+/** 
+ * Creates a new instance of GMyth Monitor Handler.
+ * 
+ * @return a new instance of the Monitor Handler. 
+ */
 GMythMonitorHandler*
 gmyth_monitor_handler_new ( void )
 {
   GMythMonitorHandler *monitor = GMYTH_MONITOR_HANDLER ( 
   					g_object_new ( GMYTH_MONITOR_HANDLER_TYPE, FALSE ) );
 
-  /* mutex to control access to the event socket consumer thread */
-  //monitor->mutex = g_mutex_new();
-
   return monitor;
 }
 
+/** 
+ * Acquire the mutex to have access to the IO Watcher listener.
+ * 
+ * @param monitor The GMythMonitorHandler instance.
+ * @param do_wait Tells the IO Watcher to wait on the GCond. (obsolete)
+ * 
+ * @return <code>true</code>, if the access to IO Watcher was acquired. 
+ */
 static gboolean 
 myth_control_acquire_context( GMythMonitorHandler *monitor, gboolean do_wait ) 
 {
@@ -234,6 +244,13 @@
   
 }
 
+/** 
+ * Release the mutex to have access to the IO Watcher listener.
+ * 
+ * @param monitor The GMythMonitorHandler instance.
+ * 
+ * @return <code>true</code>, if the access to IO Watcher was released. 
+ */
 static gboolean 
 myth_control_release_context( GMythMonitorHandler *monitor ) 
 {
@@ -269,6 +286,16 @@
 
 }
 
+/** 
+ * Opens connection the the Monitor socket on MythTV backend server,
+ * where all status messages are notified to the client.
+ * 
+ * @param monitor The GMythMonitorHandler instance.
+ * @param hostname The remote host name of the MythTV backend server.
+ * @param port The remote port number of the MythTV backend server.
+ * 
+ * @return <code>true</code>, if the connection was successfully opened.
+ */
 gboolean
 gmyth_monitor_handler_open (GMythMonitorHandler *monitor, const gchar *hostname, gint port)
 {
@@ -300,6 +327,16 @@
 
 }
 
+/** 
+ * Reads the data got from the connection to the Monitor socket,
+ * and looks for some important status messages.
+ * 
+ * @param monitor The GMythMonitorHandler instance.
+ * @param strlist The GMythStringList instance got from the Monitor remote socket.
+ * @param back_msg_action A string pointer to the status message detailed description.
+ * 
+ * @return The backend status message code ID.
+ */
 static gint
 gmyth_monitor_handler_is_backend_message( GMythMonitorHandler *monitor,
                         GMythStringList* strlist, gchar **back_msg_action )
@@ -371,6 +408,16 @@
 	gmyth_debug( "Backend message event: %s --- ", str->str );
 }
 
+/** 
+ * Opens connection the the Monitor socket on MythTV backend server,
+ * where all status messages are notified to the client.
+ * 
+ * @param io_channel The GIOChannel instance to the Monitor connection.
+ * @param io_cond The GIOCondition describing the actual status of the IO Channel.
+ * @param data Pointer to the GMythMonitorHandler.
+ * 
+ * @return <code>true</code>, if the data was successfully read.
+ */
 gboolean
 gmyth_monitor_handler_listener( GIOChannel *io_channel, GIOCondition io_cond, gpointer data )
 {
@@ -399,7 +446,7 @@
   GMythStringList *strlist = NULL;
   
   if ( NULL == io_channel ) {
-  	g_debug ("Monitor socket is NULL!\n");
+  	gmyth_debug ("Monitor socket is NULL! (GIOChannel)");
   	*ret = FALSE;
   	goto clean_up;
   }
@@ -477,6 +524,14 @@
 
 }
 
+/** 
+ * Opens connection events' socket the the Monitor socket on 
+ * MythTV backend server.
+ * 
+ * @param monitor The GMythMonitorHandler instance.
+ * 
+ * @return <code>true</code>, if the socket was successfully opened.
+ */
 static gboolean
 gmyth_connect_to_backend_monitor (GMythMonitorHandler *monitor)
 {
@@ -496,6 +551,16 @@
   return ret;
 }    
 
+/** 
+ * Opens connection the the Monitor socket on MythTV backend server,
+ * where all status messages are notified to the client.
+ * 
+ * @param monitor The GMythMonitorHandler instance.
+ * @param channel The GIOChannel instance to the Monitor socket.
+ * 
+ * @return Pointer to the boolean value, and it is <code>true</code> only if the 
+ * 				 GMythMonitorHandler could be configured.
+ */
 static gboolean*
 gmyth_monitor_handler_setup( GMythMonitorHandler *monitor, GIOChannel *channel )
 {
@@ -526,6 +591,13 @@
   
 }
 
+/** 
+ * Starts the MonitorHandler thread to the GIOWatcher.
+ * 
+ * @param monitor The GMythMonitorHandler instance.
+ * 
+ * @return <code>true</code>, if the MonitorHandler was started.
+ */
 gboolean 
 gmyth_monitor_handler_start (GMythMonitorHandler *monitor)
 {