Nokia N97 SDK
Example Applications Guide

msgqlib.h File Reference


Detailed Description

Description: Header file for MsgQLib Copyright (c) 2007 Nokia Corporation. This material, including documentation and any related computer programs, is protected by copyright controlled by Nokia Corporation.

Definition in file msgqlib.h.

#include <_ansi.h>

Go to the source code of this file.


Defines

#define  MAX_MSG_LEN   2048
#define  MSGQ_TBL_SZ   101
#define  MSG_Q_READY   0
#define  MSG_Q_CLEANING   1
#define  NO_WAIT   0
#define  WAIT_FOREVER   0xFFFF
#define  NULL   0
#define  KMsgQLibErr   0x100
#define  KMsgQLibNoMemoryErr   (KMsgQLibErr | 1)
#define  KMsgQLibQIdErr   (KMsgQLibErr | 2)
#define  KMsgQLibParamErr   (KMsgQLibErr | 3)
#define  KMsgQLibQFlushErr   (KMsgQLibErr | 4)
#define  KMsgQLibQShortErr   (KMsgQLibErr | 5)
#define  MSG_Q_FIFO   1
#define  MSG_Q_PRIORITY   2
#define  MSG_PRI_NORMAL   3
#define  MSG_PRI_URGENT   4
#define  SEM_Q_FIFO   5
#define  SEM_Q_PRIORITY   6
#define  OK   0
#define  ERROR   -1

Typedefs

typedef unsigned long  ULONG
typedef unsigned short  ushort_t

Functions

IMPORT_C int  MsgQCreate (ULONG qName, ULONG maxMsgs, ULONG qOptions, int *err)
IMPORT_C int  MsgQDelete (ULONG qName, int *err)
IMPORT_C int  MsgQSend (ULONG qName, char *msg, ULONG nBytes, ULONG priority, int timeout, int *err)
IMPORT_C int  MsgQReceive (ULONG qName, char *msg, ULONG maxNBytes, int timeout, int *err)
IMPORT_C int  MsgQCheck (ULONG qName, int *err)
IMPORT_C int  MsgQMaxCheck (ULONG qName, int *err)
IMPORT_C int  MsgQClean (ULONG qName, int *err)


Function Documentation

IMPORT_C int MsgQCreate (  ULONG  qName,
ULONG  maxMsgs,
ULONG  qOptions,
int *  err
) 
 

Creates a message queue with the argument passed

Parameters:
qName  - queue name
maxMsgs  - max messages in the queue
qOptions  - message queue options MSG_Q_FIFO MSG_Q_PRIORITY
err  - error code to be returned
Returns:
Returns status and error code

Definition at line 23 of file msgqcreate.c.

References AddToMsgQTable(), ERROR, InstallMsqQTable(), KMsgQLibParamErr, MAX_MSG_LEN, MSG_Q_FIFO, MSG_Q_PRIORITY, MsgQCreate(), MsgQTableLookup(), NULL, and OK.

Referenced by main(), MsgQCreate(), and ThreadFunction().

