<?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_d0e291923_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>
</related-links></concept>