User Application Interface Library for Network based Message Queue

User Guide

The User Application Interface Library

Applications can access the functionality of the network based message queue via the User Application Interface Library. It offers you functions to exchange data between all users of the message queue. We have tried to keep our interface very similar to the one of the message queue in UNIX. That way it is very easy for applications to enjoy the benefits of the network based message queue without much change in the source code. In the following the routines of the library are each described in detail.

Contents of the User Application Interface Library

Network Based Message Queue

NAME nmsgget - retrieve the ID of the message queue

SYNOPSIS


	int nmsgget(key, msgFlag)



	key_t key;

	int      msgFlag;



	#include "uai.h"

DESCRIPTION

nmsgget() determines the ID of the message queue. So far it is only possible to connect to one specific message queue. Thus the parameters key and msgFlag are ignored. In future versions of the network based message queue it will be possible to connect to message queues of a particular type.

RETURN VALUES

The ID of the message queue to which a connection has been established is returned.

Network Based Message Queue

NAME nmsgsnd - send a message to the message queue

SYNOPSIS


	int nmsgsnd(nmsqid, ptr, length, flag)



	int                     nmsqid;

	struct nmsgbuf *ptr;

	int                     length;

	int                     flag;



	#include "uai.h"

DESCRIPTION

nmsgsnd() sends a message of size length to the message queue that has the ID nmsqid. The data of the message is contained in the nmsgbuf structure referenced by ptr. The nmsgbuf structure is defined as follows:


		struct nmsgbuf

		{

			long mtype;

			char mtext[1024];

		}

The name mtext might be misleading. In fact any kind of data for transmission can be stored in the array. The parameter flag is ignored by the network based message queue.

RETURN VALUES

nmsgsnd() returns the amount of bytes that have been sent to the message queue.

Network Based Message Queue

NAME nmsgrcv - receive a message from the message queue
SYNOPSIS


	int nmsgrcv(nmsqid, ptr, length, nmsgtype)



	int                     nmsqid;

	struct nmsgbuf *ptr;

	int                     length;

	long                  nmsgtype;



	#include "uai.h"

DESCRIPTION

nmsgrcv() receives a message of size length and type nmsgtype from the message queue that has the ID nmsqid. The data of the message is stored in the nmsgbuf structure referenced by ptr. The nmsgbuf structure is defined as follows:


		struct nmsgbuf

		{

			long mtype;

			char mtext[1024];

		}

So mtext will contain the data. The unique ID of the sender is stored in the mtype field.

RETURN VALUES

nmsgrcv() returns the amount of bytes that have been read from the message queue.

Network Based Message Queue

NAME nmsgctl - send a command to the message queue

SYNOPSIS


	int nmsgctl(nmsqid, cmd, buff)



	int                          nmsqid;

	int                          cmd;

	struct nmsqid_ds *buff;



	#include "uai.h"

DESCRIPTION

nmsgctl() sends a command to the message queue that has the ID nmsqid. There are two commands available:
command | description

IPC_RMID | remove a message queue from the system

IPC_STAT | get statistics about the load of the message queue

The statistical data from the message queue is stored in the nmsqid_ds structure referenced by buff. The nmsqid_ds structure is defined as follows:


		struct nmsqid_ds

		{

			int numberMsgsType;

			int numberMsgs;

			int numberBytes;

			int numberPendingProcesses;

			int numberConnections;

		}

The nmsqid_ds structure is not needed for the IPC_RMID command. For this command buff can be set to NULL.

RETURN VALUES

nmsgctl() returns a 1 if the command cmd was successful and 0 otherwise.

Network Based Message Queue

NAME ngetownid - get the unique ID of the calling process

SYNOPSIS


	int ngetownid(void)



	#include "uai.h"

DESCRIPTION

ngetownID() determines the calling process' unique ID. It is unique over the network, because it consists of the process and the host ID.

RETURN VALUES

ngetownid() returns the calling process' unique ID.

Sameer Suresh Shende

Last modified: Mon Oct 14 17:21:34 PDT