# HG changeset patch # User rosfran # Date 1174425838 0 # Node ID c1601c03cc7821c7123aab67d87f3dbfb688b145 # Parent 18916d01fd457a30f2b48e36225265cecc44324b [svn r425] Added internal DOxygen documentation. diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_backendinfo.c --- a/gmyth/src/gmyth_backendinfo.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_backendinfo.c Tue Mar 20 21:23:58 2007 +0000 @@ -1,11 +1,14 @@ - /** * GMyth Library * * @file gmyth/gmyth_backend_info.c * + * @brief

This component represents all the MythTV backend server + * configuration information. + * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. * @author Hallyson Melo + * @author Rosfran Borges * *//* * diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_backendinfo.h --- a/gmyth/src/gmyth_backendinfo.h Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_backendinfo.h Tue Mar 20 21:23:58 2007 +0000 @@ -3,9 +3,12 @@ * * @file gmyth/gmyth_backend_info.h * + * @brief

This component represents all the MythTV backend server + * configuration information. * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. * @author Hallyson Melo + * @author Rosfran Borges * *//* * diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_common.c --- a/gmyth/src/gmyth_common.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_common.c Tue Mar 20 21:23:58 2007 +0000 @@ -7,6 +7,7 @@ * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. * @author Leonardo Sobral Cunha + * @author Rosfran Borges * *//* * @@ -110,7 +111,7 @@ static void free_channel_data (gpointer data, gpointer user_data) { - // Frees the GMythChannelInfo structure + /* Frees the GMythChannelInfo structure */ g_free(data); } diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_common.h --- a/gmyth/src/gmyth_common.h Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_common.h Tue Mar 20 21:23:58 2007 +0000 @@ -7,6 +7,7 @@ * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. * @author Leonardo Sobral Cunha + * @author Rosfran Borges * *//* * diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_file_transfer.c --- a/gmyth/src/gmyth_file_transfer.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_file_transfer.c Tue Mar 20 21:23:58 2007 +0000 @@ -225,7 +225,10 @@ } /** - * Creates a new instance of GMyth File Transfer. + * Creates a new instance of GMythFileTransfer. + * + * @param backend_info The BackendInfo instance, with all the MythTV network + * configuration data. * * @return a new instance of the File Transfer. */ @@ -240,6 +243,13 @@ return transfer; } +/** + * Creates a new instance of GMythFileTransfer. + * + * @param uri_str The URI poiting to the MythTV backend server. + * + * @return a new instance of the File Transfer. + */ GMythFileTransfer* gmyth_file_transfer_new_with_uri (const gchar* uri_str) { @@ -250,6 +260,14 @@ return transfer; } +/** + * Open a File Transfer connection in order to get a remote file. + * + * @param transfer The actual File Transfer instance. + * @param filename The file name of the remote file to be transfered to the client. + * + * @return true, if the connection opening had been done successfully. + */ gboolean gmyth_file_transfer_open (GMythFileTransfer *transfer, const gchar* filename) { @@ -285,6 +303,13 @@ } +/** + * Connect a File Transfer binary client socket to a remote file. + * + * @param transfer The actual File Transfer instance. + * + * @return true, if the connection had been configured successfully. + */ static gboolean gmyth_connect_to_backend (GMythFileTransfer *transfer) { @@ -385,6 +410,14 @@ return ret; } +/** + * Receives a GObject signal coming from a LiveTV instance, all the time a + * program info changes. + * + * @param transfer The actual File Transfer instance. + * @param msg_code The MythTV backend message status code. + * @param live_tv A pointer to the LiveTV instance. * + */ void gmyth_file_transfer_emit_program_info_changed_signal ( GMythFileTransfer *transfer, gint msg_code, gpointer live_tv ) @@ -404,6 +437,13 @@ } +/** + * Checks if the actual File Transfer connection is open. + * + * @param transfer The actual File Transfer instance. + * + * @return true, if the File Transfer connection is opened. + */ gboolean gmyth_file_transfer_is_open (GMythFileTransfer *transfer) { @@ -433,6 +473,11 @@ return ( strlist != NULL && gmyth_string_list_get_int( strlist, 0 ) == 1 ); } +/** + * Closes a remote File Transfer connection. + * + * @param transfer The actual File Transfer instance. + */ void gmyth_file_transfer_close( GMythFileTransfer *transfer ) { @@ -472,6 +517,15 @@ } +/** + * Do a seek operation (moves the read/write file pointer) on a remote file. + * + * @param transfer The actual File Transfer instance. + * @param pos The position to be moved in the remote file. + * @param whence Tells to what direction seek movement should be done. + * + * @return The actual position on the remote file (after seek has been done). + */ gint64 gmyth_file_transfer_seek(GMythFileTransfer *transfer, guint64 pos, gint whence) { @@ -510,6 +564,14 @@ return retval; } +/** + * Acquire access to a remote file socket read/write pointer. + * + * @param transfer The actual File Transfer instance. + * @param do_wait Waits or not on a GCond, when trying to read from the remote socket. + * + * @return true, if the acquire had been got. + */ static gboolean myth_control_acquire_context( GMythFileTransfer *transfer, gboolean do_wait ) { @@ -538,6 +600,13 @@ return ret; } +/** + * Release access to a remote file socket read/write pointer. + * + * @param transfer The actual File Transfer instance. + * + * @return true, if the socket read/write permissions had been releaseds. + */ static gboolean myth_control_release_context( GMythFileTransfer *transfer ) { @@ -558,6 +627,19 @@ return ret; } +/** + * Reads a block from a remote file. + * + * @param transfer The actual File Transfer instance. + * @param data A GByteArray instance, where all the binary data representing + * the remote file will be stored. + * @param size The block size, in bytes, to be requested from a remote file. + * @param read_unlimited Tells the backend to read indefinitely (LiveTV), or only + * gets the actual size + * + * @return The actual block size (in bytes) returned by REQUEST_BLOCK message, + * or the error code. + */ gint gmyth_file_transfer_read(GMythFileTransfer *transfer, GByteArray *data, gint size, gboolean read_unlimited) { @@ -574,7 +656,7 @@ GIOCondition io_cond_control; GIOStatus io_status = G_IO_STATUS_NORMAL, io_status_control = G_IO_STATUS_NORMAL; - gboolean ret = TRUE; + gboolean ret = TRUE; GString *query; @@ -712,6 +794,7 @@ return total_read; } + static void gmyth_file_transfer_program_info_changed( GMythFileTransfer *transfer, gint msg_code, gpointer livetv_transfer ) @@ -733,6 +816,15 @@ } +/** + * Sets the timeout flag of a file being transfered. + * + * @param transfer The actual File Transfer instance. + * @param fast If this is true, sets the remote timeout to be as fast + * as possible. + * + * @return true, if the acquire had been got. + */ gboolean gmyth_file_transfer_settimeout( GMythFileTransfer *transfer, gboolean fast ) { @@ -765,6 +857,13 @@ return TRUE; } +/** + * Gets the actual file size of the binary content. + * + * @param transfer The actual File Transfer instance. + * + * @return The actual file size in bytes. + */ guint64 gmyth_file_transfer_get_filesize (GMythFileTransfer *transfer) { diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_programinfo.c --- a/gmyth/src/gmyth_programinfo.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_programinfo.c Tue Mar 20 21:23:58 2007 +0000 @@ -3,10 +3,11 @@ * * @file gmyth/gmyth_programinfo.c * - * @brief

