A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
three-gpp-http-server.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2013 Magister Solutions
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Budiarto Herman <budiarto.herman@magister.fi>
7 *
8 */
9
10#ifndef THREE_GPP_HTTP_SERVER_H
11#define THREE_GPP_HTTP_SERVER_H
12
14
15#include <ns3/address.h>
16#include <ns3/application.h>
17#include <ns3/event-id.h>
18#include <ns3/nstime.h>
19#include <ns3/ptr.h>
20#include <ns3/simple-ref-count.h>
21#include <ns3/traced-callback.h>
22
23#include <map>
24#include <ostream>
25
26namespace ns3
27{
28
29class Socket;
30class Packet;
31class ThreeGppHttpVariables;
32class ThreeGppHttpServerTxBuffer;
33
34/**
35 * \ingroup http
36 * Model application which simulates the traffic of a web server. This
37 * application works in conjunction with ThreeGppHttpClient applications.
38 *
39 * The application works by responding to requests. Each request is a small
40 * packet of data which contains ThreeGppHttpHeader. The value of the *content
41 * type* field of the header determines the type of object that the client is
42 * requesting. The possible type is either a *main object* or an *embedded
43 * object*.
44 *
45 * The application is responsible to generate the right type of object and send
46 * it back to the client. The size of each object to be sent is randomly
47 * determined (see ThreeGppHttpVariables). Each object may be sent as multiple packets
48 * due to limited socket buffer space.
49 *
50 * To assist with the transmission, the application maintains several instances
51 * of ThreeGppHttpServerTxBuffer. Each instance keeps track of the object type to be
52 * served and the number of bytes left to be sent.
53 *
54 * The application accepts connection request from clients. Every connection is
55 * kept open until the client disconnects.
56 */
58{
59 public:
60 /**
61 * Creates a new instance of HTTP server application.
62 *
63 * After creation, the application must be further configured through
64 * attributes. To avoid having to do this process manually, please use
65 * ThreeGppHttpServerHelper.
66 *
67 * Upon creation, the application randomly determines the MTU size that it
68 * will use (either 536 or 1460 bytes). The chosen size will be used while
69 * creating the listener socket.
70 */
72
73 /**
74 * Returns the object TypeId.
75 * \return The object TypeId.
76 */
77 static TypeId GetTypeId();
78
79 /**
80 * Sets the maximum transmission unit (MTU) size used by the application.
81 *
82 * This overrides the MTU size which is randomly determined once the
83 * application is created. Values other than the standard 536 and 1460 bytes
84 * can be set using this method.
85 *
86 * \param mtuSize MTU size in bytes.
87 */
88 void SetMtuSize(uint32_t mtuSize);
89
90 /**
91 * Returns a pointer to the listening socket.
92 * \return Pointer to the listening socket
93 */
94 Ptr<Socket> GetSocket() const;
95
96 /// The possible states of the application.
98 {
99 NOT_STARTED = 0, ///< Before StartApplication() is invoked.
100 STARTED, ///< Passively listening and responding to requests.
101 STOPPED ///< After StopApplication() is invoked.
102 };
103
104 /**
105 * Returns the current state of the application.
106 * \return The current state of the application.
107 */
108 State_t GetState() const;
109
110 /**
111 * Returns the current state of the application in string format.
112 * \return The current state of the application in string format.
113 */
114 std::string GetStateString() const;
115
116 /**
117 * Returns the given state in string format.
118 * \param state An arbitrary state of an application.
119 * \return The given state equivalently expressed in string format.
120 */
121 static std::string GetStateString(State_t state);
122
123 /**
124 * Common callback signature for `MainObject` and `EmbeddedObject` trace
125 * sources.
126 * \param size Size of the generated object in bytes.
127 */
129
130 /**
131 * Callback signature for `ConnectionEstablished` trace source.
132 * \param httpServer Pointer to this instance of ThreeGppHttpServer, which is where
133 * the trace originated.
134 * \param socket Pointer to the socket where the connection is established.
135 */
137 Ptr<Socket> socket);
138
139 protected:
140 void DoDispose() override;
141
142 private:
143 void StartApplication() override;
144 void StopApplication() override;
145
146 // SOCKET CALLBACK METHODS
147
148 /**
149 * Invoked when #m_initialSocket receives a connection request.
150 * \param socket Pointer to the socket where the event originates from.
151 * \param address The address of the remote client where the connection
152 * request comes from.
153 * \return Always true, to indicate to the other end that the connection
154 * request is accepted.
155 */
156 bool ConnectionRequestCallback(Ptr<Socket> socket, const Address& address);
157 /**
158 * Invoked when a new connection has been established.
159 * \param socket Pointer to the socket that maintains the connection to the
160 * remote client. This socket will be saved to the Tx buffer.
161 * \param address The address the connection is incoming from.
162 */
163 void NewConnectionCreatedCallback(Ptr<Socket> socket, const Address& address);
164 /**
165 * Invoked when a connection with a web client is terminated. The
166 * corresponding socket will be removed from Tx buffer.
167 * \param socket Pointer to the socket where the event originates from.
168 */
169 void NormalCloseCallback(Ptr<Socket> socket);
170 /**
171 * Invoked when a connection with a web client is terminated. The
172 * corresponding socket will be removed from Tx buffer.
173 * \param socket Pointer to the socket where the event originates from.
174 */
175 void ErrorCloseCallback(Ptr<Socket> socket);
176 /**
177 * Invoked when #m_initialSocket receives some packet data. It will check the
178 * packet for ThreeGppHttpHeader. It also fires the `Rx` trace source.
179 *
180 * Depending on the type of object requested, the method will trigger
181 * ServeMainObject() or ServeEmbeddedObject() after some delays.
182 *
183 * \param socket Pointer to the socket where the event originates from.
184 */
186 /**
187 * Invoked when more buffer space for transmission is added to a socket. The
188 * method will invoke ServeFromTxBuffer() to start some transmission using
189 * the socket.
190 * \param socket Pointer to the socket where the event originates from.
191 * \param availableBufferSize The number of bytes available in the socket's
192 * transmission buffer.
193 */
194 void SendCallback(Ptr<Socket> socket, uint32_t availableBufferSize);
195
196 // TX-RELATED METHODS
197
198 /**
199 * Generates a new main object and push it into the Tx buffer.
200 *
201 * The size of the object is randomly determined by ThreeGppHttpVariables.
202 * Fires the `MainObject` trace source. It then immediately triggers
203 * ServeFromTxBuffer() to send the object.
204 *
205 * \param socket Pointer to the socket which is associated with the
206 * destination client.
207 */
208 void ServeNewMainObject(Ptr<Socket> socket);
209 /**
210 * Generates a new embedded object and push it into the Tx buffer.
211 *
212 * The size of the object is randomly determined by ThreeGppHttpVariables.
213 * Fires the `EmbeddedObject` trace source. It then immediately triggers
214 * ServeFromTxBuffer() to send the object.
215 *
216 * \param socket Pointer to the socket which is associated with the
217 * destination client.
218 */
220 /**
221 * Creates a packet out of a pending object in the Tx buffer send it over the
222 * given socket. If the socket capacity is smaller than the object size, then
223 * the method only convert a part of the object into a packet.
224 *
225 * ThreeGppHttpHeader will be attached in the beginning of each application
226 * layer packet - if a packet is split, then then the following parts will
227 * not have the header. The method fires the `Tx` trace source after sending
228 * the packet to the socket.
229 *
230 * This method is invoked when a new object is generated by
231 * ServeNewMainObject() or ServeNewEmbeddedObject(). It's also invoked when
232 * the socket informs (through SendCallback()) that more buffer space for
233 * transmission has become available.
234 *
235 * \param socket Pointer to the socket which is associated with the
236 * destination client.
237 * \return Size of the packet sent (in bytes).
238 */
240
241 /**
242 * Change the state of the server. Fires the `StateTransition` trace source.
243 * \param state The new state.
244 */
245 void SwitchToState(State_t state);
246
247 /// The current state of the client application. Begins with NOT_STARTED.
249 /// The listening socket, for receiving connection requests from clients.
251 /// Pointer to the transmission buffer.
253
254 // ATTRIBUTES
255
256 /// The `Variables` attribute.
258 /// The `LocalAddress` attribute.
260 /// The `LocalPort` attribute.
261 uint16_t m_localPort;
262 /// The `Tos` attribute.
263 uint8_t m_tos;
264 /// The `Mtu` attribute.
266
267 // TRACE SOURCES
268
269 /// The `ConnectionEstablished` trace source.
271 /// The `MainObject` trace source.
273 /// The `EmbeddedObject` trace source.
275 /// The `Tx` trace source.
277 /// The `Rx` trace source.
279 /// The `RxDelay` trace source.
281 /// The `StateTransition` trace source.
283
284}; // end of `class ThreeGppHttpServer`
285
286/**
287 * \internal
288 * \ingroup http
289 * Transmission buffer used by an HTTP server instance.
290 *
291 * The class handles the sockets which face the connected HTTP clients. An
292 * individual buffer is allocated for each socket. The buffer indicates the
293 * length (in bytes) and the type of the data within, i.e., it does *not*
294 * contain the actual packet data.
295 *
296 * Types of data are expressed using the ThreeGppHttpHeader::ContentType_t type. Only one
297 * type of data can be active for one client at a time, i.e., the current
298 * content of a buffer has to be removed before a different type of data can
299 * be added.
300 */
301class ThreeGppHttpServerTxBuffer : public SimpleRefCount<ThreeGppHttpServerTxBuffer>
302{
303 public:
304 /// Create an empty instance of transmission buffer.
306
307 // SOCKET MANAGEMENT
308
309 /**
310 * This method is typically used before calling other methods. For example,
311 * AddSocket() requires that the given socket does not exist among the stored
312 * buffers. On the other hand, all the other methods that accept a pointer to
313 * a socket as an argument require the existence of a buffer allocated to the
314 * given socket.
315 * \param socket Pointer to the socket to be found.
316 * \return True if the given socket is found within the buffer.
317 */
318 bool IsSocketAvailable(Ptr<Socket> socket) const;
319
320 /**
321 * Add a new socket and create an empty transmission buffer for it. After the
322 * method is completed, IsSocketAvailable() for the same pointer of socket
323 * shall return true.
324 * \param socket Pointer to the new socket to be added (must not exist in the
325 * buffer).
326 * \warning Must be called only when IsSocketAvailable() for the given socket
327 * is false.
328 */
329 void AddSocket(Ptr<Socket> socket);
330
331 /**
332 * Remove a socket and its associated transmission buffer, and then unset the
333 * socket's callbacks to prevent further interaction with the socket. If the
334 * socket has a pending transmission event, it will be canceled.
335 *
336 * This method is useful for discarding a socket which is already closed,
337 * e.g., by the HTTP client. This is due to the fact that double closing of a
338 * socket may introduce undefined behaviour.
339 *
340 * After the method is completed, IsSocketAvailable() for the same pointer of
341 * socket shall return false.
342 *
343 * \param socket Pointer to the socket to be removed.
344 * \warning Must be called only when IsSocketAvailable() for the given socket
345 * is true.
346 */
347 void RemoveSocket(Ptr<Socket> socket);
348
349 /**
350 * Close and remove a socket and its associated transmission buffer, and then
351 * unset the socket's callback to prevent further interaction with the
352 * socket.
353 *
354 * This method is similar with RemoveSocket(), except that the latter does
355 * not close the socket.
356 *
357 * After the method is completed, IsSocketAvailable() for the same pointer of
358 * socket shall return false.
359 *
360 * \param socket Pointer to the socket to be closed and removed.
361 * \warning Must be called only when IsSocketAvailable() for the given socket
362 * is true.
363 */
364 void CloseSocket(Ptr<Socket> socket);
365
366 /**
367 * Close and remove all stored sockets, hence clearing the buffer.
368 */
369 void CloseAllSockets();
370
371 // BUFFER MANAGEMENT
372
373 /**
374 * \param socket Pointer to the socket which is associated with the
375 * transmission buffer of interest.
376 * \return True if the current length of the transmission buffer is zero,
377 * i.e., no pending packet.
378 * \warning Must be called only when IsSocketAvailable() for the given socket
379 * is true.
380 */
381 bool IsBufferEmpty(Ptr<Socket> socket) const;
382
383 /**
384 * \param socket Pointer to the socket which is associated with the
385 * transmission buffer of interest
386 * \return The client time stamp that comes from the last request packet
387 * received by the given socket. It indicates the time the request
388 * packet was transmitted by the client.
389 */
390 Time GetClientTs(Ptr<Socket> socket) const;
391
392 /**
393 * Returns ThreeGppHttpHeader::NOT_SET when the buffer is new and never been filled
394 * with any data before. Otherwise, returns either ThreeGppHttpHeader::MAIN_OBJECT
395 * or ThreeGppHttpHeader::EMBEDDED_OBJECT.
396 * \param socket Pointer to the socket which is associated with the
397 * transmission buffer of interest
398 * \return The content type of the current data inside the transmission
399 * buffer.
400 * \warning Must be called only when IsSocketAvailable() for the given socket
401 * is true.
402 */
404
405 /**
406 * \param socket Pointer to the socket which is associated with the
407 * transmission buffer of interest
408 * \return The length (in bytes) of the current data inside the transmission
409 * buffer.
410 * \warning Must be called only when IsSocketAvailable() for the given socket
411 * is true.
412 */
413 uint32_t GetBufferSize(Ptr<Socket> socket) const;
414
415 /**
416 * \param socket pointer to the socket which is associated with the
417 * transmission buffer of interest
418 * \return true if the buffer content has been read since it is written
419 *
420 * \warning Must be called only when IsSocketAvailable() for the given socket
421 * is true.
422 *
423 * This method returns true after WriteNewObject() method is called. It
424 * becomes false after DepleteBufferSize() method is called.
425 */
426 bool HasTxedPartOfObject(Ptr<Socket> socket) const;
427
428 /**
429 * Writes a data representing a new main object or embedded object to the
430 * transmission buffer.
431 *
432 * The stored data can be later consumed wholly of partially by
433 * DepleteBufferSize() method.
434 *
435 * \param socket Pointer to the socket which is associated with the
436 * transmission buffer of interest.
437 * \param contentType The content-type of the data to be written (must not
438 * equal to ThreeGppHttpHeader:NOT_SET).
439 * \param objectSize The length (in bytes) of the new object to be created
440 * (must be greater than zero).
441 * \warning Must be called only when both IsSocketAvailable() and
442 * IsBufferEmpty() for the given socket are true.
443 */
444 void WriteNewObject(Ptr<Socket> socket,
446 uint32_t objectSize);
447
448 /**
449 * Informs about a pending transmission event associated with the socket, so
450 * that it would be automatically canceled in case the socket is closed.
451 *
452 * The method also indicates the time stamp given by the client. The time
453 * stamp will be included in every packet sent.
454 *
455 * \param socket pointer to the socket which is associated with the
456 * transmission buffer of interest
457 * \param eventId the event to be recorded, e.g., the return value of
458 * Simulator::Schedule function
459 * \param clientTs client time stamp
460 *
461 * \warning Must be called only when IsSocketAvailable() for the given socket
462 * is true.
463 */
464 void RecordNextServe(Ptr<Socket> socket, const EventId& eventId, const Time& clientTs);
465
466 /**
467 * Decrements a buffer size by a given amount.
468 *
469 * The content type of the object to be consumed can be inquired beforehand
470 * by the GetBufferContentType() method.
471 *
472 * If the method has consumed all the remaining bytes within the buffer,
473 * IsBufferEmpty() for the buffer shall return true.
474 *
475 * \param socket Pointer to the socket which is associated with the
476 * transmission buffer of interest.
477 * \param amount The length (in bytes) to be consumed (must be greater than
478 * zero).
479 *
480 * \warning Must be called only when IsSocketAvailable() for the given socket
481 * is true. In addition, the requested amount must be larger than
482 * the current buffer size, which can be checked by calling the
483 * GetBufferSize() method.
484 */
485 void DepleteBufferSize(Ptr<Socket> socket, uint32_t amount);
486
487 /**
488 * Tell the buffer to close the associated socket once the buffer becomes
489 * empty.
490 * \param socket Pointer to the socket which is associated with the
491 * transmission buffer of interest.
492 * \warning Must be called only when IsSocketAvailable() for the given socket
493 * is true.
494 */
495 void PrepareClose(Ptr<Socket> socket);
496
497 private:
498 /**
499 * Set of fields representing a single transmission buffer, which will be
500 * associated with a socket.
501 */
503 {
504 /**
505 * Pending transmission event which will be automatically canceled when the
506 * associated socket is closed.
507 */
509 /**
510 * The client time stamp that comes from the request packet. This value
511 * will be set in ThreeGppHttpHeader of every corresponding response packet sent, to
512 * be used by the client to compute round trip delay time (RTT).
513 */
515 /**
516 * The content type of the current data inside the transmission buffer.
517 * Accessible using the GetBufferContentType() method.
518 */
520 /**
521 * The length (in bytes) of the current data inside the transmission
522 * buffer. Accessible using the GetBufferSize() method.
523 */
525 /**
526 * True if the remote end has issued a request to close, which means that
527 * this socket will immediately closes itself once the buffer becomes
528 * empty.
529 */
531 /**
532 * \brief True if the buffer content has been read since it is written.
533 * Accessible using the HasTxedPartOfObject() method.
534 */
536 };
537
538 /// Collection of accepted sockets and its individual transmission buffer.
539 std::map<Ptr<Socket>, TxBuffer_t> m_txBuffer;
540
541}; // end of `class ThreeGppHttpServerTxBuffer`
542
543} // namespace ns3
544
545#endif /* THREE_GPP_HTTP_SERVER_H */
a polymophic address class
Definition address.h:90
The base class for all ns3 applications.
Definition application.h:51
An identifier for simulation events.
Definition event-id.h:45
Smart pointer class similar to boost::intrusive_ptr.
A template-based reference counting class.
ContentType_t
The possible types of content (default = NOT_SET).
Model application which simulates the traffic of a web server.
State_t
The possible states of the application.
@ NOT_STARTED
Before StartApplication() is invoked.
@ STOPPED
After StopApplication() is invoked.
@ STARTED
Passively listening and responding to requests.
void StartApplication() override
Application specific startup code.
uint32_t ServeFromTxBuffer(Ptr< Socket > socket)
Creates a packet out of a pending object in the Tx buffer send it over the given socket.
State_t m_state
The current state of the client application. Begins with NOT_STARTED.
void(* ThreeGppHttpObjectCallback)(uint32_t size)
Common callback signature for MainObject and EmbeddedObject trace sources.
Ptr< ThreeGppHttpVariables > m_httpVariables
The Variables attribute.
uint16_t m_localPort
The LocalPort attribute.
TracedCallback< uint32_t > m_embeddedObjectTrace
The EmbeddedObject trace source.
Address m_localAddress
The LocalAddress attribute.
void ReceivedDataCallback(Ptr< Socket > socket)
Invoked when m_initialSocket receives some packet data.
void ServeNewMainObject(Ptr< Socket > socket)
Generates a new main object and push it into the Tx buffer.
TracedCallback< uint32_t > m_mainObjectTrace
The MainObject trace source.
uint32_t m_mtuSize
The Mtu attribute.
TracedCallback< const Time &, const Address & > m_rxDelayTrace
The RxDelay trace source.
State_t GetState() const
Returns the current state of the application.
Ptr< ThreeGppHttpServerTxBuffer > m_txBuffer
Pointer to the transmission buffer.
void(* ConnectionEstablishedCallback)(Ptr< const ThreeGppHttpServer > httpServer, Ptr< Socket > socket)
Callback signature for ConnectionEstablished trace source.
bool ConnectionRequestCallback(Ptr< Socket > socket, const Address &address)
Invoked when m_initialSocket receives a connection request.
void ServeNewEmbeddedObject(Ptr< Socket > socket)
Generates a new embedded object and push it into the Tx buffer.
TracedCallback< const std::string &, const std::string & > m_stateTransitionTrace
The StateTransition trace source.
void ErrorCloseCallback(Ptr< Socket > socket)
Invoked when a connection with a web client is terminated.
void SendCallback(Ptr< Socket > socket, uint32_t availableBufferSize)
Invoked when more buffer space for transmission is added to a socket.
TracedCallback< Ptr< const Packet >, const Address & > m_rxTrace
The Rx trace source.
uint8_t m_tos
The Tos attribute.
Ptr< Socket > GetSocket() const
Returns a pointer to the listening socket.
TracedCallback< Ptr< const ThreeGppHttpServer >, Ptr< Socket > > m_connectionEstablishedTrace
The ConnectionEstablished trace source.
Ptr< Socket > m_initialSocket
The listening socket, for receiving connection requests from clients.
static TypeId GetTypeId()
Returns the object TypeId.
std::string GetStateString() const
Returns the current state of the application in string format.
ThreeGppHttpServer()
Creates a new instance of HTTP server application.
TracedCallback< Ptr< const Packet > > m_txTrace
The Tx trace source.
void NormalCloseCallback(Ptr< Socket > socket)
Invoked when a connection with a web client is terminated.
void DoDispose() override
Destructor implementation.
void StopApplication() override
Application specific shutdown code.
void NewConnectionCreatedCallback(Ptr< Socket > socket, const Address &address)
Invoked when a new connection has been established.
void SetMtuSize(uint32_t mtuSize)
Sets the maximum transmission unit (MTU) size used by the application.
void SwitchToState(State_t state)
Change the state of the server.
void DepleteBufferSize(Ptr< Socket > socket, uint32_t amount)
Decrements a buffer size by a given amount.
ThreeGppHttpHeader::ContentType_t GetBufferContentType(Ptr< Socket > socket) const
Returns ThreeGppHttpHeader::NOT_SET when the buffer is new and never been filled with any data before...
uint32_t GetBufferSize(Ptr< Socket > socket) const
void CloseAllSockets()
Close and remove all stored sockets, hence clearing the buffer.
bool HasTxedPartOfObject(Ptr< Socket > socket) const
void PrepareClose(Ptr< Socket > socket)
Tell the buffer to close the associated socket once the buffer becomes empty.
Time GetClientTs(Ptr< Socket > socket) const
void CloseSocket(Ptr< Socket > socket)
Close and remove a socket and its associated transmission buffer, and then unset the socket's callbac...
ThreeGppHttpServerTxBuffer()
Create an empty instance of transmission buffer.
void RecordNextServe(Ptr< Socket > socket, const EventId &eventId, const Time &clientTs)
Informs about a pending transmission event associated with the socket, so that it would be automatica...
std::map< Ptr< Socket >, TxBuffer_t > m_txBuffer
Collection of accepted sockets and its individual transmission buffer.
void WriteNewObject(Ptr< Socket > socket, ThreeGppHttpHeader::ContentType_t contentType, uint32_t objectSize)
Writes a data representing a new main object or embedded object to the transmission buffer.
bool IsBufferEmpty(Ptr< Socket > socket) const
bool IsSocketAvailable(Ptr< Socket > socket) const
This method is typically used before calling other methods.
void AddSocket(Ptr< Socket > socket)
Add a new socket and create an empty transmission buffer for it.
void RemoveSocket(Ptr< Socket > socket)
Remove a socket and its associated transmission buffer, and then unset the socket's callbacks to prev...
Simulation virtual time values and global simulation resolution.
Definition nstime.h:94
Forward calls to a chain of Callback.
a unique identifier for an interface.
Definition type-id.h:48
Every class exported by the ns3 library is enclosed in the ns3 namespace.
Set of fields representing a single transmission buffer, which will be associated with a socket.
ThreeGppHttpHeader::ContentType_t txBufferContentType
The content type of the current data inside the transmission buffer.
uint32_t txBufferSize
The length (in bytes) of the current data inside the transmission buffer.
EventId nextServe
Pending transmission event which will be automatically canceled when the associated socket is closed.
bool isClosing
True if the remote end has issued a request to close, which means that this socket will immediately c...
bool hasTxedPartOfObject
True if the buffer content has been read since it is written.
Time clientTs
The client time stamp that comes from the request packet.