00023                                                                               {
00024         int         qId;
00025         int         semId;
00026         int         semName ;
00027         struct msqid_ds  qStatus ;
00028         struct semid_ds  sStatus ;
00029         
00030         union semun {
00031                 int              val;
00032                 struct semid_ds* buf;
00033                 ushort_t*                array;
00034         } arg ;
00035 
00036 
00037         int          hashInstErr;
00038 
00039         if (MsgQTableLookup(qName) != NULL) {
00040                 *err = OK;
00041                 return (OK);
00042         }
00043         else {
00044                 if((qOptions == MSG_Q_FIFO) || (qOptions == MSG_Q_PRIORITY)) {
00045                         // Set msg queue options to  FIFO and create the message queue
00046                         qOptions= MSG_Q_FIFO ;
00047                         if((qId = msgget((key_t) qName ,IPC_CREAT | 0666 | IPC_EXCL )) >=0 ) {
00048                                 //  set msg queue parameter max # bytes in queue
00049                                 if(  msgctl(qId,IPC_STAT,&qStatus) == 0  )          
00050                                 if( qStatus.msg_qbytes > (maxMsgs * MAX_MSG_LEN) ) {
00051                                         qStatus.msg_qbytes = maxMsgs * MAX_MSG_LEN ;              
00052                                         if( msgctl(qId,IPC_SET,&qStatus) < 0) {
00053                                                 // delete message queue on error 
00054                                                 msgctl(qId,IPC_RMID,0);
00055                                                 *err = errno;
00056                                                 return(ERROR);
00057                                         }
00058                                 }
00059                                 // create semaphore
00060                                 semName= (key_t) qName;
00061                                 if((semId = semget(semName, 1, IPC_CREAT | 0666 |IPC_EXCL )) >= 0 ) {
00062                                         // set the semaphore value
00063                                         arg.buf = &sStatus;              
00064                                         arg.val = 1;
00065                                         semctl(semId , 0, SETVAL, arg) ;
00066                                         
00067                                         //install queue data in hash table
00068                                         if(InstallMsqQTable(qName, qId, semId, &hashInstErr) == OK) {
00069                                                 AddToMsgQTable(qName);
00070                                                 *err = OK;                
00071                                                 return (OK);
00072                                         }
00073                                         else {
00074                                                 //delete semaphore on error
00075                                                 semctl(semId,0,IPC_RMID,0) ;
00076                                                 *err = hashInstErr;
00077                                         }
00078                                 }
00079                                 else {
00080                                         // delete message queue on error
00081                                         msgctl(qId,IPC_RMID,0);
00082                                         *err = errno;
00083                                 }
00084                         }
00085                         else {
00086                                 *err = errno;
00087                         }       
00088                 }
00089                 else
00090                         *err = KMsgQLibParamErr;
00091 
00092                 return(ERROR);
00093         }
00094 }

IMPORT_C int MsgQDelete (  ULONG  qName,
int *  err
) 
 

This function deletes a message queue

Parameters:
qName  - queue name
err  - error code to be returned
Returns:
Returns status and error code

Definition at line 21 of file msgqdelete.c.

References DeleteFromMsgQTable(), ERROR, KMsgQLibQIdErr, MsgQDelete(), MsgQTableLookup(), NULL, OK, MsgQInfo::qId, MsgQInfo::qName, RemoveFromMsqQTable(), and MsgQInfo::semId.

Referenced by MsgQDelete().

00022 {
00023         MSGQ_INFO*               pMsgQInfo;
00024         int              hashRmErr;
00025 
00026         if ((pMsgQInfo = MsgQTableLookup(qName)) != NULL) {
00027                 if (semctl(pMsgQInfo->semId,0,IPC_RMID,0) == 0) {
00028                         if (msgctl(pMsgQInfo->qId,IPC_RMID,0) == 0) {
00029                                 if (RemoveFromMsqQTable(pMsgQInfo->qName, &hashRmErr) == OK) {
00030                                         DeleteFromMsgQTable(qName);
00031                                         *err = OK;
00032                                         return (OK);
00033                                 }
00034                                 else
00035                                         *err = hashRmErr;
00036                         }
00037                         else 
00038                                 *err = errno;
00039                 }
00040                 else
00041                         *err = errno;
00042         }
00043         else
00044                 *err = KMsgQLibQIdErr;
00045 
00046         return(ERROR);
00047 }

IMPORT_C int MsgQSend (  ULONG  qName,
char *  msg,
ULONG  nBytes,
ULONG  priority,
int  timeout,
int *  err
) 
 

This function sends a message with internal copy

Parameters:
qName  - queue name
msg  - message to send
nBytes  - length of message
priority  - message priority
timeout  - milliseconds to wait
err  - error code to be returned
Returns:
Returns status and error code

Definition at line 22 of file msgqsend.c.

References KMsgQLibQFlushErr, KMsgQLibQIdErr, MAX_MSG_LEN, MsgQInfo::maxNumMsgs, MSG_PRI_NORMAL, MSG_PRI_URGENT, MSG_Q_READY, MsgQSend(), MsgQTableLookup(), NULL, MsgQInfo::numMsgs, OK, MsgQInfo::qId, MsgQInfo::semId, and MsgQInfo::sendState.

Referenced by MsgQSend(), and ThreadFunction().

