<?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-2648B61C-6EBD-4668-AACD-EA4B2C435BB2" xml:lang="en"><title>Message
Handling</title><shortdesc>This document describes message queues and message handling.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-AE9A6778-85AE-4D1D-BF61-EE06339549D9"><title>Message queues</title> <p>The
request handling kernel side DFC is managed by a message queue object of the <xref href="GUID-F10B7D2F-D546-3997-A020-37A0D894F1CD.dita"><apiname>TMessageQueue</apiname></xref> type.
The message queue consists of a DFC and a doubly linked list of received messages.
The messages are represented by <xref href="GUID-D43CB8FA-C212-3B56-AD16-9F1D69DA7551.dita"><apiname>TThreadMessage</apiname></xref> objects
and are owned by each user thread. Requests are queued as message objects
on the message queue. </p> <p>The driver framework requires that the driver
sets a DFC queue to use with the message queue. This is done by calling <xref href="GUID-A3CC1D95-4681-3349-A67C-F113A614041D.dita#GUID-A3CC1D95-4681-3349-A67C-F113A614041D/GUID-EB160A2E-39A9-3739-ABDE-C91E2A28D26D"><apiname>DLogicalChannel::SetDfcQ()</apiname></xref>.
The message queue must also be enabled to receive incoming messages by calling <xref href="GUID-382DD935-E9D7-3E00-88B2-B28A89CAD4FB.dita#GUID-382DD935-E9D7-3E00-88B2-B28A89CAD4FB/GUID-EF06556E-9EC6-3D1C-AEE9-0CDDF6B42A24"><apiname>TMessageQue::Receive()</apiname></xref>. </p> <codeblock id="GUID-A995A927-113D-5CB6-B813-DF88DC02D0C1" xml:space="preserve">// Logical Channel Second stage constructor
TInt DExDriverLogicalChannel::DoCreate(TInt /*aUnit*/, const TDesC8*
        /*anInfo*/, const TVersion&amp; aVer)
    {
    ...
    // Set up the DFC queue for this driver. Here, the DFC 
    // queue is created by the PDD dedicated for this driver.
    SetDfcQ(Pdd()-&gt;DfcQ());

    // Start receiving the incoming requests on the message queue
    iMsgQ.Receive();
    ...
    }</codeblock> <p>The Kernel provides a standard DFC queue, which runs
on a dedicated kernel thread called <codeph>DFCThread0</codeph>, for general
use by drivers. However, it is recommended that the driver creates its own
DFC thread to process its requests. The following example shows how a PDD
can implement the <codeph>DfcQ()</codeph> function to return a newly created
DFC thread: </p> <codeblock id="GUID-4753E5B1-8B8F-5589-8547-C94B48B7D66A" xml:space="preserve">// DfcQ - Creates a DFC queue dedicated for the tutorial driver
TDynamicDfcQue* DExUartPhysicalChannelH4::DfcQ()
    {
    // Create a DFC queue dedicated to the driver with a specified 
    // priority
    TInt r = Kern::DynamicDfcQCreate(pDfcQ,KExUartDfcPriority,
    KExUartDfcName);
    if (r!=KErrNone)
        {
        // DfcQ failed, return NULL
        return NULL;
        }
    return iDfcQueue;
    }</codeblock> <p>The DFC thread that is created for the driver must be
destroyed after use. To do this, the driver can create an Exit or Kill DFC
request and queue it to the thread to be destroyed in the logical channel
destructor. This exit DFC function cancels any other requests pending using <xref href="GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB.dita#GUID-A14562A5-3E91-3113-AB3C-71DBEA9D58EB/GUID-9851B90B-8D05-3C86-B083-44C4564AC140"><apiname>TDfc::Cancel()</apiname></xref> and
calls <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-808B3622-BDC4-376D-96E9-16281BA28AF8"><apiname>Kern::Exit()</apiname></xref> to terminate the thread. </p> <p>The <xref href="GUID-D9111A26-FAA3-3D8E-AB41-5B1263FABB6A.dita"><apiname>TDynamicDfcQue</apiname></xref> has
a destroy method that can be run on the channel destructor. The destroy method
destroys the DFC queue, kills the DFC thread and deletes the <xref href="GUID-D9111A26-FAA3-3D8E-AB41-5B1263FABB6A.dita"><apiname>TDynamicDfcQue</apiname></xref> object
itself. This avoids the possibilities of memory leaks in the DFC. </p></section>
<section id="GUID-2463763E-1838-4D7D-80F2-D77420B49D09"><title>Message handling</title> <p>All
synchronous and asynchronous requests are passed to the <xref href="GUID-621F4531-996F-33BB-8081-4B2067CC262A.dita"><apiname>HandleMsg()</apiname></xref> function
by the framework, with the message as an argument. A driver should implement
the function to identify the message type and handle the messages accordingly. </p> <p>The
client thread is blocked until the message is completed, as the request uses
the thread's message object. If the client thread was left free, it would
corrupt the message if another request was issued. </p> <p>When the driver
has completed handling the message, it notifies the framework by calling <xref href="GUID-D43CB8FA-C212-3B56-AD16-9F1D69DA7551.dita#GUID-D43CB8FA-C212-3B56-AD16-9F1D69DA7551/GUID-20CFC972-7C07-36D8-BAC8-BB63AA4612B6"><apiname>TThreadMessage::Complete()</apiname></xref>.
The client thread is then unblocked, and can either block on the thread semaphore
or issue further requests before blocking. </p> <p>For synchronous requests,
the message is not completed until the request itself is complete, and the
driver calls the <codeph>TThreadMessage::Complete()</codeph> function after
the actual completion of the request. However, for asynchronous requests,
the message is completed after the driver has accepted the request, but not
necessarily after the actual completion of the request, which can happen later.
This means that the driver calls <codeph>TThreadMessage::Complete()</codeph> as
soon as it has received the message and initiated the required processing
to complete the request. </p> <codeblock id="GUID-C178DFFA-2321-5396-AED6-5244BBF98388" xml:space="preserve">void DExDriverLogicalChannel::HandleMsg(TMessageBase* aMsg)
    {            
    TThreadMessage&amp; m = *(TThreadMessage*)aMsg;        
    // obtain the function id value to determine the request nature
    TInt id = m.iValue;        
    ...
    if (id&gt;=0)    // Synchronous messages
        {
        // call synchronous message handler function, DoControl()    
        TInt r = DoControl(id,m.Ptr0(),m.Ptr1());
        m.Complete(r,ETrue);
        return;
        }    
    }</codeblock></section>
</conbody></concept>