GMythFileTransfer deals with the file streaming media remote/local - * transfering to the MythTV frontend. + * @brief

GMythProgramInfo representing the program info, with the + * configuration data to the actual remote file in the TV chain. * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. + * @author Rosfran Borges * @author Leonardo Sobral Cunha * *//* @@ -251,6 +252,16 @@ return program_info; } +/** + * Converts an instance of a GMythProgramInfo, to a GMythStringList. + * + * @param prog A GMythProgramInfo instance. + * @param slist The GMythStringList to be passed to this function, in order to + * give the responsibility of the string list creation to the + * API user. + * + * @return a GMythStringList with the program info fields. + */ GMythStringList* gmyth_program_info_to_string_list (GMythProgramInfo *prog, GMythStringList *slist) { @@ -319,6 +330,13 @@ return slist; } +/** + * Converts an instance of a GMythStringList, to a GMythProgramInfo. + * + * @param slist The GMythStringList got from the MythTV backend server. + * + * @return a GMythProgramInfo representing the string list got from network. + */ GMythProgramInfo* gmyth_program_info_from_string_list ( GMythStringList *slist ) { @@ -397,6 +415,13 @@ return ( str != NULL && str->str != NULL && strlen( str->str ) > 0 ? str->str : " " ); } +/** + * Prints out an instance of a GMythProgramInfo. + * + * @param prog A GMythProgramInfo instance. + * + * @return a string representing the program info. + */ const gchar* gmyth_program_info_to_string( const GMythProgramInfo* prog ) { diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_programinfo.h --- a/gmyth/src/gmyth_programinfo.h Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_programinfo.h Tue Mar 20 21:23:58 2007 +0000 @@ -1,11 +1,13 @@ /** * GMyth Library + * + * @file gmyth/gmyth_programinfo.h * - * @file gmyth/gmyth_common.h - * - * @brief

