/*
* Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  This class provides container for message.
*
*/


#ifndef COMMSMESSAGE_H
#define COMMSMESSAGE_H

#include <string>
#include <sstream>

#include "javaosheaders.h"
#include "transport.h"
#include "commspermissions.h"

namespace java
{
namespace util
{
class Uid;
}//end util
namespace comms
{

/**
* CommsMessage class provides container for message payload. It provides an
* interface to manipulate payload as if it was input/output stream.
*
* Comms message consists of header fields and message body.
* Header is used to route message to correct endpoint and listener.
* Header consists of following fields:
* - module id, identifies which listener is used to handle message
* - message id, identifies message
* - receiver, identifies receiving endpoint
* - sender, identifies sending endpoint
* - message reference, identifies message
*
* Message payload can be read and write using stream operations (<<, >>).
* Message can contain multiple items (ints, strings etc) that must be
* read in the same order as they were originally written.
*
* There is no limit to message size but some other interprocess communication mechanism
* should be considered if message sizes exceed 60k bytes.
*
* Usage:
* It is important that application fills message headers correctly as
* message routing and dispatching is done based on header information.
* Following headers should be set always: module id, message id, message reference
* and receiver.
* @code
* CommsMessage msg;
*
* // Following headers must be set always
* msg.setModuleId(MY_MODULE_ID);
* msg.setMessageId(MY_MESSAGE_ID);
*
* // Following header should be set if replying
* msg.setMessageRef(aMesssage.getMessageRef());
*
* // If CommsServerEndpoint is used then also receiver header must be filled
* msg.setReceiver(aMessage.getSender());
*
* // or use replyTo() method instead of setting each header field separately
*
* // Message payload can be written using insert operator
* msg << "this is a string" << 1234 << L"this is a wstring";
*
* // Message payload can be read using extract operator
* std::string s;
* std::wstring w;
* int i;
* msg >> s >> i >> w;
* @endcode
*
* @see CommsListener, CommsEndpoint
*/
class CommsMessage
{
public:
    /**
    * Constructs a message.
    * Content is initialized to an empty stream.
    */
    OS_IMPORT CommsMessage();

    /**
    * Constructs a message.
    * Content is initialized to a copy of the IPC message pointer
    * @param[in] aMessage Pointer to IPC message, which content is used to initialize the content of this
    */
    OS_IMPORT CommsMessage(const ipcMessage_t* aMessage);

    /**
    * Constructs a message.
    * Content is initialized to a copy of the CommsMessage object
    * @param[in] aMessage Object whose content is used to initialize the content of this
    */
    OS_IMPORT CommsMessage(const CommsMessage& aMessage);

    /**
    * A destructor.
    */
    OS_IMPORT virtual ~CommsMessage();

    /**
    * Message assignment.
    * Sets a copy of the argument as the new content for this object.
    * The previous content is dropped.
    * @code
    * CommsMessage a, b;
    * a << "hello world";
    * b = a;
    * @endcode
    * @param[in] aMessage Comms message. A copy of the content of this object is used as the new content for the object
    */
    OS_IMPORT CommsMessage& operator=(const CommsMessage& aMessage);

    /**
     * Sets message id, identifies message type
     * @param aMessageId message id
     */
    OS_IMPORT void setMessageId(int aMessageId);

    /**
     * Sets module id, identifies which listener is used to handle message
     * @param aModuleId module id
     */
    OS_IMPORT void setModuleId(int aModuleId);

    /**
     * Sets message reference, identifies message
     * @param aMessageRef message reference
     */
    OS_IMPORT void setMessageRef(int aMessageRef);

    /**
     * Sets receiver, identifies receiving endpoint
     * @param aReceiver receiver
     */
    OS_IMPORT void setReceiver(int aReceiver);

    /**
     * Sets sender, identifies sending endpoint
     * @param aSender sender
     */
    OS_IMPORT void setSender(int aSender);

    /**
     * Returns message id, identifies message type
     * @return message id
     */
    OS_IMPORT int getMessageId() const;

    /**
     * Returns module id, identifies which listener is used to handle message
     * @return module id
     */
    OS_IMPORT int getModuleId() const;

    /**
     * Returns message reference, identifies message
     * @return message reference
     */
    OS_IMPORT int getMessageRef() const;

    /**
     * Returns receiver, identifies receiving endpoint
     * @return receiver
     */
    OS_IMPORT int getReceiver() const;

    /**
     * Returns sender, identifies sending endpoint
     * @return sender
     */
    OS_IMPORT int getSender() const;

    /**
     * Checks what permissions sender of the message has.
     * CommsPermission enumeration defines the set of supported permissions.
     * @code
     * MyListener::processMessage(CommsMessage& aMessage)
     * {
     *     if( aMessage.hasPermission(MANAGE_CERTIFICATES) )
     *     {
     *         // manage certificates
     *     }
     * }
     * @endcode
     * @see CommsPermission
     * @return true, if sender of the message has given permission
     */
    OS_IMPORT bool hasPermission(const CommsPermission& aPermission) const;

    /**
     * Sets headers so that reply is sent to given message.
     * @code
     * CommsMessage msg;
     * msg.replyTo(aMessage);
     * // is equivalent to
     * msg.setModuleId(aMessage.getModuleId());
     * msg.setMessageId(aMessage.getMessageId());
     * msg.setMessageRef(aMessage.getMessageRef());
     * msg.setReceiver(aMessage.getSender());
     * msg.setSender(aMessage.getReceiver());
     * @endcode
     * @param aMessage Address where the reply should be sent
     * @return -
     */
    OS_IMPORT void replyTo(const CommsMessage& aMessage);