00023 {
00024         MSGQ_INFO* pMsgQInfo = NULL;
00025 
00026         struct {
00027                 long mtype;
00028                 char mtext[MAX_MSG_LEN];
00029         } message;
00030 
00031         /* structure used for semaphore post operation */
00032         struct sembuf op;
00033         
00034         /* init the  semop () structure which is used for wait and signal operations */
00035         op.sem_num = 0;
00036         op.sem_op = -1;
00037         op.sem_flg = SEM_UNDO;
00038 
00039         /* check parameters */
00040         if ((priority == MSG_PRI_NORMAL) || (priority == MSG_PRI_URGENT)) {
00041                 if((pMsgQInfo = MsgQTableLookup(qName)) != NULL) {
00042                         if (pMsgQInfo->sendState == MSG_Q_READY) {
00043                                 op.sem_flg = op.sem_flg | timeout;
00044                                 if((semop(pMsgQInfo->semId, &op, 1)) == OK) {
00045                                         pMsgQInfo->numMsgs++;
00046                                         if(pMsgQInfo->maxNumMsgs < pMsgQInfo->numMsgs)          
00047                                         pMsgQInfo->maxNumMsgs = pMsgQInfo->numMsgs;
00048 
00049                                         message.mtype = 1;
00050                                         bcopy(msg, message.mtext, nBytes);
00051                                         message.mtext[nBytes] = '\0';
00052 
00053                                         if(msgsnd (pMsgQInfo->qId, &message, (size_t)nBytes+4, timeout) == OK) {
00054                                                 *err = OK;
00055                                                 /* After successfull send, unlock the message queue by using post operation on semaphore.*/
00056                                                 op.sem_op = 1;
00057                                                 semop(pMsgQInfo->semId, &op, 1);
00058                                                 return (OK);
00059                                         }
00060                                         else {
00061                                                 *err = errno;
00062                                                 pMsgQInfo->numMsgs--;
00063                                                 op.sem_op = 1;
00064                                                 semop(pMsgQInfo->semId, &op, 1);
00065                                         }
00066                                 }
00067                                 else
00068                                         *err = errno;
00069                         }
00070                         else
00071                                 *err = KMsgQLibQFlushErr;
00072                 }
00073                 else
00074                         *err = KMsgQLibQIdErr;
00075         }
00076         else
00077                 *err = KMsgQLibParamErr;
00078 
00079         return(ERROR);
00080 }

IMPORT_C int MsgQReceive (  ULONG  qName,
char *  msg,
ULONG  maxNBytes,
int  timeout,
int *  err
) 
 

This function receives a message with internal copy

Parameters:
qName  - queue name
msg  - buffer for received message
maxNBytes  - length of buffer
timeout  - milliseconds to wait
err  - error code to be returned
Returns:
Returns status and error code

Definition at line 24 of file msgqrecv.c.

References ERROR, KMsgQLibQIdErr, MAX_MSG_LEN, MsgQReceive(), MsgQTableLookup(), NO_WAIT, NULL, MsgQInfo::numMsgs, OK, MsgQInfo::qId, and WAIT_FOREVER.

Referenced by MsgQClean(), MsgQReceive(), and ThreadFunction().

00024                                                                                          {
00025         MSGQ_INFO* pMsgQInfo = NULL;
00026         ssize_t rxBytes;
00027         int toTicks;
00028 
00029         struct {
00030                 long  mtype;
00031                 char mtext[MAX_MSG_LEN];
00032         } message;
00033 
00034         /* check parameters */
00035         if ((pMsgQInfo = MsgQTableLookup(qName)) != NULL) {
00036                 if(timeout != NO_WAIT && timeout != WAIT_FOREVER)
00037                         toTicks = timeout < 10 ? 1: (ULONG)((timeout * sysconf(_SC_CLK_TCK)) / 1000);
00038                 else
00039                         toTicks = timeout;      
00040 
00041                 message.mtype = 1;
00042                 /* receive message */
00043                 if((rxBytes = msgrcv(pMsgQInfo->qId, &message, (size_t)maxNBytes, 1, toTicks)) != -1) {
00044                         message.mtext[rxBytes-4] = '\0';
00045                         bcopy(message.mtext, msg, rxBytes);
00046                         pMsgQInfo->numMsgs--;
00047                         *err = OK;
00048                         return ((ULONG)rxBytes);
00049                 }
00050                 else
00051                         *err = errno;
00052         }
00053         else
00054                 *err = KMsgQLibQIdErr;
00055 
00056         return(ERROR);
00057 }