This file contains basic common functions for the gmyth library. + * @brief

GMythProgramInfo representing the program info, with the + * configuration data to the actual remote file in the TV chain. * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. + * @author Rosfran Borges * @author Leonardo Sobral Cunha * *//* @@ -23,6 +25,7 @@ * You should have received a copy of the GNU Lesser General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * */ #ifndef _GMYTH_PROGRAMINFO_H diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_recorder.c --- a/gmyth/src/gmyth_recorder.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_recorder.c Tue Mar 20 21:23:58 2007 +0000 @@ -1,14 +1,15 @@ /** * GMyth Library * - * @file gmyth/gmyth_remote_encoder.c + * @file gmyth/gmyth_recorder.c * - * @brief

GMythRecorder class defines functions for playing live tv. + * @brief

GMythRecorder defines functions for playing live tv. * * The remote encoder is used by gmyth_tvplayer to setup livetv. * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. * @author Hallyson Luiz de Morais Melo + * @author Rosfran Borges * *//* * @@ -115,6 +116,7 @@ /** Configures the remote encoder instance connecting it to Mythtv backend. * * @param recorder the GMythRecorder instance. + * * @return TRUE if successfull, FALSE if any error happens. */ gboolean @@ -754,6 +756,13 @@ } +/** + * Requests the actual remote file position on a LiveTV instance. + * + * @param recorder The GMythRecorder instance. + * + * @return The position, in bytes, of the offset to the read header. + */ gint64 gmyth_recorder_get_file_position ( GMythRecorder *recorder ) { @@ -786,6 +795,13 @@ } +/** + * Asks MythTV backend server about if it started to record the remote file. + * + * @param recorder The GMythRecorder instance. + * + * @return true, if the actual remote file is bein recorded. + */ gboolean gmyth_recorder_is_recording ( GMythRecorder *recorder ) { @@ -824,6 +840,13 @@ } +/** + * Finish remote file recording process. + * + * @param recorder The GMythRecorder instance. + * + * @return true, if the recording had been actually closed. + */ gboolean gmyth_recorder_finish_recording ( GMythRecorder *recorder ) { diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_recorder.h --- a/gmyth/src/gmyth_recorder.h Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_recorder.h Tue Mar 20 21:23:58 2007 +0000 @@ -3,10 +3,13 @@ * * @file gmyth/gmyth_recorder.h * - * @brief

GMythRecorder class defines functions for playing live tv. + * @brief

