Nokia N97 SDK
Example Applications Guide

Message Queue Library Example

1. About this Example
2. Prerequisites
3. Design and Implementation


1. About this Example

The Message Queue Library example demonstrates how to use Open C APIs for developing applications that use Open C standard libraries on top of Symbian/S60. OpenCMessageQueueLibraryEx is an DLL that exports some set of genaralized APIs using which user can create/close message queues and send/receive messages and also get information on created message queues.


1.1 APIs demonstrated


1.2 Building and Using

To build the Message Queue Library example application, go to the OpenCMessageQueueLibraryEx\group directory and build the application.

The Message Queue Library application consists of two modules, which should be built in the following order:

  1. engine - which builds the generic message queue library
  2. exe - which builds an EXE that demonstrates the usage of this library

The definition for the whole application can be found in the bld.inf file in the group subdirectory of the applications main directory.


2. Prerequisites

This example requires a familiarity with the C programming language, and access to the Open C stanadard library documentation. As, this example uses Open C Standard library, the reader is recommended to read the following topics from the Open C SDK documentation before proceeding:


3. Design and Implementation

3.1 Capabilities

The program capabilities are defined in:

MessageQueueLibrary.mmp file (DLL - library): CAPABILITY ALL -TCB MessageQueueClient.mmp file (EXE - application): CAPABILITY NONE.

3.2 Module hierarchy

This application has 2 modules as below:

This example will create a DLL which exports set of generic APIs for the user using which one can do message queue related operations.

To give an rough idea on how to use these apis, an EXE is provided that creates threads and does send/receive on message queues using those exported apis

3.2 Module hierarchy

This DLL (OpenCMessageQueueLibraryEx) will export following APIs:

int MsgQCreate(ULONG qName, ULONG maxMsgs, ULONG qOptions, int* err) Description: Creates a message queue

int MsgQDelete(ULONG qName, int *err) Description: Function for deleting a message queue

int MsgQSend(ULONG qName, char *msg, ULONG nBytes, ULONG priority, int timeout, int *err) Description: Function for sending a message with internal copy

int MsgQReceive(ULONG qName, char *msg, ULONG maxNBytes, int timeout, int *err) Description: Function for receiving a message with internal copy

int MsgQClean(ULONG qName, int *err) Description: Function that empties the specified queue

int MsgQCheck(ULONG qName, int *err) Description: Function for checking how many messages are in a queue

int MsgQMaxCheck(ULONG qName, int *err) Description: This function checks the maximum number of messages in a

All the above APIs will return the library specific error codes to the user through "err".

Each Message Queue created using these apis will have following things maintained:

  1. Queue name
  2. Queue id
  3. Semaphore id (for synchronizing simultaneous access by multiple threads )
  4. Message send state
  5. Number of messages queued
  6. Maximum number of messages queued
  7. Message Queue Info

Internally, these api use ipc related apis of libc like:

Possible error codes are:

  1. KMsgQLibNoMemoryErr 0x101 - out of memory
  2. KMsgQLibQIdErr 0x102 - queue already in use or invalid
  3. KMsgQLibParamErr 0x103 - illegal parm(s)/val(s)
  4. KMsgQLibQFlushErr 0x104 - queue being flushed
  5. KMsgQLibQShortErr 0x105 - internal error: inconsistency between # of msgs

3.2 Module hierarchy

OpenCMessageQueueClientEx is C Application that uses Message Queue library. This application uses main() as an entry point for the application. The application is simple console based application. This has use cases for using Message Queue library (OpenCMessageQueueLibrary.dll) APIs.

Main thread of Application will create two message queues. It will create two threads, passing them Message Queue name.

Thread one will send message to message queue 1 and waits for messages from message queue 2. Thread one will send message to message queue 2 and waits for messages from message queue 1.

Using OpenCMessageQueueLibrary.dll, if user tries to create a message queue with already existing name, it will just return the existing message queue id.

It has its own icon and can be launched from the UI both in the emulator and in the device.


© Nokia 2009

Back to top