<?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-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5" xml:lang="en"><title>Using
Message Queue</title><shortdesc>This topic explains the operations that can be performed using
message queue.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<ul>
<li id="GUID-47D01156-47CE-5E19-9B0D-222E05851555"><p><xref href="GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita#GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5/GUID-D08DB507-7AFD-5ADD-B785-03BF01BE758D">Creating &amp; opening a queue</xref> </p> </li>
<li id="GUID-4CFC9AD9-5303-597D-A339-26064DDA459F"><p><xref href="GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita#GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5/GUID-2C05D532-9353-5E83-A8D8-1EACB9D44662">Sending data to the queue</xref> </p> </li>
<li id="GUID-D7A7CB34-16CF-545C-927D-99AF3011C6E7"><p><xref href="GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita#GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5/GUID-683F69D9-CC59-5F8C-A65B-E69D98737A96">Receiving a message from the queue</xref> </p> </li>
<li id="GUID-3A517EE0-2B17-5EEF-BFEE-FF98FD1BE9BF"><p><xref href="GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita#GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5/GUID-1647018E-85C2-58DC-A97A-F90580D9D4E2">Waiting for messages or space</xref> </p> </li>
<li id="GUID-5379B30A-4E56-5C7E-A7E3-44C8E5592946"><p><xref href="GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita#GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5/GUID-A5EABF21-FB2C-5B91-9007-40B4FBE04269">Querying a Queue’s Size</xref> </p> </li>
<li id="GUID-6FD43EA9-4E52-5F60-AD10-314964015F9E"><p><xref href="GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita#GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5/GUID-72033282-9E2F-5E8E-8D78-1B8F6DF42D82">An example of a type specific queue</xref> </p> </li>
</ul>
<section id="GUID-D08DB507-7AFD-5ADD-B785-03BF01BE758D"><title>Creating &amp;
opening a queue</title> <p>A global queue is created by calling <codeph>CreateGlobal()</codeph> on
a handle object, while a local queue is created by calling <codeph>CreateLocal()</codeph>.</p> <p>A
global queue is opened by calling <codeph>OpenGlobal()</codeph> on a handle
object, passing a queue name.</p> <p>All the memory used by the queue is allocated
when the queue is created, so it is possible for the call that creates a queue
to fail with out of memory. The queue is deleted when the last open handle
on it is closed.</p> <p><b> Creating
a global named queue</b> </p> <codeblock id="GUID-C70F3600-6198-5DFE-AFA9-2A9366472ED9" xml:space="preserve">_LIT(KGLobalName, "GlobalMessageQueue");
const TInt KNumberOfSlots = 5;
const TInt KMessageLength = 16;
RMsgQueueBase queue;
TInt ret = queue.CreateGlobal(KGLobalName, KNumberOfSlots, KMessageLength, EOwnerProcess);
        </codeblock> <p>This code fragment creates a global named message
queue called <codeph>GlobalMessageQueue</codeph> with 5 slots, each capable
of holding a message of size 16 bytes. Note that we have explicitly used <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref>. <i>In
practice</i>, you would use the template class <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref>.
For example:</p> <codeblock id="GUID-79040227-DE95-58AB-BC2E-105085AF89F3" xml:space="preserve">class TMyClass
    {
public:
    TInt iA;
    TInt iB;
    TInt iC;
    TInt iD;
    }

_LIT(KGLobalName, "GlobalMessageQueue");
const TInt KNumberOfSlots = 5;
RMsgQueue&lt;TMyClass&gt; queue;
TInt ret = queue.CreateGlobal(KGLobalName, KNumberOfSlots, EOwnerProcess);
        </codeblock> <p>The length of the message is the length of the templated
class, which in this example is also 16.</p> <p><b>Creating a local message queue</b> </p> <codeblock id="GUID-139E6A88-4F52-5036-AF75-2B3CB91802F0" xml:space="preserve">const TInt KNumberOfSlots = 2;
RMsgQueueBase queue;
TInt ret = queue.CreateLocal(KNumberOfSlots, RMsgQueueBase::KMaxLength);
        </codeblock> <p>This creates a local queue with 2 message slots that