    /**
     * Insert data to message.
     * @code
     * CommsMessage msg;
     * // Message payload can be written using insert operator
     * msg << "this is a string" << 1234 << L"this is a wstring";
     * @endcode
     * @param aStr A value to be inserted
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator << (const std::string& aStr);

    /**
     * Insert data to message.
     * @code
     * CommsMessage msg;
     * // Message payload can be written using insert operator
     * msg << "this is a string" << 1234 << L"this is a wstring";
     * @endcode
     * @param aStr A value to be inserted
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator << (const std::wstring& aStr);

    /**
     * Insert data to message.
     * @code
     * CommsMessage msg;
     * // Message payload can be written using insert operator
     * msg << "this is a string" << 1234 << L"this is a wstring";
     * @endcode
     * @param aInt A value to be inserted
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator << (const int& aInt);

    /**
     * Insert data to message.
     * @code
     * CommsMessage msg;
     * // Message payload can be written using insert operator
     * msg << "this is a string" << 1234LL << L"this is a wstring";
     * @endcode
     * @param aLong A value to be inserted
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator << (const long long& aLong);

    /**
     * Insert data to message.
     * @param aUid A value to be inserted
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator << (const java::util::Uid& aUid);

    /**
     * Extract data from message.
     * @code
     * CommsMessage msg;
     * // Message payload can be read using extract operator
     * std::string s;
     * std::wstring w;
     * int i;
     * msg >> s >> i >> w;
     * @endcode
     * @param aStr String that contains extracted data
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator >> (std::wstring& aStr);

    /**
     * Extract data from message.
     * @code
     * CommsMessage msg;
     * // Message payload can be read using extract operator
     * std::string s;
     * std::wstring w;
     * int i;
     * msg >> s >> i >> w;
     * @endcode
     * @param aStr String that contains extracted data
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator >> (std::string& aStr);

    /**
     * Extract data from message.
     * @code
     * CommsMessage msg;
     * // Message payload can be read using extract operator
     * std::string s;
     * std::wstring w;
     * int i;
     * msg >> s >> i >> w;
     * @endcode
     * @param aInt Integer that contains extracted data
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator >> (int& aInt);

    /**
     * Extract data from message.
     * @code
     * CommsMessage msg;
     * // Message payload can be read using extract operator
     * std::string s;
     * std::wstring w;
     * long long i;
     * msg >> s >> i >> w;
     * @endcode
     * @param aLong Integer that contains extracted data
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator >> (long long& aLong);

    /**
     * Extract data from message.
     * @code
     * java::util::Uid uid;
     * msg >> uid;
     * @endcode
     * @param aUid Uid object that contains extracted data
     * @return The object itself (*this).
     */
    OS_IMPORT CommsMessage& operator >> (java::util::Uid& aUid);

    /**
    * Sets the position of the get pointer to the beginning of the stream.
    * The get pointer determines the next location to be read from the source stream
    * @code
    * CommsMessage msg;
    * msg << 1 << 2;
    * int a, b;
    * msg >> a;
    * msg.begin();
    * msg >> b;
    * // a == b == 1
    * @endcode
    * @param -
    * @return -
    */
    OS_IMPORT void begin();

    /**
    * The reset() function resets the header and deletes the contents of the stream.
    * @code
    * CommsMessage msg, empty;
    * msg.setMessageId(MY_MESSAGE_ID);
    * msg << 1 << 2;
    * msg.reset();
    * // msg == empty== true
    * @endcode
    * @param -
    * @return -
    */
    OS_IMPORT void reset();

    /**
    * Converts CommsMessage to byte array.
    *
    * The returned array points to an internal location with the required storage space
    * for this sequence of characters , but the values in this array should not be
    * modified in the program and are only granted to remain unchanged until the next
    * call to a non-constant member function of the CommsMessage object.
    *
    * Returned byte array can be casted to ipcMessage_t* if needed.
    * @code
    * char* arr = aMsg.toByteArray();
    * ipcMessage_t& msg = *(ipcMessage_t*)arr;
    * @endcode
    * @param -
    * @return bytearray
    */
    OS_IMPORT char* toByteArray();

    /**
    * Get the message's current payload as string.
    * @param -
    * @return String whose content is copied from the message's stream buffer
    */
    OS_IMPORT std::string toString() const;

    /**
    * Evaluate message's internal stream object state.
    * Returns true if either one of the error flags (failbit or badbit)
    * is set on the stream. Otherwise it returns false.
    *
    * This behavior is equivalent to std::ios::fail().
    * @code
    * CommsMessage msg;
    * msg << "string1" << "string2" << "string3";
    * string a, temp;
    * msg >> a;
    * while(!(msg>>temp)); // ignore rest
    * @endcode
    * @param -
    * @return true if either failbit or badbit is set.
    * @return false otherwise.
    */
    OS_IMPORT bool operator !() const;

    /**
    * Converts message's internal stream object to pointer.
    * This pointer is a null pointer if either one of the error flags (failbit or badbit) is set,
    * otherwise it is a non-zero pointer.
    * The pointer returned is not intended to be referenced, it just indicates success when
    * none of the error flags are set.
    * @code
    * CommsMessage msg;
    * msg << "string";
    * if ( (void*)msg == 0)
    * {
    *    cerr << "something wrong with the message";
    * }
    * @endcode
    * @param -
    * @return null pointer if either failbit or badbit is set on object internal message stream.
    * @return A non-null pointer otherwise.
    */
    OS_IMPORT operator void*() const;

private:
    std::stringstream  mStream;
    ipcHeader_t        mHeader;
    char*              mArray;
};

} // namespace comms
} // namespace java

#endif // COMMSMESSAGE_H