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

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

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

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

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

    15 receive, parse and process BIO messages </p>

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

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

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

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

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

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

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

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

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

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

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

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

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

    29 access points. </p> </section>

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

    31 <dlentry>

    32 <dt>vCard</dt>

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

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

    35 </dlentry>

    36 <dlentry>

    37 <dt>vCal</dt>

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

    39 </dlentry>

    40 </dl> </section>

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

    42 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

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

    44 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

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

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

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

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

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

    50 <title>              BIO Messaging Framework architecture            </title>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    66 the information required for identifying BIO messages. The information may

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    84 parsing and processing functionality for incoming BIO messages. The parser

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

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

    87 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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   106 settings. </p> </li>

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

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

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

   110 </ul> </section>

   111 <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>

   112 </conbody><related-links>

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

   114 </link>

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

   116 </link>

   117 </related-links></concept>