--- a/Symbian3/PDK/Source/GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita Tue Mar 30 11:42:04 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-2F4B2A69-9B92-52BE-9A1A-FDA501579CE5.dita Tue Mar 30 11:56:28 2010 +0100
@@ -1,180 +1,180 @@
-<?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 & 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 &
-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<TMyClass> 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(&src, sizeof (TInt));
- TBool full = (ret == KErrOverflow);
-
- //blocking send
- src = 32;
- mqueue.SendBlocking(&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(&data, sizeof (TInt));
- TBool empty = (ret == KErrUnderflow);
-
- //blocking receive
- mqueue.ReceiveBlocking(&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<TTemplateTestData> 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>
+<?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 & 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 &
+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<TMyClass> 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(&src, sizeof (TInt));
+ TBool full = (ret == KErrOverflow);
+
+ //blocking send
+ src = 32;
+ mqueue.SendBlocking(&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(&data, sizeof (TInt));
+ TBool empty = (ret == KErrUnderflow);
+
+ //blocking receive
+ mqueue.ReceiveBlocking(&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<TTemplateTestData> 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>
\ No newline at end of file