/***************************************************************************
KR_Messages.h  -
-------------------
begin                : Tue Apr 29 2004
copyright            : (C) 2004 by DigitalAirways
email                : info@digitalairways.com
***************************************************************************/

/*
* Copyright (c) 2004 DigitalAirways, sarl. All Rights Reserved.
*
* This software is the confidential and proprietary information of
* DigitalAirways, sarl. ("Confidential Information").  You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with DigitalAirways.
* A copy of this license is included in the licence.txt file included
* in this software package.
*/

/*
**************************************************************
* RELEASE NOTES
**************************************************************
- The times used here are related to the system time.
- The queues are never supposed to contain holes.

**************************************************************
* HISTORY
**************************************************************
-

**************************************************************
* TODO
**************************************************************
-


*/

#ifndef __KR_MESSAGES__
#define __KR_MESSAGES__

#include "EB_Utils.h"

// MESSAGES TYPES:
//  Implementation notes:
//   - when an arg is a pointer whose ownership is supposed to be transferred
//     to the consumer, the flag MFG_DYNARG MUST be used. This allows the
//     system to avoid memory leaks, even for messages whose semantics is not
//     known by any component.

// Internal test message
//  sub: none
//  arg: none
#define MSG_TEST0	0x0001
// Verbose message
//  sub: none
//  arg: none
#define MSG_VERBOSE	0x0002
// A new layout must be loaded as the current model.
//  sub: none
//  arg: URL of the new layout to load
#define MSG_LOADLAYOUT 0x0100 // = 256
// The previous layout (if any) must be loaded as the current model.
//  sub: none
//  arg: none
#define MSG_BACKLAYOUT 0x0101 // = 257
// An action must be processed by the current model.
//  sub: action ID
//  arg: action arg
#define MSG_ACTION	0x0102 // = 258
// An accept must be processed by the current model.
//  sub: none
//  arg: none
#define MSG_ACCEPT	0x0103 // = 259
// A cancel must be processed by the current model.
//  sub: none
//  arg: none
#define MSG_CANCEL	0x0104 // = 260
// The current model must be rendered.
//  sub: none
//  arg: none
#define MSG_RENDER	0x0105 // = 261
// The current model must be activated.
//  sub: none
//  arg: none
#define MSG_ACTIVATE	0x0106 // = 262
// The current layout must be repainted.
//  sub: none
//  arg: none
#define MSG_REPAINT	0x0201 // = 513
// A slot must be repainted.
//  sub: none
//  arg: a pointer on the concerned bitmap
#define MSG_REFBITMAP	0x0202 // = 514
//
// Messages whose value is over this one are considered as user's messages.
// Their semantics is not known by the framework itself, nor any of its
// standard components.
//  sub: none
//  arg: none
#define MSG_USER	0x1000

//
// MESSAGES OPTIONS:
//
// This flag means that the arg is a pointer that must be deleted
// by the consumer of the message.
#define MFG_DYNARG 0x00010000
// This flag means that the message must not be deleted
// when the current layout is changed and the queues are flushed
#define MFG_UNFLUSHABLE 0x00020000


// Default maximum number of pending messages in a queue
#ifndef QUEUE_LEN
#define QUEUE_LEN	20
#endif // ndef QUEUE_LEN


class KRMessage {
public:
	long msgType ;
	long msgSubType ;
	long msgArg ;
	KALEIDO_TIME_TYPE msgScheduled ; // At what time should this message be used ?
	//
	DEFINE_NEW(KRMessage);
	DEFINE_DELETE(KRMessage);
	KRMessage()
	{
	}

	void setValues(long newMsgType, long newMsgSubType, long newMsgArg, KALEIDO_TIME_TYPE newMsgScheduled)
	{
		msgType      = newMsgType;
		msgSubType   = newMsgSubType;
		msgArg       = newMsgArg;
		msgScheduled = newMsgScheduled;
		return ;
	}

