RSS Reader Documentation

1.0

INTRODUCTION

RSS and RSS Reader

RSS reader is a program which downloads information from RSS channels and shows these information to the user. RSS channel is an internet file stored typically on the server which provides some news or articles. This file must have special format which is called RSS and is derived from XML. The file contains information about the server (title, URL, text encoding, etc.) and short information about a number of latest news (typically 5-20). Each of the news is called channel item (spot) and contains title, short article description, URL to the complete article, etc.). RSS reader downloads this file, analysis it, stores new channel spots and shows them to the user with URL to complete article text.

My RSS reader supports four main RSS formats: RSS 0.91, RSS 0.92, RSS 2.0 and RSS 1.0. First three are very similar, there are only little differences in required and optional RSS (XML) entities. RSS 1.0 specification comes from another institution than the previous three. It uses other XML entities and attributes.

Specifications:

One of the main program parts is RSS parsing. Each of the RSS versions is represented by one class, all of them are inherited from abstract class RssChannel.

RSS updating and threads

RSS channels can be updated manually (user can select "Update folder" or "Update channel") or automatically (each channel has its updating interval specified (typically 30 minutes or more) or global settings is used). All of these updates are done in separate threads (derived from wxThread). As these threads needs to write new channel items to the database it's necessary to controll accessing it. The goal is to enable accessing (reading or writing) the database by only one thread (GUI or updating) and this is guaranteed by one global critical section (wxCriticalSection) which is entered every time I need to access the database and left after all db commands are finished.

Updating threads: CUpdateChannelThread, CUpdateFolderThread, CAutomaticUpdateThread

Encoding

Program encoding is Unicode which is the reason for using wxWidgets _T macro around all strings. It also causes that RSS reader can't be run on Windows 95, 98, ME which have no Unicode support. On the other hand database encoding is UTF-8 because SQLite doesn't support Unicode now. How it works together? RSS channels use different encodings (UTF-8, ISO-8859-2, Windows-1250, etc.) so first the parsed channel data is transfered into UTF-8 and than saved into database. Every time I need to use database data in the program it must be converted to Unicode. For all conversions wxWidgets classes are used.

Supported RSS encodings: UTF-8, ISO-8859-2 (Latin2), Windows-1250. It's not difficult to add more encodings. Just add two lines into RssChannel::CharConvert.

Settings and running at startup

Program configuration is loaded and saved using wxConfig class (on Windows it's implemented with registry). Which configuration is being saved? Main windows size, global channel options and main options (all from menu "Options").

Running at startup option is saved directly into Windows registry HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows\CurrentVersion\Run.

Global variables

For communicating between main program parts a couple of global variables are used
	MainFrame * g_mainFrame;               // pointer to the main frame, from this we can access  
	                                       // other main cotrols (channel tree, spot list, ...)

	wxMBConvUTF8 g_conv;                   // UTF<->Unicode converter

	sqlite3::connection g_conn;            // database connection (connection started at program
	                                       // startup and closed when program closes)

	wxCriticalSection g_dbCritSection;     // critical section for controlling database accessing,
	                                          only one thread can access db at the moment
 	

GUI

Main frame (MainFrame) is divided into three main parts -- channel and folder tree (CChannelTree), spot list with channel items titles (CSpotList) and spotview (CSpotView and spot URL). Other important classes are CTrayIcon and CInfoFrame. All the dialogs are using wxSizers to be comfortably resizeable (like on Linux).

LIBRARIES

RSS Reader application uses couple of great libraries for making the work easier. All of them are free to use and almost all also multiplatform.

wxWidgets

wxWidgets is really great C++ library for making GUI. Almost all of the classes from my application are inherited from wxWidgets classes.

I use also a class wxHyperLinkCtrl which isn't a part of standard distribution.

SQLite

SQLite is a simple database system, much more smaller then MySQL or PgSQL. It can operate with basic SQL commands and although it has strange datatype politics for the purposes of my application it was quite good choice.

SQLite offers only C API for manipulating with the system which isn't very comfortable so I use one minimalistic C++ wrapper.

TinyXml

TinyXml is really a tiny XML parser which works with DOM. Of course it hasn't got all the functionality as other parsers (ie. Xerces) do but for it completely satisfied my needs.

DATABASE STRUCTURE

RSS reader uses 3 database tables for storing data about channels, folders and channels' items (spots). See SQLite FAQ for information about datatypes in this database system.

Table folders

Table folders contains information about folders that are shown in the application channel and folder tree.

 	id INTEGER PRIMARY KEY     -- is AUTO_INCREMENT
 	parent INTEGER             -- id of my parent folder, 0 for root folder
 	title VARCHAR(60)          -- folder title
 	

Table channels

Table channels contains information about each channel which was added to the application channel and folder tree.

Not all information is currently used (description, pubDate, language).

	id INTEGER PRIMARY KEY     -- is AUTO_INCREMENT
	folder INTEGER             -- id of a folder which the channel belongs to
	title VARCHAR(150)         -- channel title
	link VARCHAR(150)          -- channel URL
	description VARCHAR(200)   -- channel description (extracted from RSS)
	language VARCHAR(10)       -- channel language (extracted from RSS)
	pubDate DATETIME           -- channel latest publication date (extracted from RSS)
	globalOpt INTEGER          -- use global options for the channel (1 yes, 0 no)
	maxSpots INTEGER           -- how many spots store in the table for this channel (-1 = no limit)
	updateInterval INTEGER     -- how often (in minutes) automatically update this channel
 	

Table spots

Table spots contains information about channel spots, which are <item> entities from RSS channel.

PubDate is currently not used.

	id INTEGER PRIMARY KEY     -- is AUTO_INCREMENT
	channel INTEGER            -- id of a channel which the spot is from
	title VARCHAR(150)         -- spot title
	link VARCHAR(150)          -- spot URL
	description TEXT           -- spot description
	pubDate VARCHAR(50)        -- spot publication date
	read INTEGER               -- was the spot read (1 yes, 0 no)
 	

PORTABILITY

All the main libraries (wxWidgets, SQLite, TinyXml) I'm using are wide portable. There were couple of small issues with compiling SQLite wrapper so the sources had to be edited.

Linux version uses wxGTK2. Linux version uses XPM graphic files instead of PNG and ICO that are used in Windows version.

AUTHOR

Michal Kebrt, UK MFF, michalek.k@seznam.cz
Generated on Tue Oct 3 20:47:11 2006 for RSSReader by  doxygen 1.4.6