GMythRecorder defines functions for playing live tv. + * + * The remote encoder is used by gmyth_tvplayer to setup livetv. * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. * @author Hallyson Luiz de Morais Melo + * @author Rosfran Borges * *//* * diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_remote_util.c --- a/gmyth/src/gmyth_remote_util.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_remote_util.c Tue Mar 20 21:23:58 2007 +0000 @@ -7,6 +7,7 @@ * * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. * @author Hallyson Luiz de Morais Melo + * @author Rosfran Borges * *//* * @@ -35,10 +36,12 @@ #include "gmyth_stringlist.h" #include "gmyth_debug.h" -/** Requests the Mythtv backend for a free remote recorder. +/** + * Requests the Mythtv backend for a free remote recorder. * * @param socket The socket instance where to send the command. * @param curr The recorder index, or -1 to consider the first one. + * * @return the remote encoder instance available, or NULL if any error happens. */ GMythRecorder* @@ -83,6 +86,7 @@ * Requests the Mythtv backend for the number of free remote recorders. * * @param socket The socket instance where to send the command. + * * @return the number of remote encoders instance available, or 0 if no one is actually free.. */ gint diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_uri.c --- a/gmyth/src/gmyth_uri.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_uri.c Tue Mar 20 21:23:58 2007 +0000 @@ -125,7 +125,8 @@ G_OBJECT_CLASS (gmyth_uri_parent_class)->finalize (object); } -/** Creates a new instance of GMythURI. +/** + * Creates a new instance of GMythURI. * * @return a new instance of GMythURI. */ @@ -137,7 +138,10 @@ return gmyth_uri; } -/** Creates a new instance of GMythURI. +/** + * Creates a new instance of GMythURI. + * + * @param uri_str The URI string representing this URI instance. * * @return a new instance of GMythURI. */ @@ -151,6 +155,15 @@ return gmyth_uri; } +/** + * Gets the starting offset of a substring inside a given string. + * + * @param haystack The given string to be searched for patterns. + * @param needle The substring that should be matched over the haystack. + * + * @return The starting offset to the given substring, or -1 if the + * haystack function parameter doesn't contains the needle string argument. + */ static gint gmyth_strstr (const gchar *haystack, const gchar *needle) { @@ -167,6 +180,13 @@ } +/** + * Checks if a URI is absolute. + * + * @param uri The GMythURI instance. + * + * @return true, if the URI is absolute. + */ static gboolean gmyth_uri_isabsolute (const GMythURI *uri) { @@ -180,6 +200,19 @@ return ret; } +/** + * Searches for the first reverse character occurrence, from a given + * list of characters, inside a given string. + * + * @param str The given string to be searched for characters occurrence. + * @param chars The characters list. If this string returns 4 on strlen, there are + * four possible characters to be matched. + * @param nchars The number of characters to be matched, which has at most + * strlen(chars). + * + * @return The starting offset to the first character occurrence, + * or -1 if the no character of the list could be found. + */ static gint gmyth_strrchr( const gchar *str, const gchar *chars, const gint nchars ) { @@ -211,6 +244,13 @@ return ""; } +/** + * Parses a URI string into a GMythURI instance. + * + * @param uri The GMythURI instance. + * @param value The URI string to be parsed. + * + */ static void gmyth_uri_parser_setup_and_new( GMythURI *uri, const gchar *value ) { @@ -364,6 +404,13 @@ } +/** + * Gets the channel name fro a URI instance. + * + * @param uri The GMythURI instance. + * + * @return The channel name, got from the substring "?channel=[channel_name]". + */ gchar* gmyth_uri_get_channel_name( GMythURI* uri ) { diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_util.c --- a/gmyth/src/gmyth_util.c Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_util.c Tue Mar 20 21:23:58 2007 +0000 @@ -1,29 +1,31 @@ /** -* GMyth Library -* -* @file gmyth/gmyth_util.c -* -* @brief

