bcs_ipcqueue.h File Reference

Routines accessing interprocess message queues. More...

Go to the source code of this file.

Defines
#define	BCS_Q_getQueue(q, id, datatype)   _BCS_Q_getQueue(q, id, sizeof(datatype))
	Before any other action concerning a message queue can be taken, call this method to initialize and connect a queue.
Enumerations
enum	BCS_Q_Flag { BCS_Q_NONE, BCS_Q_NOWAIT, BCS_Q_NONE, BCS_Q_NOWAIT }
	Flags for controlling methods behaviour. More...
Functions
BCS_ERROR	BCS_Q_deleteQueue (BCS_Queue *q)
	The queue will be deleted entirely and its contents will be lost.
BCS_ERROR	BCS_Q_forceUnlock (UInt32 id)
	In case your program crashed while using a queue, the queue might be locked.
BCS_ERROR	BCS_Q_getMessage (BCS_Queue *q, void *m, Int32 id, BCS_Q_Flag f)
BCS_ERROR	BCS_Q_postMessage (BCS_Queue *q, void *m, BCS_Q_Flag f)

---

Detailed Description

Date:

04.01.2010

Author:

Marius Zwicker This file provides a convenient interface on all platforms for creating, and accessing interprocess message queues. Although a lot of effort was taken to make all methods as safe as possible, still be sure your given size and actual data size corresponds to each other and you will always take off the same message size as you put on a message queue before. Otherwise undefined and strange things might happen.

Hints for supported data structures:

You can use any kind of struct, but please make sure that the first entry is defined by 'long id'. An example:

struct example_data { long id; char[5] data; };

---

Define Documentation

#define BCS_Q_getQueue	(		q,
			id,
			datatype
	)		_BCS_Q_getQueue(q, id, sizeof(datatype))

Parameters:

q	Pointer to a BCS_Q_Message struct. Attention: If this struct was already used, the connection will be lost!
id	Unique identifier for your queue. Use the same identifier in different processes to connect to the same queue.
datatype	Insert your datatype here. Using our example type, you would write struct BCS_Queue.

Returns:

BCS_ERROR values, see bcs_errorcodes.h

---

Enumeration Type Documentation

enum BCS_Q_Flag

Enumerator:

BCS_Q_NONE	blocking call, method will return only if message could be sent or received
BCS_Q_NOWAIT	non blocking, method will always return and return BCS_ERR_EMPTY or BCS_ERR_NOTSENT if operation failed
BCS_Q_NONE	blocking call, method will return only if message could be sent or received
BCS_Q_NOWAIT	non blocking, method will always return and return BCS_ERR_EMPTY or BCS_ERR_NOTSENT if operation failed

---

Function Documentation

BCS_ERROR BCS_Q_forceUnlock

(

UInt32

id

)

To clean all locks, use this command. Please make sure nobody else is using the queue at that time.

BCS_ERROR BCS_Q_getMessage	(	BCS_Queue *	q,
		void *	m,
		Int32	id,
		BCS_Q_Flag	f
	)

Parameters:

q	Pointer to an initilialized queue.
m	Pointer to an unused message struct. Be aware that all contained data will be overwritten! Again, please make sure to use your defined message structure containing 'long id'.
id	Setting this id has 3 different effects: id=0 Get the next message from the queue, regardless of its id id>0 Get the next message whose id is equal to the given id id<0 Get the next message whose id is less or equal than the absolute value of the given id Please note that using this sorting algorithm might have impact on the performance!
f	Set this flag to control the methods behaviour, see BCS_Q_Flag documentation for details

BCS_ERROR BCS_Q_postMessage	(	BCS_Queue *	q,
		void *	m,
		BCS_Q_Flag	f
	)

Parameters:

q	Pointer to an initilialized queue.
m	Pointer to your message. Make sure it is your message struct and you have 'long id' as first member!
f	Set this flag to control the methods behaviour, see BCS_Q_Flag documentation for details