<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B" xml:lang="en"><title>BIO

Messaging Framework Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The BIO Messaging Framework provides a framework supports plug-ins which

receive, parse and process BIO messages </p>

<p>Bearer Independent Objects (BIO) messages contain data that can be received

and interpreted by the device. Unlike conventional messages—such as, SMS and

email, BIO messages does not depend on the type of transport over which it

is received. not intended to be read by the user in their raw form. BIO messages

can be received over a number of bearers: IR, Bluetooth, SMS and WAP Push. </p>

<section><title>Purpose</title> <p>Plug-ins supported by the framework handle

incoming BIO messages received by a phone. BIO messages are sent to the system

to update attributes on the system. </p> <p>Examples of BIO messages are vCards

vCals, device settings, ringtones, graphical logos and icons, Internet access

point setup messages and Over the Air (OTA) configuration messages. vCards

are parsed and then displayed to the user, and when accepted they modify the

user’s contact database. OTA configuration messages are parsed before they

are displayed to the user, and if accepted they create email accounts or internet

access points. </p> </section>

<section id="GUID-6E7D52CF-F18C-5C92-9DB2-611EDD018048"><title>Key terms</title> <dl>

<dlentry>

<dt>vCard</dt>

<dd><p>An electronic business card, which is a collection of properties. Properties

can be a property name, one or more property parameters. and a property value. </p> </dd>

</dlentry>

<dlentry>

<dt>vCal</dt>

<dd><p>An electronic calendar entry, which consists of a collection of properties. </p> </dd>

</dlentry>

</dl> </section>

<section><title>Architecture</title> <p>BIO Messaging Framework comprises

of three main components—<xref href="GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B.dita#GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B/GUID-BA671884-B143-52B0-9F48-1801F465F6D6">BIO

MTM</xref>, <xref href="GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B.dita#GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B/GUID-38031091-ED66-51CF-A025-85C7CEEC3D7D">BIO

database</xref> and <xref href="GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B.dita#GUID-17DE7D55-00C9-5D40-8AE4-39BDB20FCC5B/GUID-9C9FDAE8-B89A-57EF-8F56-E0C84D9E5837">BIO

parser</xref>. </p> <p>BIO messages are not received by the BIO Message Framework

directly. They come over other subsystems to the BIO database. For example,

the SMS watchers receive BIO messages from the SMS stack and use BIO Messaging

Framework to tag the messages with the correct BIO ID. </p> <p>The following

figure illustrates the BIO Messaging Framework architecture: </p> <fig id="GUID-2CEE40B9-2559-5CF3-B98F-2472F6B4D35D">

<title>              BIO Messaging Framework architecture            </title>

<image href="GUID-42609A21-CEDC-58E8-864C-0CF8458F6798_d0e498755_href.png" placement="inline"/>

</fig> <p id="GUID-38031091-ED66-51CF-A025-85C7CEEC3D7D"><b>BIO database</b> </p> <p>The

BIO database is used to identify the type of BIO messages. It maps message

attributes, such as port number, MIME type, or leading string to a BIO type.

These attributes are then used by clients of the BIO Message Framework to

determine what ports to listen for messages. For example, SMS messages which

start with that string and, when storing these messages in the inbox, tag

them with the BIO ID associated with that leading string. </p> <p><b>BIO watcher</b> </p> <p>BIO

watcher is part of the <xref href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita">Watcher

Framework</xref>, which handles BIO messages that come from the SMS and WAP

stack. It firsts identifies the type of BIO message using the BIO database,

and then creates a BIO message in a Message Store using the messaging APIs. </p> <p><b>BIF

files and utilities</b> </p> <p>BIO Information Files (BIF) are resource files

that are read by the BIO database to provide registration information of BIO

message types. There is one BIF file for every BIO message type. They encapsulate

the information required for identifying BIO messages. The information may

include the expected port number, MIME type or leading string. Different BIO

watchers use different information. </p> <p>BIF files can be one of two formats.

The first format is a resource file and the second format is a custom binary

format for representing the data fields in the BIF file. The BIF utilities

