File	Date	Author	Commit
AdMgr	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation
Icons	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation
Res	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation
inc	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation
src	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation
LICENSE.txt	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation
README.txt	2011-03-18	Cheng Luo	[e1a675] [SERI] correct the format
application.xml	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation
manifest.xml	2011-03-17	Cheng Luo	[d1cbef] [SERI] initial creation

Read Me

BuddyFix version 2.0.1 build 2011-03-16
=====================================


INTRODUCTION
------------

BuddyFix is the Samsung bada location based social networking application developed by Samsung Electronics Research Institute in UK. This free application aims to demonstrate the bada Server side features, e.g. location services and social services. It was first used by the bada book "Introduction to bada - A Developer's Guide" (www.wiley.com/go/bada). After a certain time, this application has been evolved into a decent application allows friends and family to keep contact with each other and allocate them on the map. 


COMPILATION
-----------

This application is developed on the bada public SDK 1.2.0. And has been tested on Wave S8500 (firmware version XX-JK2) device. 

***IMPORTANT*** 
To build this application, you have to get your own manifest file developer.bada.com and use your own user name and password for the deCarta map. And please also read the help document (from [bada SDK root]/Tools/Ad-Manager-Package.zip) of how to configure your IDE for using the AdManager library. 

DEPENDENCIES
------------

BuddyFix uses the deCarta Ad Library version 1.2 (http://developer.decarta.com) to get the advertisement from NavTeq server. Due to the privacy, developers have to use their own user name and password for the map and ads server setting strings. 

DIRECTORY STRUCTURE
-------------------

AdMgr/
Icons/			All icon images
inc/			header files for BuddyFix
|--Managers		Controllers header files
|--UI			UI header files
+--Utils		Static utilities header files
src/			Source files 
|--Managers		Controllers source files		
|--UI			UI source files 
+--Utils		Static Utilities source files 
Res/			UI resource files: e.g. UI Buidler files


TIMERS USED IN BUDDYFIX
-----------------------

There are 7 different places have used the Timer object. 
 * DatabaseManager class 
	- maintain the periodic request of CRUD-ing the persistent data stored in the database

 * LocationManager class (x2)
	- maintain the periodic request of updating the device's location
	- maintain the periodic request of receiving friends's locations

 * BuddyRequestForm class
	- maintain the periodic request of receiving incoming invitations

 * FormAnimation class
	- maintain the animated drawing of two bitmaps on the animation form

 * MapViewForm class
	- maintain the periodic request of fetching the advertisement

 * Utils class
	- maintain the time-out of the Waiting pop-ups

USER EVENT HANDLING
-------------------

The custom event handling in BuddyFix is done through the FormManager class. It is the central event dispatcher of the entire application. There are also some other classes handling partial custom event, such as BuddyManagmentForm and LaunchWizard classes. In most of situation, the asynchronous callbacks-e.g. OnTargetLocationsReceivedN() methods implemented by the Manager classes - e.g. LocationManager will forward the event to the FormManager. And the FormManager class will take the further responsibilites to proxy the event to the particular event destinations. 

The following figure gives you the brief idea how the event is handled in BuddyFix:

 +----------+    +=============+    +-----------------+   
 | Managers |--->| FormManager |--->| single UI Forms | 
 +----------+    +=============+    +-----------------+


 +----------+    +=============+    +=====================+   	 +--------------+
 | Managers |--->| FormManager |--->| BuddyManagementForm |----->| Groups panel |
 +----------+    +=============+    +=====================+  |   +--------------+
							     |	
							     |	 +--------------+
							     +-->| Import panel |
							     |	 +--------------+
							    ...     ...
							     |	
							     |   +--------------+
							     +-->| History Panel|
								 +--------------+



Legend:  ----->		Event (UI events & custom events)

	 +====+
	 |    |		Event relayer
	 +====+

	 +----+
	 |    |		Event source & destination
	 +----+	

In MVC pattern, the Manager classes in BuddyFix are more acting as the Model, the FormManager is acting as the Controller/bridge, and the different Forms are the Views. This might help you to understand the architecture of BuddyFix. 

APPLICATION DATA
----------------

There are three types of data are saved for the application as the persistent data: 

  - database file (/Home/UserId_buddyfix.dbs)
  - application registry
  - user image files (/Home/UserId.bmp)

Following tables are the sample of different tables in the database file:

buddyTable

 +------------+---------------+----------------+------------+-//
 |   userId   |   buddyName   |    longitude   |  latitude  |  
 +------------+---------------+----------------+------------+-//
 | dz7yp3ifya |   BuddyName   | -1.79675333333 | 51.498485  |  
 +------------+---------------+----------------+------------+-//

//------------+--------------+-----------+------------------------+ 
   timestamp  | isConfirmed  |  groupId  |    remoteIconPath      |
//------------+--------------+-----------+------------------------+
 1291657175303|     true     |      0    | /Home/dzy7yp3ifya.bmp  |
//------------+--------------+-----------+------------------------+

messageTable

 +------------+---------------------+------------------+------------+
 |  senderId  |      receivedAt     |   messageText    |  convId    |
 +------------+---------------------+------------------+------------+
 | b9ayhvtso3 | 11/28/2010 11:57:33 |   Hello world    | -853525128 |    
 +------------+---------------------+------------------+------------+

historyTable

 +------------+-------------+--------------------+-----------------+
 |   userId   |  buddyName  |      dataTime      |   responseType  |
 +------------+-------------+--------------------+-----------------+
 | b9ayhvtso3 |   Tester3   | 11/28/2010 11:57:33|        1        |    
 +------------+-------------+--------------------+-----------------+

convTable
 
 +------------+---------------+----------------------+ 
 |   convId   |     subject   |   participantString  |
 +------------+---------------+----------------------+
 | dz7yp3ifya |   BuddyName   |b7ayhvtso3Tester3     |
 +------------+---------------+----------------------+

groupsTable

 +---------+-----------+------------------+
 | groupId | groupName |  pinIconIndex    |
 +---------+-----------+------------------+
 |    0    |  Friends  |                  |
 +---------+-----------+------------------+

Note: When creating the column of the database table, avoid using the preserved SQL keyword such as "index". It will cause problems when creating the table. 


KNOWN ISSUES
------------

- When the application is trying to receive locations from buddies, it is limited to maximum 20 buddies in the target list.
- Currently is it not possible to run BuddyFix with multiple bada applications due to the platform limitation.
- We are constantly working on this application and future framework based on this application.  

CONTACTS
--------
For any bugs, suggestions or comments, please contact us Cheng Luo: c.luo@samsung.com

ACKNOWLEDGMENT
--------------
This project is done with our spare time in SERI by bunch of guys (Cheng Luo, James Shaw, Sameer Ballewar and Keith Bauwise) who are interested in developing mobile applications. 
We also want to thank Ben Morris for his inital idea of BuddyFix and Samsung bada team in HQ specially: HoKyung Kim, Hyeyoung Jung and Eric Yoon for their supports on BuddyFix. 


Copyright (c) 2011, Samsung Electronics Co., Ltd. All rights reserved.