IMPORT_C int MsgQCheck (  ULONG  qName,
int *  err
) 
 

This function checks how many messages are in a queue

Parameters:
qName  - queue name
err  - error code to be returned
Returns:
Returns status and error code

Definition at line 21 of file msgqcheck.c.

References ERROR, KMsgQLibQIdErr, KMsgQLibQShortErr, MsgQCheck(), MsgQTableLookup(), NULL, MsgQInfo::numMsgs, OK, and MsgQInfo::qId.

Referenced by MsgQCheck().

00021                                               {
00022         MSGQ_INFO* pMsgQInfo = NULL;
00023         int nMsgs;
00024         struct  msqid_ds  qStatus ;
00025 
00026         if ((pMsgQInfo = MsgQTableLookup(qName)) != NULL) {
00027                 //   get total count of msgs from the msg queue 
00028                 if ((msgctl(pMsgQInfo->qId,IPC_STAT ,&qStatus)) >= 0 ) {
00029                         nMsgs=qStatus.msg_qnum ;
00030                         if (nMsgs == pMsgQInfo->numMsgs) {
00031                                 *err = OK;
00032                                 return(nMsgs);
00033                         }
00034                         else {
00035                                 *err = KMsgQLibQShortErr;
00036                                 return(pMsgQInfo->numMsgs);
00037                         }
00038                 }
00039                 else
00040                         *err=errno;
00041         }
00042         else
00043                 *err = KMsgQLibQIdErr;
00044         return(ERROR);
00045 }

IMPORT_C int MsgQMaxCheck (  ULONG  qName,
int *  err
) 
 

This function checks the maximum number of messages in a queue

Parameters:
qName  - queue name
err  - error code to be returned
Returns:
Returns status and error code

Definition at line 19 of file msgqmaxcheck.c.

References ERROR, KMsgQLibQIdErr, MsgQInfo::maxNumMsgs, MsgQMaxCheck(), MsgQTableLookup(), NULL, and OK.

Referenced by MsgQMaxCheck().

00019                                                  {
00020         MSGQ_INFO* pMsgQInfo = NULL;
00021 
00022         if ((pMsgQInfo = MsgQTableLookup(qName)) != NULL) {
00023                 *err = OK;
00024                 return (pMsgQInfo->maxNumMsgs);
00025         }
00026         else
00027                 *err = KMsgQLibQIdErr;
00028 
00029         return(ERROR);
00030 }

IMPORT_C int MsgQClean (  ULONG  qName,
int *  err
) 
 

This function empties the specified queue

Parameters:
qName  - queue name
err  - error code to be returned
Returns:
Returns status and error code

Definition at line 20 of file msgqclean.c.

References ERROR, KMsgQLibQIdErr, MAX_MSG_LEN, MSG_Q_CLEANING, MSG_Q_READY, MsgQClean(), MsgQReceive(), MsgQTableLookup(), NULL, OK, and MsgQInfo::sendState.

Referenced by MsgQClean().

00020                                               {
00021         MSGQ_INFO* pMsgQInfo = NULL;
00022         char msg[MAX_MSG_LEN];
00023         int rcv_err;
00024 
00025         if ((pMsgQInfo = MsgQTableLookup(qName)) != NULL) {
00026                 // sending a message is not allowed
00027                 pMsgQInfo->sendState = MSG_Q_CLEANING;
00028                 // empty out the queue 
00029                 while(MsgQReceive(qName, msg, MAX_MSG_LEN, IPC_NOWAIT, &rcv_err) != ERROR) {};
00030                 if (rcv_err == ENOMSG) {
00031                         *err = OK;
00032                         return (OK);
00033                 }
00034                 else
00035                         *err = rcv_err;
00036                 // sending a message is allowed
00037                 pMsgQInfo->sendState = MSG_Q_READY;
00038         }
00039         else
00040                 *err = KMsgQLibQIdErr;
00041 
00042         return(ERROR);
00043 }


© Nokia 2009

Back to top