Fawkes API  Fawkes Development Version
message.h
1 
2 /***************************************************************************
3  * message.h - Fawkes network message
4  *
5  * Created: Mon Nov 20 18:00:09 2006
6  * Copyright 2006 Tim Niemueller [www.niemueller.de]
7  *
8  ****************************************************************************/
9 
10 /* This program is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version. A runtime exception applies to
14  * this software (see LICENSE.GPL_WRE file mentioned below for details).
15  *
16  * This program is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19  * GNU Library General Public License for more details.
20  *
21  * Read the full text in the LICENSE.GPL_WRE file in the doc directory.
22  */
23 
24 #ifndef __NETCOMM_FAWKES_MESSAGE_H_
25 #define __NETCOMM_FAWKES_MESSAGE_H_
26 
27 #include <core/utils/refcount.h>
28 #include <core/exceptions/software.h>
29 
30 #include <cstddef>
31 
32 namespace fawkes {
33 
34 #pragma pack(push,4)
35 
36 /** Fawkes network message header.
37  * Header that is prepended to all following messages.
38  */
39 typedef struct {
40  unsigned short int cid; /**< component id */
41  unsigned short int msg_id; /**< message id */
42  unsigned int payload_size; /**< payload size in bytes */
44 
45 #pragma pack(pop)
46 
47 /** Message as stored in local queues.
48  * A message takes a header and a pointer to the data that
49  * has the size mentioned in header.payload_size that is to be
50  * sent over the network.
51  */
52 typedef struct {
53  fawkes_message_header_t header; /**< message header */
54  void *payload; /**< message payload */
56 
57 
58 /** Fawkes transfer header.
59  * This header is prepended to a collection of messages that is sent
60  * at once.
61  */
62 typedef struct {
63  unsigned int size; /**< size of the following payload. */
65 
66 
68 {
69  public:
70  FawkesNetworkMessageTooBigException(size_t message_size);
71 };
72 
74 
76 {
77  public:
78  FawkesNetworkMessage(unsigned int clid, fawkes_message_t &msg);
80  FawkesNetworkMessage(unsigned int clid,
81  unsigned short int cid, unsigned short int msg_id,
82  void *payload, size_t payload_size);
83  FawkesNetworkMessage(unsigned int clid,
84  unsigned short int cid, unsigned short int msg_id);
85  FawkesNetworkMessage(unsigned short int cid, unsigned short int msg_id,
86  void *payload, size_t payload_size);
87  FawkesNetworkMessage(unsigned int clid,
88  unsigned short int cid, unsigned short int msg_id,
90  FawkesNetworkMessage(unsigned short int cid, unsigned short int msg_id,
92  FawkesNetworkMessage(unsigned short int cid, unsigned short int msg_id,
93  size_t payload_size);
94  FawkesNetworkMessage(unsigned short int cid, unsigned short int msg_id);
96 
97  virtual ~FawkesNetworkMessage();
98 
99  unsigned int clid() const;
100  unsigned short int cid() const;
101  unsigned short int msgid() const;
102  size_t payload_size() const;
103  void * payload() const;
104  const fawkes_message_t & fmsg() const;
105 
106  /** Get correctly casted payload.
107  * Use this method to cast the payload to a specific type. The size is
108  * check as a sanity check and a TypeMismatchException is thrown if the
109  * size does not match.
110  * @return casted message
111  * @exception TypeMismatchException payload size does not match requested type
112  */
113  template <typename MT>
114  MT *
115  msg() const
116  {
117  if ( payload_size() != sizeof(MT) ) {
118  throw TypeMismatchException("FawkesNetworkMessage: message has incorrect size for this type");
119  }
120  return (MT *)(_msg.payload);
121  }
122 
123  /** Get correctly casted payload.
124  * Use this method to cast the payload to a specific type. The size is
125  * check as a sanity check and a TypeMismatchException is thrown if the
126  * size does not match. The size of the received message must be greater or
127  * equal to the size of the message type. Useful if message contains a variable
128  * length string.
129  * @return casted message
130  * @exception TypeMismatchException payload size does not match requested type
131  */
132  template <typename MT>
133  MT *
134  msgge() const
135  {
136  if ( payload_size() < sizeof(MT) ) {
137  throw TypeMismatchException("FawkesNetworkMessage: message has incorrect size for this type");
138  }
139  return (MT *)(_msg.payload);
140  }
141 
142  /** Get correctly parsed output.
143  * Use this method to cast the payload to a specific complex type. You can use this
144  * routine to parse complex messages that are derived from FawkesNetworkMessageContent.
145  * Note that the class must provide a constructor that takes four parameters: The
146  * component ID, message ID, a pointer to the payload and the payload size. From this
147  * the class shall parse the output and throw an exception if that for whatever
148  * reason fails.
149  * @return casted message
150  * @exception TypeMismatchException payload size does not match requested type
151  */
152  template <typename MT>
153  MT *
154  msgc() const
155  {
156  try {
157  MT *m = new MT(cid(), msgid(), _msg.payload, payload_size());
158  return m;
159  } catch (Exception &e) {
160  throw;
161  } catch (...) {
162  throw Exception("Unknown exception caught while parsing complex network message");
163  }
164  }
165 
166  void set_client_id(unsigned int clid);
167  void set_component_id(unsigned short int cid);
168  void set_message_id(unsigned short int msg_id);
169  void set_payload(void *payload, size_t payload_size);
170  void set(fawkes_message_t &msg);
171  void set_content(FawkesNetworkMessageContent *content);
172 
173  void pack();
174 
175  private:
176  void init_cid_msgid(unsigned short int cid, unsigned short int msg_id);
177  void init_payload(size_t payload_size);
178 
179  unsigned int _clid;
180  fawkes_message_t _msg;
181 
182  FawkesNetworkMessageContent *_content;
183 };
184 
185 } // end namespace fawkes
186 
187 #endif
unsigned short int msg_id
message id
Definition: message.h:41
fawkes_message_header_t header
message header
Definition: message.h:53
MT * msgge() const
Get correctly casted payload.
Definition: message.h:134
Fawkes library namespace.
Exception()
Constructor for subclasses.
Definition: exception.cpp:257
Representation of a message that is sent over the network.
Definition: message.h:75
unsigned short int cid
component id
Definition: message.h:40
Fawkes transfer header.
Definition: message.h:62
MT * msgc() const
Get correctly parsed output.
Definition: message.h:154
Fawkes network message content.
Fawkes network message header.
Definition: message.h:39
Base class for exceptions in Fawkes.
Definition: exception.h:36
unsigned int payload_size
payload size in bytes
Definition: message.h:42
Message as stored in local queues.
Definition: message.h:52
void * payload
message payload
Definition: message.h:54
Reference counting base class.
Definition: refcount.h:32
FawkesNetworkMessageTooBigException(size_t message_size)
Constructor.
Definition: message.cpp:48
The given message size exceeds the limit.
Definition: message.h:67
MT * msg() const
Get correctly casted payload.
Definition: message.h:115
unsigned int size
size of the following payload.
Definition: message.h:63