This component provides utility functions. -* -* Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. -* @author Hallyson Luiz de Morais Melo -* -*//* -* -* This program is free software; you can redistribute it and/or modify -* it under the terms of the GNU Lesser General Public License as published by -* the Free Software Foundation; either version 2 of the License, or -* (at your option) any later version. -* -* This program is distributed in the hope that it will be useful, -* but WITHOUT ANY WARRANTY; without even the implied warranty of -* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -* GNU General Public License for more details. -* -* You should have received a copy of the GNU Lesser General Public License -* along with this program; if not, write to the Free Software -* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -*/ + * GMyth Library + * + * @file gmyth/gmyth_util.c + * + * @brief

This component provides utility functions + * (dealing with dates, time, string formatting, etc.). + * + * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. + * @author Hallyson Luiz de Morais Melo + * @author Rosfran Borges + * + *//* + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ #ifdef HAVE_CONFIG_H #include "config.h" @@ -394,11 +396,13 @@ return time; } -/** Decodes a long long variable from the string list +/** + * Decodes a long long variable from the string list * format of the myhtprotocol. * * @param strlist the string list of mythprotocol values * @param offset the list node offset of the long long variable + * * @return gint64 the long long converted value */ gint64 @@ -424,6 +428,14 @@ } +/** + * Checks if the given remote file exists. + * + * @param backend_info The GMythBackendInfo instance. + * @param filename The file name of the remote file. + * + * @return true, if the remote file exists. + */ gboolean gmyth_util_file_exists (GMythBackendInfo *backend_info, const gchar* filename) { @@ -464,6 +476,15 @@ return res; } +/** + * Checks if the given remote file exists, and gets its remote directory. + * + * @param backend_info The GMythBackendInfo instance. + * @param filename The file name of the remote file. + * @param current_dir String pointer to the directory where the remote file is stored. + * + * @return true, if the remote file exists. + */ gboolean gmyth_util_file_exists_and_get_remote_dir (GMythBackendInfo *backend_info, const gchar* filename, gchar** current_dir) @@ -511,6 +532,15 @@ return res; } +/** + * Creates a file name to a possible existing remote file, + * based on some fields of the LiveTV/recorded program info. + * + * @param chan_id The channel ID number. + * @param start_time The start time of the recording. + * + * @return The string representing the file name. + */ gchar* gmyth_util_create_filename( const gint chan_id, const GTimeVal* start_time ) { diff -r 18916d01fd45 -r c1601c03cc78 gmyth/src/gmyth_util.h --- a/gmyth/src/gmyth_util.h Tue Mar 20 15:08:35 2007 +0000 +++ b/gmyth/src/gmyth_util.h Tue Mar 20 21:23:58 2007 +0000 @@ -1,29 +1,31 @@ /** -* GMyth Library -* -* @file gmyth/gmyth_util.h -* -* @brief

This component provides utility functions. -* -* Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. -* @author Hallyson Luiz de Morais Melo -* -*//* -* -* This program is free software; you can redistribute it and/or modify -* it under the terms of the GNU Lesser General Public License as published by -* the Free Software Foundation; either version 2 of the License, or -* (at your option) any later version. -* -* This program is distributed in the hope that it will be useful, -* but WITHOUT ANY WARRANTY; without even the implied warranty of -* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -* GNU General Public License for more details. -* -* You should have received a copy of the GNU Lesser General Public License -* along with this program; if not, write to the Free Software -* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -*/ + * GMyth Library + * + * @file gmyth/gmyth_util.h + * + * @brief

This component provides utility functions + * (dealing with dates, time, string formatting, etc.). + * + * Copyright (C) 2006 INdT - Instituto Nokia de Tecnologia. + * @author Hallyson Luiz de Morais Melo + * @author Rosfran Borges + * + *//* + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Lesser General Public License as published by + * the Free Software Foundation; either version 2 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public License + * along with this program; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + */ #ifndef GMYTH_UTIL_H_ #define GMYTH_UTIL_H_