have the maximum possible message size. <i>In practice</i>, you would use
the template class <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref> rather than the base class <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref>.</p> <p><b>Opening a named global queue</b> </p> <codeblock id="GUID-9DCB3D58-0690-50BD-A650-DD78FBFA6447" xml:space="preserve">_LIT(KGLobalName, "GlobalMessageQueue");
RMsgQueueBase queue;
TInt messageSize = 0;
TInt ret = queue.OpenGlobal(KGLobalName1);
If (ret == KErrNone)
    {
    messageSize = queue.MessageSize();
    }
        </codeblock> <p>This opens the global named message queue called <codeph>GlobalMessageQueue</codeph>.
The message size used within this queue is queried by calling <codeph>MessageSize()</codeph>.
If the queue does not exist <codeph>OpenGlobal()</codeph> returns <codeph>KErrNotFound</codeph>.</p> <p>Note
that using an illegal message size when writing to, or reading from, a queue
is a programming error. <i>In practice</i>, you would use the templated class <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref> rather
than the base class <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref> to avoid this problem.</p> </section>
<section id="GUID-2C05D532-9353-5E83-A8D8-1EACB9D44662"><title>Sending a message
to the queue</title> <p>A message is sent to a message queue by calling <codeph>Send()</codeph> or <codeph>SendBlocking()</codeph> on
the message queue handle. <codeph>Send()</codeph> returns the error code <xref href="GUID-F9E0EF8B-4EF5-3E35-811A-00B8F9CCF2FA.dita"><apiname>KErrOverflow</apiname></xref> if
the queue is full, <codeph>SendBlocking()</codeph> waits until there is space
in the queue.</p> <p>The following example creates a global named queue, and
sends 2 integer to values to it. The first call to <codeph>Send()</codeph> returns
an error if the queue is full, the call to <codeph>SendBlocking()</codeph> waits
until there is space in the queue. Although the example code uses the base
class <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref>, <i>in practice</i> you would use the
templated class <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref>, to avoid the risk of passing
an invalid length, message size, or an invalid data pointer.</p> <codeblock id="GUID-870BFC97-AB6A-5F44-BE3B-BFE2D979CF15" xml:space="preserve">_LIT(KGLobalName, "GlobalMessageQueue");
RMsgQueueBase mqueue;

TInt ret = mqueue.CreateGlobal(KGLobalName1, 1, sizeof (TInt));
if (ret == KErrNone)
    {
    TInt src = 45;
    ret = mqueue.Send(&amp;src, sizeof (TInt));
    TBool full = (ret == KErrOverflow);

    //blocking send
    src = 32;
    mqueue.SendBlocking(&amp;src, sizeof(TInt));
    mqueue.Close();
    }
        </codeblock> </section>
<section id="GUID-683F69D9-CC59-5F8C-A65B-E69D98737A96"><title>Receiving a
message from the queue</title> <p>A message is received from a message queue
by calling <codeph>Receive()</codeph> or <codeph>ReceiveBlocking()</codeph> on
the message queue handle. <codeph>Receive()</codeph> returns the error code <xref href="GUID-3673F75F-655F-3561-BD56-F7E1C6980810.dita"><apiname>KErrUnderflow</apiname></xref> if
the queue is empty, <codeph>ReceiveBlocking()</codeph> waits until there is
data in the queue.</p> <p>The following example opens a global named queue
and receives 2 integer values from it. The first call to <codeph>Receive()</codeph> returns
an error if the queue is empty, the call to <codeph>ReceiveBlocking()</codeph> waits
until there is data available in the queue. Note also that using the base
class <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref> rather than the templated class <xref href="GUID-5195B8D1-851E-3BEE-A72D-1841C0937300.dita"><apiname>RMsgQueue</apiname></xref> risks
raising panics if the length specified is not the same as the message size
specified when the queue was originally created, or if the pointer to the
receive buffer is not a valid address.</p> <codeblock id="GUID-9EBE78E0-F7A4-5764-A182-DF7C87E18026" xml:space="preserve">_LIT(KGLobalName, "GlobalMessageQueue");
RMsgQueueBase mqueue;

