1 /*

     2 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  This class provides container for message.

    15 *

    16 */

    17 

    18 

    19 #ifndef COMMSMESSAGE_H

    20 #define COMMSMESSAGE_H

    21 

    22 #include <string>

    23 #include <sstream>

    24 

    25 #include "javaosheaders.h"

    26 #include "transport.h"

    27 #include "commspermissions.h"

    28 

    29 namespace java

    30 {

    31 namespace util

    32 {

    33 class Uid;

    34 }//end util

    35 namespace comms

    36 {

    37 

    38 /**

    39 * CommsMessage class provides container for message payload. It provides an

    40 * interface to manipulate payload as if it was input/output stream.

    41 *

    42 * Comms message consists of header fields and message body.

    43 * Header is used to route message to correct endpoint and listener.

    44 * Header consists of following fields:

    45 * - module id, identifies which listener is used to handle message

    46 * - message id, identifies message

    47 * - receiver, identifies receiving endpoint

    48 * - sender, identifies sending endpoint

    49 * - message reference, identifies message

    50 *

    51 * Message payload can be read and write using stream operations (<<, >>).

    52 * Message can contain multiple items (ints, strings etc) that must be

    53 * read in the same order as they were originally written.

    54 *

    55 * There is no limit to message size but some other interprocess communication mechanism

    56 * should be considered if message sizes exceed 60k bytes.

    57 *

    58 * Usage:

    59 * It is important that application fills message headers correctly as

    60 * message routing and dispatching is done based on header information.

    61 * Following headers should be set always: module id, message id, message reference

    62 * and receiver.

    63 * @code

    64 * CommsMessage msg;

    65 *

    66 * // Following headers must be set always

    67 * msg.setModuleId(MY_MODULE_ID);

    68 * msg.setMessageId(MY_MESSAGE_ID);

    69 *

    70 * // Following header should be set if replying

    71 * msg.setMessageRef(aMesssage.getMessageRef());

    72 *

    73 * // If CommsServerEndpoint is used then also receiver header must be filled

    74 * msg.setReceiver(aMessage.getSender());

    75 *

    76 * // or use replyTo() method instead of setting each header field separately

    77 *

    78 * // Message payload can be written using insert operator

    79 * msg << "this is a string" << 1234 << L"this is a wstring";

    80 *

    81 * // Message payload can be read using extract operator

    82 * std::string s;

    83 * std::wstring w;

    84 * int i;

    85 * msg >> s >> i >> w;

    86 * @endcode

    87 *

    88 * @see CommsListener, CommsEndpoint

    89 */

    90 class CommsMessage

    91 {

    92 public:

    93     /**

    94     * Constructs a message.

    95     * Content is initialized to an empty stream.

    96     */

    97     OS_IMPORT CommsMessage();

    98 

    99     /**

   100     * Constructs a message.

   101     * Content is initialized to a copy of the IPC message pointer

   102     * @param[in] aMessage Pointer to IPC message, which content is used to initialize the content of this

   103     */

   104     OS_IMPORT CommsMessage(const ipcMessage_t* aMessage);

   105 

   106     /**

   107     * Constructs a message.

   108     * Content is initialized to a copy of the CommsMessage object

   109     * @param[in] aMessage Object whose content is used to initialize the content of this

   110     */

   111     OS_IMPORT CommsMessage(const CommsMessage& aMessage);

   112 

   113     /**

   114     * A destructor.

   115     */

   116     OS_IMPORT virtual ~CommsMessage();

   117 

   118     /**

   119     * Message assignment.

   120     * Sets a copy of the argument as the new content for this object.

   121     * The previous content is dropped.

   122     * @code

   123     * CommsMessage a, b;

   124     * a << "hello world";

   125     * b = a;

   126     * @endcode

   127     * @param[in] aMessage Comms message. A copy of the content of this object is used as the new content for the object

   128     */

   129     OS_IMPORT CommsMessage& operator=(const CommsMessage& aMessage);

   130 

   131     /**

   132      * Sets message id, identifies message type

   133      * @param aMessageId message id

   134      */

   135     OS_IMPORT void setMessageId(int aMessageId);

   136 

   137     /**

   138      * Sets module id, identifies which listener is used to handle message

   139      * @param aModuleId module id

   140      */

   141     OS_IMPORT void setModuleId(int aModuleId);

   142 

   143     /**

   144      * Sets message reference, identifies message

   145      * @param aMessageRef message reference

   146      */

   147     OS_IMPORT void setMessageRef(int aMessageRef);

   148 

   149     /**

   150      * Sets receiver, identifies receiving endpoint

   151      * @param aReceiver receiver

   152      */

   153     OS_IMPORT void setReceiver(int aReceiver);

   154 

   155     /**

   156      * Sets sender, identifies sending endpoint

   157      * @param aSender sender

   158      */

   159     OS_IMPORT void setSender(int aSender);

   160 

   161     /**

   162      * Returns message id, identifies message type

   163      * @return message id

   164      */

   165     OS_IMPORT int getMessageId() const;

   166 

   167     /**

   168      * Returns module id, identifies which listener is used to handle message

   169      * @return module id

   170      */

   171     OS_IMPORT int getModuleId() const;

   172 

   173     /**

   174      * Returns message reference, identifies message

   175      * @return message reference

   176      */

   177     OS_IMPORT int getMessageRef() const;

   178 

   179     /**

   180      * Returns receiver, identifies receiving endpoint

   181      * @return receiver

   182      */

   183     OS_IMPORT int getReceiver() const;

   184 

   185     /**

   186      * Returns sender, identifies sending endpoint

   187      * @return sender

   188      */

   189     OS_IMPORT int getSender() const;

   190 

   191     /**

   192      * Checks what permissions sender of the message has.

   193      * CommsPermission enumeration defines the set of supported permissions.

   194      * @code

   195      * MyListener::processMessage(CommsMessage& aMessage)

   196      * {

   197      *     if( aMessage.hasPermission(MANAGE_CERTIFICATES) )

   198      *     {

   199      *         // manage certificates

   200      *     }

   201      * }

   202      * @endcode

   203      * @see CommsPermission

   204      * @return true, if sender of the message has given permission

   205      */

   206     OS_IMPORT bool hasPermission(const CommsPermission& aPermission) const;

   207 

   208     /**

   209      * Sets headers so that reply is sent to given message.

   210      * @code

   211      * CommsMessage msg;

   212      * msg.replyTo(aMessage);

   213      * // is equivalent to

   214      * msg.setModuleId(aMessage.getModuleId());

   215      * msg.setMessageId(aMessage.getMessageId());

   216      * msg.setMessageRef(aMessage.getMessageRef());

   217      * msg.setReceiver(aMessage.getSender());

   218      * msg.setSender(aMessage.getReceiver());

   219      * @endcode

   220      * @param aMessage Address where the reply should be sent

   221      * @return -

   222      */

   223     OS_IMPORT void replyTo(const CommsMessage& aMessage);

   224 

   225     /**

   226      * Insert data to message.

   227      * @code

   228      * CommsMessage msg;

   229      * // Message payload can be written using insert operator

   230      * msg << "this is a string" << 1234 << L"this is a wstring";

   231      * @endcode

   232      * @param aStr A value to be inserted

   233      * @return The object itself (*this).

   234      */

   235     OS_IMPORT CommsMessage& operator << (const std::string& aStr);

   236 

   237     /**

   238      * Insert data to message.

   239      * @code

   240      * CommsMessage msg;

   241      * // Message payload can be written using insert operator

   242      * msg << "this is a string" << 1234 << L"this is a wstring";

   243      * @endcode

   244      * @param aStr A value to be inserted

   245      * @return The object itself (*this).

   246      */

   247     OS_IMPORT CommsMessage& operator << (const std::wstring& aStr);

   248 

   249     /**

   250      * Insert data to message.

   251      * @code

   252      * CommsMessage msg;

   253      * // Message payload can be written using insert operator

   254      * msg << "this is a string" << 1234 << L"this is a wstring";

   255      * @endcode

   256      * @param aInt A value to be inserted

   257      * @return The object itself (*this).

   258      */

   259     OS_IMPORT CommsMessage& operator << (const int& aInt);

   260 

   261     /**

   262      * Insert data to message.

   263      * @code

   264      * CommsMessage msg;

   265      * // Message payload can be written using insert operator

   266      * msg << "this is a string" << 1234LL << L"this is a wstring";

   267      * @endcode

   268      * @param aLong A value to be inserted

   269      * @return The object itself (*this).

   270      */

   271     OS_IMPORT CommsMessage& operator << (const long long& aLong);

   272 

   273     /**

   274      * Insert data to message.

   275      * @param aUid A value to be inserted

   276      * @return The object itself (*this).

   277      */

   278     OS_IMPORT CommsMessage& operator << (const java::util::Uid& aUid);

   279 

   280     /**

   281      * Extract data from message.

   282      * @code

   283      * CommsMessage msg;

   284      * // Message payload can be read using extract operator

   285      * std::string s;

   286      * std::wstring w;

   287      * int i;

   288      * msg >> s >> i >> w;

   289      * @endcode

   290      * @param aStr String that contains extracted data

   291      * @return The object itself (*this).

   292      */

   293     OS_IMPORT CommsMessage& operator >> (std::wstring& aStr);

   294 

   295     /**

   296      * Extract data from message.

   297      * @code

   298      * CommsMessage msg;

   299      * // Message payload can be read using extract operator

   300      * std::string s;

   301      * std::wstring w;

   302      * int i;

   303      * msg >> s >> i >> w;

   304      * @endcode

   305      * @param aStr String that contains extracted data

   306      * @return The object itself (*this).

   307      */

   308     OS_IMPORT CommsMessage& operator >> (std::string& aStr);

   309 

   310     /**

   311      * Extract data from message.

   312      * @code

   313      * CommsMessage msg;

   314      * // Message payload can be read using extract operator

   315      * std::string s;

   316      * std::wstring w;

   317      * int i;

   318      * msg >> s >> i >> w;

   319      * @endcode

   320      * @param aInt Integer that contains extracted data

   321      * @return The object itself (*this).

   322      */

   323     OS_IMPORT CommsMessage& operator >> (int& aInt);

   324 

   325     /**

   326      * Extract data from message.

   327      * @code

   328      * CommsMessage msg;

   329      * // Message payload can be read using extract operator

   330      * std::string s;

   331      * std::wstring w;

   332      * long long i;

   333      * msg >> s >> i >> w;

   334      * @endcode

   335      * @param aLong Integer that contains extracted data

   336      * @return The object itself (*this).

   337      */

   338     OS_IMPORT CommsMessage& operator >> (long long& aLong);

   339 

   340     /**

   341      * Extract data from message.

   342      * @code

   343      * java::util::Uid uid;

   344      * msg >> uid;

   345      * @endcode

   346      * @param aUid Uid object that contains extracted data

   347      * @return The object itself (*this).

   348      */

   349     OS_IMPORT CommsMessage& operator >> (java::util::Uid& aUid);

   350 

   351     /**

   352     * Sets the position of the get pointer to the beginning of the stream.

   353     * The get pointer determines the next location to be read from the source stream

   354     * @code

   355     * CommsMessage msg;

   356     * msg << 1 << 2;

   357     * int a, b;

   358     * msg >> a;

   359     * msg.begin();

   360     * msg >> b;

   361     * // a == b == 1

   362     * @endcode

   363     * @param -

   364     * @return -

   365     */

   366     OS_IMPORT void begin();

   367 

   368     /**

   369     * The reset() function resets the header and deletes the contents of the stream.

   370     * @code

   371     * CommsMessage msg, empty;

   372     * msg.setMessageId(MY_MESSAGE_ID);

   373     * msg << 1 << 2;

   374     * msg.reset();

   375     * // msg == empty== true

   376     * @endcode

   377     * @param -

   378     * @return -

   379     */

   380     OS_IMPORT void reset();

   381 

   382     /**

   383     * Converts CommsMessage to byte array.

   384     *

   385     * The returned array points to an internal location with the required storage space

   386     * for this sequence of characters , but the values in this array should not be

   387     * modified in the program and are only granted to remain unchanged until the next

   388     * call to a non-constant member function of the CommsMessage object.

   389     *

   390     * Returned byte array can be casted to ipcMessage_t* if needed.

   391     * @code

   392     * char* arr = aMsg.toByteArray();

   393     * ipcMessage_t& msg = *(ipcMessage_t*)arr;

   394     * @endcode

   395     * @param -

   396     * @return bytearray

   397     */

   398     OS_IMPORT char* toByteArray();

   399 

   400     /**

   401     * Get the message's current payload as string.

   402     * @param -

   403     * @return String whose content is copied from the message's stream buffer

   404     */

   405     OS_IMPORT std::string toString() const;

   406 

   407     /**

   408     * Evaluate message's internal stream object state.

   409     * Returns true if either one of the error flags (failbit or badbit)

   410     * is set on the stream. Otherwise it returns false.

   411     *

   412     * This behavior is equivalent to std::ios::fail().

   413     * @code

   414     * CommsMessage msg;

   415     * msg << "string1" << "string2" << "string3";

   416     * string a, temp;

   417     * msg >> a;

   418     * while(!(msg>>temp)); // ignore rest

   419     * @endcode

   420     * @param -

   421     * @return true if either failbit or badbit is set.

   422     * @return false otherwise.

   423     */

   424     OS_IMPORT bool operator !() const;

   425 

   426     /**

   427     * Converts message's internal stream object to pointer.

   428     * This pointer is a null pointer if either one of the error flags (failbit or badbit) is set,

   429     * otherwise it is a non-zero pointer.

   430     * The pointer returned is not intended to be referenced, it just indicates success when

   431     * none of the error flags are set.

   432     * @code

   433     * CommsMessage msg;

   434     * msg << "string";

   435     * if ( (void*)msg == 0)

   436     * {

   437     *    cerr << "something wrong with the message";

   438     * }

   439     * @endcode

   440     * @param -

   441     * @return null pointer if either failbit or badbit is set on object internal message stream.

   442     * @return A non-null pointer otherwise.

   443     */

   444     OS_IMPORT operator void*() const;

   445 

   446 private:

   447     std::stringstream  mStream;

   448     ipcHeader_t        mHeader;

   449     char*              mArray;

   450 };

   451 

   452 } // namespace comms

   453 } // namespace java

   454 

   455 #endif // COMMSMESSAGE_H