|
S60 3rd Edition SDK for Symbian OS Example Applications Guide |
1. About this Example
2. Prerequisites
3. Design and Implementation
4. Building and Running
4. Class Hierarchy
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 3.4 "AddressBookConstants.h" file. 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.
It's necessary to have LAN Connection support for an emulator and GPRS Connection support for a device.
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.
The service is hosted by Forum Nokia and its connection parameters are listed in the table below.
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.
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.
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 "EAddressBookCmdAppAdd" to add contact in phone book.
2,3: CAddressBookEngine::GetContact(TInt aPosition, CAddressBookContact*& aContact) and CAddressBookView::CurrentContact() get information from current contact.
4: CPbkContactEngine::CreateEmptyContactL() creates an empty item for contact information.
5-10: CAddressBookContact::PhoneL(), CAddressBookContact::MobilePhoneL(), CAddressBookContact::SelectedPhoneL(const TDesC8& aType), CAddressBookAppUi::UpdateFieldL(CPbkContactItem* modifiableItem, TPbkFieldId fieldId, const TDesC8& newValue) add in this item information about the mobile and general phones.
11-13: CAddressBookContact::FirstName(), CAddressBookContact::ChildValue(const TDesC8& aFirstElement, const TDesC8& aSecondElement), CAddressBookAppUi::UpdateFieldL(CPbkContactItem* modifiableItem, TPbkFieldId fieldId, const TDesC8& newValue) also add information about the first name. The same steps follow for adding information about last name/fax/email/organization/title and street.
14: CPbkContactEngine::AddNewContactL() adds new item about contact information in phonebook's database.
Message Description
1: CAddressBookView::HandleListBoxEventL(CEikListBox*, TListBoxEvent aEventType) is called whenever the user presses "enter" button (EeventEnterKeyPressed) to browse full information about the employee.
2,3: CAddressBookView::OpenItemL() and CAddressBookEngine::GetContact(TInt aPosition, CAddressBookContact*& aContact) get information about current contact.
4-6: CAddressBookView::AppendRowL(TPtrC8 aValue, const TDesC8& aFieldName, CDesCArray& aArray), CAddressBookContact::LastName(), CAddressBookContact::SelectedPhoneL(const TDesC8& aType) convert information about last name that to draw it as the separate row.
7-9: CAddressBookView::AppendRowL(TPtrC8 aValue, const TDesC8& aFieldName, CDesCArray& aArray), CAddressBookContact::PhoneL(), CAddressBookContact::ChildValue(const TDesC8& aFirstElement, const TDesC8& aSecondElement) convert information about phone that to draw it as the separate row. The same steps follow for first name/middle name/extra address/street/locality/region/post code/country/mobile phone/fax/email/title/organization/unit.
10: CAddressBookView::ChangeCbaL(TInt aResourceId, TDrawNow aDrawNow) sets aResourceId = R_AVKON_SOFTKEYS_OPTIONS_BACK and state = EdrawNow.
11: CAddressBookView::Draw() draws full information about employee who was found as rows.
Selecting the Options soft key displays the following 3 choices:
A user can make queries by providing some values. The address cards matching those values are returned. E.g. a family name can be given and all address cards containing exactly that family name will be returned, unless there are e.g. more than ten cards matching that value in which case a status code indicating too many matches will be returned and the end user should give more parameters, e.g. give also the given name.
2. At this point application asks for available address book services (the company address book service based on the ProviderID). This note appears only once during first time of connection with service.
3. So WebServices connects to the authentication service, gets a resource offering for the discovery service and gets available address book services, unless the information is already cached.
4. Appears a list of access points from which is needed to choose right. (For emulator it is "Ethernet with Daemon", for hardware it corresponds with SIM card.)
5. Appears the new options menu, where Search need to find an information about somebody.
6. When user chooses this point of menu appears the next note:
7. A screen for entering query parameters is displayed. Note: although the different address book services contain a bit different data, both have same available query parameters.
8. User types the query parameters, e.g. first name of a colleague to get the rest of the information or the phone number of a missed call to check, who called.
9. As a response one of the following alternatives is received:
User can browse all the returned address cards.
10. If one or more than one address card matching the query there is opportunity to add them to contacts.
|
© Nokia 2006 |
|