	void setValues(KRMessage* from)
	{
		msgType      = from->msgType;
		msgSubType   = from->msgSubType;
		msgArg       = from->msgArg;
		msgScheduled = from->msgScheduled;
		return ;
	}

} ;

typedef KRMessage* pKRMessage ;

class KREBDLIBS_API KRMessages {
private:
	pKRMessage* queueData ;
	int isScheduled ;   // false when the scheduling information is not important for this queue
	int queueLen ;      // Lenght of the queue
	int pQueuePending ;  // Pending messages
	int queueWrite ;    // Next index to write
	int queueRead ;     // Next index to read


/*
<api>
    <class>KRMessages</class>
    <method>findMessage</method>
    <cpp>int findMessage(long msgType);</cpp>
    <descr>
        <p>This method finds the first message found in the queue and whose msgType
	 is the same as the submitted one.
	 It returns the index of the message found, or -1 if  such a message does not yet exist.</p>
    </descr>
</api>
*/
	int findMessage(long msgType);

/*
<api>
    <class>KRMessages</class>
    <method>findMessage</method>
    <cpp>int findMessage(long msgType, long msgSubType</cpp>
    <descr>
        <p>This method finds the first message found in the queue and whose msgType & msgSubType
	 are the same as the submitted ones
 It returns the index of the message found, or -1 if  such a message does not yet exist.</p>
    </descr>
</api>
*/
	int findMessage(long msgType, long msgSubType);

/*
<api>
    <class>KRMessages</class>
    <method>dropMessage</method>
    <cpp>int dropMessage(int index)</cpp>
    <descr>
        <p>This method allows to drop a message.
	 All the messages are moved down in order to fill the free place.
	 It returns the number of free slots.</p>
    </descr>
</api>
*/
	int dropMessage(int index);

/*
<api>
    <class>KRMessages</class>
    <method>insertMessage</method>
    <cpp>int insertMessage(int index, long msgType, long msgSubType, long msgArg, KALEIDO_TIME_TYPE msgScheduled=0)</cpp>
    <descr>
        <p>This method allows to insert a message.
	 All the messages are moved up in order to get the necessary place.
	 It returns the number of free slots, or -1 if there is not enough place to
	 complete the action.</p>
    </descr>
</api>
*/
	int insertMessage(int index, long msgType, long msgSubType, long msgArg, KALEIDO_TIME_TYPE msgScheduled=0);
	//
public:
	DEFINE_NEW(KRMessages);
	DEFINE_DELETE(KRMessages);
	//
	KRMessages(int scheduled=0, int len=QUEUE_LEN) ;

	~KRMessages() ;

	/*
	returns the nb of pending messages in the queue
	*/
	int size() {
		return pQueuePending;
	}

	void setScheduled(int scheduled)
	{ isScheduled = scheduled ; }

/*
<api>
    <class>KRMessages</class>
    <method>pushMessage</method>
    <cpp>int pushMessage(long msgType, long msgSubType, long msgArg, long msgScheduled=0)</cpp>
    <descr>
        <p>This method pushes a message on a queue. If there is no more free space to achieve this action, the message is dropped. It returns the number of free slots, or -1 if there is not enough space to complete the action.</p>
    </descr>
</api>
*/
	int pushMessage(long msgType, long msgSubType, long msgArg, KALEIDO_TIME_TYPE msgScheduled=0) ;

