/*
* 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