LocationApp/main.h

/*
* Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  Main.
*/

/*! \mainpage Location sharing application
 *
 *  \section intro_sec Introduction
 *
 *  The Location App is a sample application that demonstrates how to use the NFC
 *  stack and AIW Framework to pair two NFC enabled devices over Bluetooth and
 *  use the provided Bluetooth information to create a connection channel between
 *  the devices. Location data is then shared via established the Bluetooth connection.
 *
 *  The custom Qt Quick user interface of the application uses Qt C++ classes to query and store
 *  the current location and to share location data with another device. It consists of two
 *  views, Map view and Bookmark view. Both views use Location QML Plugin to handle
 *  locations: Map view to show the selected location on the map and Bookmark view to
 *  access locations stored in the device's landmark database to show them in a simple listview, from
 *  which locations can be shared by tapping a bookmark item.
 *
 *  The C++ class LocationManager is used to query and store the current position. Whenever
 *  the cached location changes, the change is signalled to UI. LocationManager
 *  also constructs/deconstructs the shared location data and handles the storing of the
 *  shared locations upon receiving. LocationManager is used from within the QML code.
 *
 *  The C++ class ConnectionEngine is used to handle connection initiation and
 *  location data transfer. ConnectionEngine consists of a Bluetooth client and server
 *  and AIWEngine. The Bluetooth server listens for client connections. AIWEngine is used
 *  to start "Easy setup", in which the devices are paired using the NFC channel. The
 *  Bluetooth information of successful setup is then used to open a Bluetooth connection
 *  between devices.
 *
 *  \section prerequisites_sec Prerequisites
 *  Qt and Qt Quick basics.
 *
 *  \section capability_sec Required capabilities
 *  The application can be self-signed.
 *
 *  \section knownissues_sec Known issues
 *  Qt Bluetooth is not working correctly. Only one location can be shared between
 *  devices before the connection dies.
 *
 *  Bluetooth must be enabled in both devices to be able to send location data over Bluetooth.
 *
 *  Declarative_location.dll and declarative_feedback.dll libraries are excluded from
 *  the Qt Mobility 1.2 Beta1 for Symbian^3 sis package file. These need to be installed
 *  separately.
 *  
 *  Nokia Ovi Maps works only online (phone network or wlan connection required).  
 *
 *  \section build_install_sec Building and installation
 *
 *  \subsection build_and_installation_preparations_subsec Preparations
 *
 *  Check that you have the latest Qt/Qt SDK installed in the
 *  development environment and on the device. Qt SDK 1.1 or later is required.
 *
 *  Additionally, create a target for Qt 4.7.3 and Qt Mobility 1.2
 *  for Symbian^3 following the instructions from:
 *  https://projects.forum.nokia.com/QtM12bSymb
 *
 *  Make sure you have a C7-00 with Symbian Anna Firmware to test.
 *  The application can be self-signed.
 *
 *  Nokia Ovi Maps installation is required to use application, if not
 *  already included in the device. Nokia Ovi Maps can be installed from:
 *  http://www.nokia.co.uk/apps-maps-and-more. Finalize the Nokia Ovi Maps installation
 *  by opening the Maps application from the Menu application. 
 *
 *  \subsection build_and_installation_qt_sdk_subsec Build & installation
 *  instructions using Qt SDK
 *
 *  <ol>
 *    <li>
 *      Open LocationApp.pro by selecting the File > Open File or Project, browse
 *      to the location where you unpacked the sample application and select LocationApp.pro.
 *    </li>
 *    <li>
 *      Select the "Qt 4.7.3 for Symbian^3 with QtM1.2b" target and press the Finish button.
 *    </li>
 *    <li>
 *      Ensure your NFC enabled Symbian device is connected to the development PC
 *      via USB and that is shows up as connected in Qt Creator (i.e. the build
 *      target selection button in the lower left corner shows a Symbian Device
 *      with a green checkbox).
 *    </li>
 *    <li>
 *      Press the Run button to build the project and create the LocationApp.sis
 *      Symbian install package. The application is installed to the device.
 *    </li>
 *  </ol>
 *
 *  \subsection build_and_installation_command_prompt_subsec Build & installation
 *  instructions using the Command Prompt
 *
 *  <ol>
 *    <li>
 *      Open Qt SDK command prompt from the Start menu by selecting Start > All
 *      Programs > Qt SDK 1.1 > Symbian^3 Qt 4.7.3 >  Qt 4.7.3 for Symbian^3 Command Prompt.
 *    </li>
 *    <li>
 *      In the directory, where LocationApp.pro is located use the following
 *      commands to build and to create installation package:
 *      \code
 *      >qmake
 *      >sbs -c armv5_gcce
 *      >createpackage -g locationapp_template.pkg release-gcce
 *      \endcode
 *    </li>
 *    <li>
 *      Nokia Ovi Suite is required to deploy the created installation package
 *      into the device. Double click the created LocationApp.sis file in
 *      Windows Explorer or use the createpackage command with -i option. Both
 *      start the installation process.
 *    </li>
 *  </ol>
 *
 *  \section usage_sec Usage
 *
 *  \subsection usage_prerequisite_subsec Usage prerequisite
 *
 *  Two NFC enabled devices that both have the LocationApp installed and
 *  running are needed to be able to share locations. Also Bluetooth must be
 *  enabled in both devices before sharing locations.
 *
 *  \subsection usage_map_view_subsec Map view
 *
 *  When the application is launched it queries the current location and shows that
 *  in the center of the map view. Also a dialog is opened to store the current position.
 *  If the current location does not have a name, it is shown as a string representation
 *  of the coordinates in decimal degrees format.
 *
 *  The "My position" button starts a new position update request, that will open
 *  a dialog to store the location. The "Bookmarks" button opens the bookmark view.
 *
 *  \subsection usage_bookmark_view_subsec Bookmark view
 *
 *  Bookmark view shows the locations stored in the device. Tapping a bookmark
 *  updates the map view to show that location.
 *
 *  Tap the "Share" button to start the NFC request to connect with another device using
 *  Bluetooth. Exchange Bluetooth information by touching the phones together. A note
 *  "Device XXXX connected." is shown, if the connection is successfully established.
 *  Location is then shared by tapping a bookmark. The receiving device shows a
 *  "Location XXXX received." note on successful sharing.
 *
 *  \section compatibility_sec Compatibility
 *
 *  This sample application has been tested using the following hardware and
 *  software:
 *
 *  <ul>
 *    <li>Nokia C7-00 with Symbian Anna Firmware</li>
 *    <li>Nokia Qt SDK 1.1</li>
 *    <li>QtMobility 1.2 Beta1</li>
 *  </ul>
 *
 *  \section change_history_sec Change history
 *
 *  1.0 First version
 *
 * \section references_sec References
 *
 *  NFC: http://www.forum.nokia.com/NFC
 *
 *  Qt for Symbian: http://qt.nokia.com/downloads
 */

int main(int argc, char *argv[]);