TInt ret = mqueue.OpenGlobal(KGLobalName1);
if (ret == KErrNone)
    {
    TInt data;
    ret = mqueue.Receive(&amp;data, sizeof (TInt));
    TBool empty = (ret == KErrUnderflow);

    //blocking receive
    mqueue.ReceiveBlocking(&amp;data, sizeof(TInt));
    mqueue.Close();
    }
        </codeblock> </section>
<section id="GUID-1647018E-85C2-58DC-A97A-F90580D9D4E2"><title> Waiting for
messages or space</title> <p>It is possible to be notified:</p> <ul>
<li id="GUID-C67C5535-12C4-5AA6-9E84-947CF4FABCA9"><p>when a queue has messages,
by calling <codeph>NotifyDataAvailable()</codeph> on the base class <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref> </p> </li>
<li id="GUID-307D0C2E-CF65-5572-8BE9-9F9A63B331FC"><p>when a queue has space
for more messages, by calling <codeph>NotifySpaceAvailable()</codeph> on the
base class <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita"><apiname>RMsgQueueBase</apiname></xref>.</p> </li>
</ul> <p>Note that the calling <codeph>NotifyDataAvailable()</codeph> when
such a request is still outstanding or calling <codeph>NotifySpaceAvailable()</codeph> when
such a request is already outstanding, results in the calling thread being
panicked</p> <p>Notification requests can be cancelled by calling <codeph>CancelDataAvailable()</codeph> or <codeph>CancelDataAvailable()</codeph> respectively.</p> <codeblock id="GUID-960DCF78-0849-59B7-ADF4-95F24EC5B987" xml:space="preserve">TRequestStatus stat;
mqueue.NotifyDataAvailable(stat);
mqueue.CancelDataAvailable();
User::WaitForRequest(stat);
        </codeblock> </section>
<section id="GUID-A5EABF21-FB2C-5B91-9007-40B4FBE04269"><title>Querying a
Queue’s Size</title> <p>The size of the message slot can be queried by calling <codeph>MessageSize()</codeph> on
the handle. This is useful when a queue is opened, as the calling thread is
panicked if the size is out of range on a <codeph>Send()</codeph> or if the
size is not exact on a <codeph>Receive().</codeph> </p> </section>
<section id="GUID-72033282-9E2F-5E8E-8D78-1B8F6DF42D82"><title>An example
of a type specific queue</title> <p>The size of the message is the size of
the type, and has the same restrictions as the base class, namely it must
be greater than 0, a multiple of 4 bytes and not greater than <xref href="GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2.dita#GUID-2DCEE7F5-9EA3-3546-8779-7299318176E2/GUID-2E514C07-6917-3DDD-A2E6-CD09A9CD2A6D"><apiname>RMsgQueueBase::KMaxLength</apiname></xref>.</p> <codeblock id="GUID-88F3E2B6-F4B7-53B1-A275-C4AB6BA53448" xml:space="preserve">class TTemplateTestData
    {
public:
    TTemplateTestData();
    TTemplateTestData(TInt a, TUint b, TUint8 c, TBool d, TInt e);

public:
    TInt first;
    TUint second;
    TUint8 third;
    TBool fourth;
    TInt fifth;
    };

    {
    ....
    RMsgQueue&lt;TTemplateTestData&gt; templateQueue;

    TTemplateTestData ch(1,2,3,ETrue,4);
    TTemplateTestData ch2;
    TTemplateTestData ch3;

    templateQueue.CreateLocal(12); 
    templateQueue.Send(ch);
    templateQueue.Receive(ch2);
    ....
    templateQueue.Close();
    ...
    }
        </codeblock> <p>Note, the size of the type (i.e. the size of the message)
must be a multiple of 4 bytes.</p> </section>
</conbody></concept>