	/*
<api>
    <class>KRMessages</class>
    <method>scheduleMessage</method>
    <cpp>int scheduleMessage(long msgType, long msgSubType, long msgArg, long msgScheduled=0)</cpp>
    <descr>
    <p>This method adds and schedules a new message to a queue. It should only be used for scheduled queues. The message is going to be inserted at the right place in the queue, depending on its msgScheduled arg. If there is no free space, the message is dropped and the method returns -1. Otherwise, the method returns the index of the inserted message.</p>
    </descr>
</api>
*/
	int scheduleMessage(long msgType, long msgSubType, long msgArg, KALEIDO_TIME_TYPE msgScheduled);

/*
<api>
    <class>KRMessages</class>
    <method>addMessage</method>
    <cpp>int addMessage(long msgType, long msgSubType, long msgArg, long msgScheduled=0)</cpp>
    <descr>
    <p>This method adds a new message to a queue. If the queue is scheduled, the new message is scheduled. If the queue is not scheduled, the new message is simply pushed. If there is no free space, the message is dropped and the method returns -1. Otherwise, the method returns the number of free slots.</p>
    </descr>
</api>
*/
	int addMessage(long msgType, long msgSubType, long msgArg, KALEIDO_TIME_TYPE msgScheduled=0);

/*
<api>
    <class>KRMessages</class>
    <method>updateMessage</method>
    <cpp>int updateMessage(long msgType, long msgSubType, long msgArg, long msgScheduled=0)</cpp>
    <descr>
    <p>This method updates the first message found in a queue and whose msgType is the same as the submitted one. If such a message is not yet in the queue, it is created as new one. If such a message is already in the queue:</p>
    <itemlist>
        <item>
            <p>If the queue is scheduled: the queue is updated.</p></item>
        <item>
            <p>If the queue is not scheduled: the message's place is kept if it was already existing. It returns the number of free slots, or -1 if there is not enough space to complete the action.</p></item>
     </itemlist>
     </descr>
</api>
*/
	int updateMessage(long msgType, long msgSubType, long msgArg, KALEIDO_TIME_TYPE msgScheduled=0, int checkEarlier=0);

/*
<kaleidoc>
<filename>KRMessages</filename>
<page>
<api>
    <class>KRMessages</class>
    <method>updateOlderMessage</method>
    <cpp>int updateOlderMessage(long msgType, long msgSubType, long msgArg, long msgScheduled=0)</cpp>
    <descr>
    <p>This method is very similar to updateMessage, but the message is not updated if the same msgType/msgSubType pair is already scheduled for an earlier date.</p>
    </descr>
</api>
</page>
</kaleidoc>
*/
int updateOlderMessage(long msgType, long msgSubType, long msgArg, KALEIDO_TIME_TYPE msgScheduled)
	{
		return updateMessage(msgType, msgSubType, msgArg, msgScheduled, 1) ;
	}


/*
<kaleidoc>
<filename>KRMessages</filename>
<page>
<api>
    <class>KRMessages</class>
    <method>dropMessages</method>
    <cpp>int dropMessages(long msgType, long msgSubType)</cpp>
    <descr>
    <p>This method drops all the messages of the concerned msgType/msgSubType pair.</p>
    </descr>
</api>
</page>
</kaleidoc>
*/
int dropMessages(long msgType, long msgSubType);

/*
<kaleidoc>
<filename>KRMessages</filename>
<page>
<api>
    <class>KRMessages</class>
    <method>popMessage</method>
    <cpp>KRMessage* popMessage()</cpp>
    <descr>
    <p>This method pops the oldest message from a queue. It returns NULL if there is no available message.</p>
    </descr>
</api>
</page>
</kaleidoc>
*/
KRMessage* popMessage();

/*
<kaleidoc>
<filename>KRMessages</filename>
<page>
<api>
    <class>KRMessages</class>
    <method>peekMessage</method>
    <cpp>KRMessage* peekMessage()</cpp>
    <descr>
    <p>This method peeks a message from a queue. The returned message is left in the queue. It returns NULL if there is no available message.</p>
    </descr>
</api>
</page>
</kaleidoc>
*/
KRMessage* peekMessage() ;

	int getPending()
	{ return pQueuePending; }

#ifdef DEV_DEBUG
	void dump(KALEIDO_TIME_TYPE currentTime, pchar prefix= (pchar) "") ;
#endif // def DEV_DEBUG
#ifdef DEV_MONITOR
	void monitor(KALEIDO_TIME_TYPE currentTime,char* prefix) ;
#endif // def DEV_MONITOR
} ;


#endif // ndef __KR_MESSAGES__