(<filepath>bifu.dll</filepath>) provide the functionality to read information

in BIF files of both formats. </p> <p id="GUID-BA671884-B143-52B0-9F48-1801F465F6D6"><b>BIO

MTM</b> </p> <p>The BIO Client MTM is responsible for loading the BIO database

and BIO utilities to handle parse or process requests from messaging clients.

It is called by a messaging client to parse or process a BIO message that

is saved in a Message Store. If the client is trusted with the correct capabilities,

the BIO parser DLLs are loaded successfully. Without the right capabilities,

the DLLs will not run. A BIO watcher saves the BIO message with the BIO flag

and the appropriate BIO type set. </p> <p>The BIO MTM does not support sending

messages and therefore does not support reply or forward of BIO messages.

Forwarding and replying to BIO messages is supported by the MTM that the message

is sent over, for example SMS. </p> <p id="GUID-9C9FDAE8-B89A-57EF-8F56-E0C84D9E5837"><b>BIO

parser and utilities</b> </p> <p>BIO parsers are plug-ins (DLLs) that provide

parsing and processing functionality for incoming BIO messages. The parser

uses BIO utilities to provide base functionality. BIO utilities that load

the BIO parser use the DLL filename and load the DLLs from the <filepath>\sys\bin</filepath> location. </p> <p>Each

BIO parser implements the <xref href="GUID-2DBFC4F4-3675-32DD-ACF7-B075827C4181.dita"><apiname>ParseL</apiname></xref> and <xref href="GUID-1451C2B5-426E-30F3-AD30-C05ECA1BF4EF.dita"><apiname>ProcessL</apiname></xref> functions.

The level of functionality varies between parsers. Some parsers update the

final repository with the received data. For example, the WAP parser updates

the <codeph>CommDb</codeph> with the received settings. Some parsers save

data in an unparsed state for processing by another component. This secondary

parsing is not part of BIO Messaging Framework and must be initiated by a

messaging client. For example, when generic file parser (GFP) saves a vCard

data as a file to update the contact database, the UI must then invoke the

Versit parser to parse the vCard and commit it to the contact database. </p> <p>It

is possible to add new BIO parsers to provide support for different types

of BIO message. The following are the types of parsers provided by Symbian: </p> <ul>

<li id="GUID-884D2387-313D-5408-A72B-607036AAA67A"><p> <b>Generic file parser

(GFP):</b> The generic file parser can be used to identify and save a variety

of BIO data types, for example, vCards and vCals. The generic file parser

does not process the data, it saves it in the message store for processing

by another component. The file is saved as an attachment of the message entry

that is parsed. </p> </li>

<li id="GUID-732BB8B0-DD6D-5808-A260-598343727228"><p> <b>OTA parser (WAPP):</b> The

WAPP parser decodes Nokia OTA messages and updates CommDb to reflect the received

settings. </p> </li>

<li id="GUID-5A42A060-4B0C-5581-A584-A34914F6B972"><p> <b>Internet Access

Parser (IACP):</b> The IACP parser decodes Nokia smart messages and updates

the CommDb and messaging settings where appropriate. </p> </li>

</ul> </section>

<section><title>API summary</title> <p> <xref href="GUID-B752DB50-DF39-3FE2-975C-D49318426F93.dita"><apiname>CBIOClientMtm</apiname></xref>, <xref href="GUID-115327CD-43D1-324B-84D7-8DFB6226C42A.dita"><apiname>CBIODatabase</apiname></xref> and <xref href="GUID-7A187B0D-79D6-3EAD-8181-FE2EBB9043DC.dita"><apiname>CBaseScriptParser2</apiname></xref> are the main APIs of BIO Message Framework. </p> </section>

</conbody><related-links>

<link href="GUID-4603D4ED-966F-5F70-B991-D10495BC2D7E.dita"><linktext>Watcher Framework</linktext>

</link>

<link href="GUID-0CBD2728-DB7E-55FF-929A-E5BF279A1B66.dita"><linktext>Example code</linktext>

</link>