mainpage.dox

symbian v9.1 下的地址本程序

/*! \mainpage AddressBook Example
 *
 * \ref intro_sec
 * \n\ref Pre_sec
 * \n\ref Design_sec
 * \n\ref Build_sec
 * \n\ref Hierarchy_sec
 *
 * <HR>
 *
 * \section intro_sec 1. About this Example
 *
 *   The purpose of this application is to provide an example, including source code, of the use of the Nokia Web Services Framework so that developers can test and run the application against a live server. The server will be hosted by Forum Nokia and provide the interface specified later in this document.
 *
 *      The sample is a small address book application, which enables the user to find information such as name, address, phone number, job title, and so on about other users. The sample utilizes a Liberty-based address book web service hosted by Forum Nokia, which providers the interface specified in section \ref Sub34.
 *   The service will not be perfect address book service, as that is not needed to show the use of the Web Services framework. Those enhancements would make no difference on the use of the Web Services Framework and so would be just unnecessary work for this example.
 *
 *   The application will be used in S60 3.0 terminals. It is using Symbian native interfaces provided by native Nokia Web Services Framework. The latter framework takes care of tasks such as authentication, service discovery and connection management thus letting the application developer to focus on the application level logic.
 *
 *  \image html AddressBookIntroduction.jpg
 *  <b> <center> figure1: Environment overview </center></b>
 *
 *
 *	 <HR>
 *
 *  \section Pre_sec 2. Prerequisites
 *
 *    This example makes use of the standard Symbian OS application framework, comprising the Application, Document, UI, and View classes. The reader should be aware of this architecture before attempting to understand this example. It is also assumed that the reader is familiar with the concepts related to Web Services. Knowledge of Liberty Alliance specifications (http://www.projectliberty.org/) is an asset.
 *
 *   It's necessary to have LAN Connection support for an emulator and GPRS Connection support for a device.
 *
 *  \subsection Sub21 2.1 Emulator
 *
 *    In emulator configure network settings from tools->Preferences-network.
 *
 *	<HR>
 *
 *  \section Design_sec 3. Design and Implementation
 *
 *    This section starts with explaining the capabilities that the program can use. After that, the support using different screen modes are explained. And then in this section is detailed the design and implementation of each of the following four components required to get information about some employee used mechanism of Web Services:
 *
 *    - Connection
 *    - Searching
 *    - AddToContant
 *    - BrowseCard
 *
 *  \subsection Sub31 3.1 Capabilities
 *
*    The program capabilities are defined in %AddressBook.mmp file: CAPABILITY NetworkServices ReadUserData WriteUserData WriteDeviceData ReadDeviceData.
*
 *  \subsection Sub32 3.2 ScalableUI
 *
 *    The program takes screen parameters in the start of the application and works with all screen modes. The program supports changing the screen layout while the program is running.
 *
 *
*  \subsection Sub33 3.3 Connection
*
*  \image html AddressBookConnection.jpg
 *  <b> <center> figure 2: Connection </center></b>
 *
*    Message Description
*
*    1:     CAddressBookAppUi::HandleCommandL(TInt aCommand) is called on the AppUi object whenever the user selects a menu option. The argument aCommand indicates the command the user selected. In case if the user chose "EaddressBookCmdAppConnect" to connect with a provider than function 	CAknWaitNoteWrapper::ExecuteL(R_CONNECTING_NOTE, *this, ETrue) runs the active scheduler, that calls CAknWaitNoteWrapper::RunL(), it checks:
 *
 *    3:     Is process already done? - function CAddressBookAppUi::IsProcessDone() (it is overridden from interface MAknBackgroundProcess).
 *
 *    4:     If process is not done yet then CAknWaitNoteWrapper::RunL() calls CAddressBookAppUi::StepL() that does one step of processing (it is overridden from interface MAknBackgroundProcess).
*          This step establishes connection.
*
*    5:     CAddressBookEngine::ConnectL() is run from CAddressBookAppUi::StepL(). Makes a connection to an ID-WSF  service.
*          When CAddressBookEngine::ConnectL() is called the first time, authentication and discovery services are connected and the user is therefore authenticated and the service is connected.
 *	 When CAddressBookEngine::ConnectL() is called again and the credentials received from  authentication and discovery services are valid, there are no need to connect to them again. This means that CAddressBookEngine::SetStatus(const TInt aStatus) will be called almost immediately with value CONNECTED, but in device GPRS or data connection is not opened yet (but instead it is opened when search occurs).
*
*    6:     CAddressBookEngine::RegisterIdentityProviderL() is called from CAddressBookEngine::ConnectL(). It registers  services. It creates the CSenServiceManager instance and uses it to  register Identity Provider and Authentication Service (AS) Description.
 *          The AS is also associated with the registered IdentityProvider.
 *
 *    7:     CAddressBookEngine::SetStatus(const TInt aStatus) gets status info about connection (STATUS_NEW, STATUS_READY or STATUS_EXIRED) to be initialized.
 *          It is called by CSenServiceConnectionImpl::RunL() that is called by active scheduler from CAddressBookAppUi::HandleCommandL(TInt aCommand) in case "EAddressBookCmdAppConnect".
 *
 *    8:     CAddressBookAppUi::ConnectionReady() calls when connection is done.
 *
 *    9-11:  Checks Is process already done - function CAddressBookAppUi::IsProcessDone()? If connection is established the active scheduler calls functions CAddressBookAppUi::ProcessFinished() and CAddressBookAppUi::DialogDismissedL(TInt aButtonId) which is overridden from interface MaknBackgroundProcess.
 *
*  \subsection Sub34 3.4 "AddressBookConstants.h" file
 *
 *    This file contains constants that describe Address Book service. This information is localized in the separate file specially that to avoid modifications inside the source code if will be some changes in the Address Book service (for example ProviderContract /EndPoint /testAuthentication ID /testPassword /Provider ID /WS Framework ID).
 *
*    The service is hosted by Forum Nokia and its connection parameters are listed in the table below.
 *
 *  \image html AddressBookServiceParameters.jpg
 *  <b> <center> figure 3: Address Book service connection parameters </center></b>
 *
*  \subsection Sub35 3.5 Searching
*
*  \image html AddressBookSearching.jpg
 *  <b> <center> figure 4: Searching</center></b>
 *
*    Message Description
 *
 *    1:     CAddressBookAppUi::HandleCommandL(TInt aCommand) is called on the AppUi object whenever the user selects a menu option. The argument aCommand indicates the command the user selected. In case if the user chose "EAddressBookCmdAppSearch" to search contact information about an employee than function CAknWaitNoteWrapper::ExecuteL(R_SEARCHING_NOTE, *this) runs the active scheduler, that calls CSenServiceConnectionImpl::RunL() and it calls function CAddressBookEngine::HandleMessageL(const TDesC8& aMessage) (it is overridden from interface MSenServiceConsumer) for receiving messages from the CSenServiceConnection::SendL() function.
 *
 *    2:     CAddressBookView::Draw() draws help information "How need to search".
 *
 *    3:     CAddressBookView::Draw() draws the window for typing query.
 *
 *    4-8:   CAddressBookEngine::SendSearchL(const TDesC& aSearchPattern) sends query entered by user. Create a search pattern from the descriptor and send it to the WSP. The message from server is received through CAddressBookEngine::HandleMessageL(const TDesC8& aMessage) or an error is received through CAddressBookEngine::HandleErrorL(const TInt aErrorCode, const TDesC8& aError).
 *
*    12-38: Receiving and parsing message from server. Xmlparser calls CAddressBookEngine::StartElementL(const TDesC8& aNsUri, const TDesC8& aLocalName, const TDesC8& aQName, const RAttributeArray& aAttrs) every time a new element tag is found and CAddressBookEngine::EndElementL(const TDesC8& aNsUri, const TDesC8& aLocalName, const TDesC8& aQName) every time a closing element tag is found.
*          In our case we are interested in the <Status> and <Card> elements. When Status is found, we compare if attribute 'Code' is OK or not. CSenXmlUtils::LocalName() only extracts out a possible XML prefix (i.e. 'ab:OK').
*          When local name is 'Card', we have encountered a contact-object.  Then we make a new CAddressBookContact and delegate the parsing to it.
 *
 *    39-46: CAddressBookAppUi::SearchFinishedL(RPointerArray<CAddressBookContact>& aContactArray) finishes searching and CAddressBookView::UpdateL(RPointerArray<CAddressBookContact>& aContactArray) parses information and creates received information in convenient for user view.
 *
*    47,48: Checks Is process already done - function CAddressBookAppUi::IsProcessDone()? If connection is established the active scheduler calls functions CAddressBookAppUi::ProcessFinished() and CAddressBookAppUi::DialogDismissedL(TInt aButtonId) which is overridden from interface MaknBackgroundProcess.
*
*    49:    CAddressBookView::Draw() draws the list of contacts matched under user's query.
 *
  *	\subsubsection Subsub351 3.5.1 Structure for address card
 *
 *    Below is the structure for address cards presented in XML style to give an idea what data is supported for cards.
 *
 *  \image html AddressBookCard.jpg
 *  <b> <center> </center></b>
 *
  * 	\subsubsection Subsub352 3.5.2 Message examples
 *
*    This section contains message examples. First there is a basic query to request address cards containing phone number 1234. The only changing parts are the <ResourceID> and <Select> parameters.  The <Select> parameter defines, what is requested. See \ref Sub353, for more details.
*
 *  \image html AddressBookMessageExample1.jpg
 *  <b> <center> </center></b>
 *
 *    The response has two changing parts. Status code depends on the processing results on the service side. The <Data> element contains the returned data. It may include one or more <Card> elements. Each card element has those elements for which content/values are specified.
 *
 *  \image html AddressBookMessageExample2.jpg
 *  <b> <center> </center></b>
 *
 *  \image html AddressBookMessageExample3.jpg
 *  <b> <center> </center></b>
 *
 *  \image html AddressBookMessageExample4.jpg
 *  <b> <center> </center></b>
 *
*	\subsubsection Subsub353 3.5.3 Select
*
 *    The Select parameter is a string containing an XPath expression based on XPath 1.0. Some examples on the expressions that can be used on the client side can be found below:
 *
 *    - Querying based on the phone number: /ab:Card[ab:TEL="1234"]
 *    - Querying based on the family name: /ab:Card[ab:N/ab:FAMILY="Smith"]
 *    - Querying based on the given name: /ab:Card[ab:N/ab:GIVEN="John"]
 *    - Querying based on the family and given name: /ab:Card[ab:N/ab:FAMILY="Smith" and ab:N/ab:GIVEN="John"]
 *
*  \subsection Sub36 3.6 AddToContact
*
*  \image html AddressBookAddToContact.jpg
 *  <b> <center> figure5: Add to Contact</center></b>
*