--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/javacommons/comms/inc/commsmessage.h Mon May 03 12:27:20 2010 +0300
@@ -0,0 +1,455 @@
+/*
+* 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