A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
three-gpp-http-client.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_CLIENT_H
11#define THREE_GPP_HTTP_CLIENT_H
12
13#include "source-application.h"
15
16#include "ns3/address.h"
17#include "ns3/traced-callback.h"
18
19#include <optional>
20
21namespace ns3
22{
23
24class Socket;
25class Packet;
27
28/**
29 * @ingroup applications
30 * @defgroup http ThreeGppHttpClientServer
31 *
32 * This traffic generator simulates web browsing traffic using the Hypertext
33 * Transfer Protocol (HTTP). It consists of one or more ThreeGppHttpClient
34 * applications which connect to an ThreeGppHttpServer application. The client
35 * models a web browser which requests web pages to the server. The server
36 * is then responsible to serve the web pages as requested. Please refer to
37 * ThreeGppHttpClientHelper and ThreeGppHttpServerHelper for usage instructions.
38 *
39 * Technically speaking, the client transmits *request objects* to demand a
40 * service from the server. Depending on the type of request received, the
41 * server transmits either:
42 * - a *main object*, i.e., the HTML file of the web page; or
43 * - an *embedded object*, e.g., an image referenced by the HTML file.
44 *
45 * A major portion of the traffic pattern is *reading time*, which does not
46 * generate any traffic. Because of this, one may need to simulate a good
47 * number of clients and/or sufficiently long simulation duration in order to
48 * generate any significant traffic in the system.
49 *
50 * Many aspects of the traffic are randomly determined by ThreeGppHttpVariables.
51 * These characteristics are based on a legacy 3GPP specification. The description
52 * can be found in the following references:
53 * - 3GPP TR 25.892, "Feasibility Study for Orthogonal Frequency Division
54 * Multiplexing (OFDM) for UTRAN enhancement"
55 * - IEEE 802.16m, "Evaluation Methodology Document (EMD)",
56 * IEEE 802.16m-08/004r5, July 2008.
57 * - NGMN Alliance, "NGMN Radio Access Performance Evaluation Methodology",
58 * v1.0, January 2008.
59 * - 3GPP2-TSGC5, "HTTP, FTP and TCP models for 1xEV-DV simulations", 2001.
60 */
61
62/**
63 * @ingroup http
64 * Model application which simulates the traffic of a web browser. This
65 * application works in conjunction with an ThreeGppHttpServer application.
66 *
67 * In summary, the application works as follows.
68 * 1. Upon start, it opens a connection to the destination web server
69 * (ThreeGppHttpServer).
70 * 2. After the connection is established, the application immediately requests
71 * a *main object* from the server by sending a request packet.
72 * 3. After receiving a main object (which can take some time if it consists of
73 * several packets), the application "parses" the main object.
74 * 4. The parsing takes a short time (randomly determined) to determine the
75 * number of *embedded objects* (also randomly determined) in the web page.
76 * - If at least one embedded object is determined, the application requests
77 * the first embedded object from the server. The request for the next
78 * embedded object follows after the previous embedded object has been
79 * completely received.
80 * - If there is no more embedded object to request, the application enters
81 * the *reading time*.
82 * 5. Reading time is a long delay (again, randomly determined) where the
83 * application does not induce any network traffic, thus simulating the user
84 * reading the downloaded web page.
85 * 6. After the reading time is finished, the process repeats to step #2.
86 *
87 * The client models HTTP *persistent connection*, i.e., HTTP 1.1, where the
88 * connection to the server is maintained and used for transmitting and receiving
89 * all objects.
90 *
91 * Each request by default has a constant size of 350 bytes. A ThreeGppHttpHeader
92 * is attached to each request packet. The header contains information
93 * such as the content type requested (either main object or embedded object)
94 * and the timestamp when the packet is transmitted (which will be used to
95 * compute the delay and RTT of the packet).
96 */
98{
99 public:
100 /**
101 * Creates a new instance of HTTP client application.
102 *
103 * After creation, the application must be further configured through
104 * attributes. To avoid having to do this process manually, please use
105 * ThreeGppHttpClientHelper.
106 */
108 void SetRemote(const Address& addr) override;
109
110 /**
111 * Returns the object TypeId.
112 * @return The object TypeId.
113 */
114 static TypeId GetTypeId();
115
116 /**
117 * Returns a pointer to the associated socket.
118 * @return Pointer to the associated socket.
119 */
120 Ptr<Socket> GetSocket() const;
121
122 /// The possible states of the application.
124 {
125 /// Before StartApplication() is invoked.
127 /// Sent the server a connection request and waiting for the server to be accept it.
129 /// Sent the server a request for a main object and waiting to receive the packets.
131 /// Parsing a main object that has just been received.
133 /// Sent the server a request for an embedded object and waiting to receive the packets.
135 /// User reading a web page that has just been received.
137 /// After StopApplication() is invoked.
139 };
140
141 /**
142 * Returns the current state of the application.
143 * @return The current state of the application.
144 */
145 State_t GetState() const;
146
147 /**
148 * Returns the current state of the application in string format.
149 * @return The current state of the application in string format.
150 */
151 std::string GetStateString() const;
152
153 /**
154 * Returns the given state in string format.
155 * @param state An arbitrary state of an application.
156 * @return The given state equivalently expressed in string format.
157 */
158 static std::string GetStateString(State_t state);
159
160 /**
161 * Common callback signature for `ConnectionEstablished`, `RxMainObject`, and
162 * `RxEmbeddedObject` trace sources.
163 * @param httpClient Pointer to this instance of ThreeGppHttpClient,
164 * which is where the trace originated.
165 */
167
168 /**
169 * Callback signature for `RxPage` trace sources.
170 * @param httpClient Pointer to this instance of ThreeGppHttpClient,
171 * which is where the trace originated.
172 * @param time Elapsed time from the start to the end of the request.
173 * @param numObjects Number of objects downloaded, including main and
174 * embedded objects.
175 * @param numBytes Total number of bytes included in the page.
176 */
178 const Time& time,
179 uint32_t numObjects,
180 uint32_t numBytes);
181
182 protected:
183 void DoDispose() override;
184
185 private:
186 void StartApplication() override;
187 void StopApplication() override;
188
189 /**
190 * @brief set the remote port (temporary function until deprecated attributes are removed)
191 * @param port remote port
192 */
193 void SetPort(uint16_t port);
194
195 // SOCKET CALLBACK METHODS
196
197 /**
198 * Invoked when a connection is established successfully on #m_socket. This
199 * triggers a request for a main object.
200 * @param socket Pointer to the socket where the event originates from.
201 */
203 /**
204 * Invoked when #m_socket cannot establish a connection with the web server.
205 * Simulation will stop and error will be raised.
206 * @param socket Pointer to the socket where the event originates from.
207 */
209 /**
210 * Invoked when connection between #m_socket and the web sever is terminated.
211 * Error will be logged, but simulation continues.
212 * @param socket Pointer to the socket where the event originates from.
213 */
214 void NormalCloseCallback(Ptr<Socket> socket);
215 /**
216 * Invoked when connection between #m_socket and the web sever is terminated.
217 * Error will be logged, but simulation continues.
218 * @param socket Pointer to the socket where the event originates from.
219 */
220 void ErrorCloseCallback(Ptr<Socket> socket);
221 /**
222 * Invoked when #m_socket receives some packet data. Fires the `Rx` trace
223 * source and triggers ReceiveMainObject() or ReceiveEmbeddedObject().
224 * @param socket Pointer to the socket where the event originates from.
225 */
227
228 // CONNECTION-RELATED METHOD
229
230 /**
231 * Initialize #m_socket to connect to the destination web server at
232 * #m_peer and #m_peerPort and set up callbacks to
233 * listen to its event. Invoked upon the start of the application.
234 */
235 void OpenConnection();
236
237 // TX-RELATED METHODS
238
239 /**
240 * Send a request object for a main object to the destination web server.
241 * The size of the request packet is randomly determined by HttpVariables and
242 * is assumed to be smaller than 536 bytes. Fires the `TxMainObjectRequest`
243 * trace source.
244 *
245 * The method is invoked after a connection is established or after a
246 * reading time has elapsed.
247 */
248 void RequestMainObject();
249 /**
250 * Send a request object for an embedded object to the destination web
251 * server. The size of the request packet is randomly determined by
252 * ThreeGppHttpVariables and is assumed to be smaller than 536 bytes. Fires the
253 * `TxEmbeddedObjectRequest` trace source.
254 */
256
257 // RX-RELATED METHODS
258
259 /**
260 * Receive a packet of main object from the destination web server. Fires the
261 * `RxMainObjectPacket` trace source.
262 *
263 * A main object may come from more than one packets. This is determined by
264 * comparing the content length specified in the ThreeGppHttpHeader of the packet and
265 * the actual packet size. #m_objectBytesToBeReceived keeps track of the
266 * number of bytes that has been received.
267 *
268 * If the received packet is not the last packet of the object, then the
269 * method simply quits, expecting it to be invoked again when the next packet
270 * comes.
271 *
272 * If the received packet is the last packet of the object, then the method
273 * fires the `RxMainObject`, `RxDelay`, and `RxRtt` trace sources. The client
274 * then triggers EnterParsingTime().
275 *
276 * @param packet The received packet.
277 * @param from Address of the sender.
278 */
279 void ReceiveMainObject(Ptr<Packet> packet, const Address& from);
280 /**
281 * Receive a packet of embedded object from the destination web server. Fires
282 * the `RxEmbeddedObjectPacket` trace source.
283 *
284 * An embedded object may come from more than one packets. This is determined
285 * by comparing the content length specified in the TheeGppHttpHeader of the packet and
286 * the actual packet size. #m_objectBytesToBeReceived keeps track of the
287 * number of bytes that has been received.
288 *
289 * If the received packet is not the last packet of the object, then the
290 * method simply quits, expecting it to be invoked again when the next packet
291 * comes.
292 *
293 * If the received packet is the last packet of the object, then the method
294 * fires the `RxEmbeddedObject`, `RxDelay`, and `RxRtt` trace sources.
295 * Depending on the number of embedded objects remaining
296 * (#m_embeddedObjectsToBeRequested) the client can either trigger
297 * RequestEmbeddedObject() or EnterReadingTime().
298 *
299 * @param packet The received packet.
300 * @param from Address of the sender.
301 */
302 void ReceiveEmbeddedObject(Ptr<Packet> packet, const Address& from);
303 /**
304 * Simulate a consumption of the received packet by subtracting the packet
305 * size from the internal counter at #m_objectBytesToBeReceived. Also updates
306 * #m_objectClientTs and #m_objectServerTs according to the ThreeGppHttpHeader
307 * found in the packet.
308 *
309 * This method is invoked as a sub-procedure of ReceiveMainObject() and
310 * ReceiveEmbeddedObject().
311 *
312 * @param packet The received packet. If it is the first packet of the object,
313 * then it must have a ThreeGppHttpHeader attached to it.
314 */
315 void Receive(Ptr<Packet> packet);
316
317 // OFF-TIME-RELATED METHODS
318
319 /**
320 * Becomes idle for a randomly determined amount of time, and then triggers
321 * ParseMainObject(). The length of idle time is determined by
322 * TheeGppHttpVariables.
323 *
324 * The method is invoked after a complete main object has been received.
325 */
326 void EnterParsingTime();
327 /**
328 * Randomly determines the number of embedded objects in the main object.
329 * ThreeGppHttpVariables is utilized for this purpose. Then proceeds with
330 * RequestEmbeddedObject(). If the number of embedded objects has been
331 * determined as zero, then EnterReadingTime() is triggered.
332 *
333 * The method is invoked after parsing time has elapsed.
334 */
335 void ParseMainObject();
336 /**
337 * Becomes idle for a randomly determined amount of time, and then triggers
338 * RequestMainObject(). The length of idle time is determined by
339 * ThreeGppHttpVariables.
340 *
341 * The method is invoked after a complete web page has been received.
342 */
343 void EnterReadingTime();
344 /**
345 * Cancels #m_eventRequestMainObject, #m_eventRequestEmbeddedObject, and
346 * #m_eventParseMainObject. Invoked by StopApplication() and when connection
347 * has been terminated.
348 */
350
351 /**
352 * Change the state of the client. Fires the `StateTransition` trace source.
353 * @param state The new state.
354 */
355 void SwitchToState(State_t state);
356
357 /**
358 * Finish receiving a page. This function should be called when a full-page
359 * finishes loading, including the main object and all embedded objects.
360 */
361 void FinishReceivingPage();
362
363 /// The current state of the client application. Begins with NOT_STARTED.
365 /// The socket for sending and receiving packets to/from the web server.
367 /// According to the content length specified by the ThreeGppHttpHeader.
369 /// The packet constructed of one or more parts with ThreeGppHttpHeader.
371 /// The client time stamp of the ThreeGppHttpHeader from the last received packet.
373 /// The server time stamp of the ThreeGppHttpHeader from the last received packet.
375 /// Determined after parsing the main object.
377 /// The time stamp when the page started loading.
379 /// Number of embedded objects to requested in the current page.
381 /// Number of bytes received for the current page.
383
384 // ATTRIBUTES
385
386 /// The `Variables` attribute.
388 /// The `RemoteServerPort` attribute.
389 std::optional<uint16_t> m_peerPort;
390
391 // TRACE SOURCES
392
393 /// The `RxPage` trace source.
396 /// The `ConnectionEstablished` trace source.
398 /// The `ConnectionClosed` trace source.
400 /// The `Tx` trace source.
402 /// The `TxMainObjectRequest` trace source.
404 /// The `TxEmbeddedObjectRequest` trace source.
406 /// The `TxMainObjectPacket` trace source.
408 /// The `TxMainObject` trace source.
410 /// The `TxEmbeddedObjectPacket` trace source.
412 /// The `TxEmbeddedObject` trace source.
414 /// The `Rx` trace source.
416 /// The `RxDelay` trace source.
418 /// The `RxRtt` trace source.
420 /// The `StateTransition` trace source.
422
423 // EVENTS
424
425 /**
426 * An event of either RequestMainObject() or OpenConnection(), scheduled to
427 * trigger after a connection has been established or reading time has
428 * elapsed.
429 */
431 /**
432 * An event of either RequestEmbeddedObject() or OpenConnection().
433 */
435 /**
436 * An event of ParseMainObject(), scheduled to trigger after parsing time has
437 * elapsed.
438 */
440};
441
442} // namespace ns3
443
444#endif /* THREE_GPP_HTTP_CLIENT_H */
a polymophic address class
Definition address.h:90
An identifier for simulation events.
Definition event-id.h:45
network packets
Definition packet.h:228
Smart pointer class similar to boost::intrusive_ptr.
Definition ptr.h:66
A low-level Socket API based loosely on the BSD Socket API.
Definition socket.h:57
ns3::TracedCallback< const Time &, const Address & > m_rxRttTrace
The RxRtt trace source.
Time m_pageLoadStartTs
The time stamp when the page started loading.
ns3::TracedCallback< Ptr< const ThreeGppHttpClient >, const Time &, uint32_t, uint32_t > m_rxPageTrace
The RxPage trace source.
void SetPort(uint16_t port)
set the remote port (temporary function until deprecated attributes are removed)
void ReceiveMainObject(Ptr< Packet > packet, const Address &from)
Receive a packet of main object from the destination web server.
ns3::TracedCallback< Ptr< const ThreeGppHttpClient > > m_connectionClosedTrace
The ConnectionClosed trace source.
std::optional< uint16_t > m_peerPort
The RemoteServerPort attribute.
ns3::TracedCallback< const Time &, const Address & > m_rxDelayTrace
The RxDelay trace source.
ns3::TracedCallback< Ptr< const ThreeGppHttpClient >, Ptr< const Packet > > m_rxEmbeddedObjectTrace
The TxEmbeddedObject trace source.
Ptr< ThreeGppHttpVariables > m_httpVariables
The Variables attribute.
uint32_t m_embeddedObjectsToBeRequested
Determined after parsing the main object.
EventId m_eventParseMainObject
An event of ParseMainObject(), scheduled to trigger after parsing time has elapsed.
void SwitchToState(State_t state)
Change the state of the client.
uint32_t m_numberEmbeddedObjectsRequested
Number of embedded objects to requested in the current page.
void ConnectionFailedCallback(Ptr< Socket > socket)
Invoked when m_socket cannot establish a connection with the web server.
ThreeGppHttpClient()
Creates a new instance of HTTP client application.
ns3::TracedCallback< Ptr< const Packet >, const Address & > m_rxTrace
The Rx trace source.
void EnterParsingTime()
Becomes idle for a randomly determined amount of time, and then triggers ParseMainObject().
State_t m_state
The current state of the client application. Begins with NOT_STARTED.
void FinishReceivingPage()
Finish receiving a page.
Ptr< Socket > m_socket
The socket for sending and receiving packets to/from the web server.
void RequestEmbeddedObject()
Send a request object for an embedded object to the destination web server.
void ParseMainObject()
Randomly determines the number of embedded objects in the main object.
ns3::TracedCallback< Ptr< const ThreeGppHttpClient >, Ptr< const Packet > > m_rxMainObjectTrace
The TxMainObject trace source.
State_t GetState() const
Returns the current state of the application.
void EnterReadingTime()
Becomes idle for a randomly determined amount of time, and then triggers RequestMainObject().
void DoDispose() override
Destructor implementation.
void StartApplication() override
Application specific startup code.
Ptr< Packet > m_constructedPacket
The packet constructed of one or more parts with ThreeGppHttpHeader.
uint32_t m_objectBytesToBeReceived
According to the content length specified by the ThreeGppHttpHeader.
void ConnectionSucceededCallback(Ptr< Socket > socket)
Invoked when a connection is established successfully on m_socket.
static TypeId GetTypeId()
Returns the object TypeId.
void ErrorCloseCallback(Ptr< Socket > socket)
Invoked when connection between m_socket and the web sever is terminated.
EventId m_eventRequestMainObject
An event of either RequestMainObject() or OpenConnection(), scheduled to trigger after a connection h...
uint32_t m_numberBytesPage
Number of bytes received for the current page.
void(* TracedCallback)(Ptr< const ThreeGppHttpClient > httpClient)
Common callback signature for ConnectionEstablished, RxMainObject, and RxEmbeddedObject trace sources...
void(* RxPageTracedCallback)(Ptr< const ThreeGppHttpClient > httpClient, const Time &time, uint32_t numObjects, uint32_t numBytes)
Callback signature for RxPage trace sources.
void CancelAllPendingEvents()
Cancels m_eventRequestMainObject, m_eventRequestEmbeddedObject, and m_eventParseMainObject.
Ptr< Socket > GetSocket() const
Returns a pointer to the associated socket.
ns3::TracedCallback< Ptr< const Packet > > m_txTrace
The Tx trace source.
Time m_objectClientTs
The client time stamp of the ThreeGppHttpHeader from the last received packet.
State_t
The possible states of the application.
@ CONNECTING
Sent the server a connection request and waiting for the server to be accept it.
@ NOT_STARTED
Before StartApplication() is invoked.
@ READING
User reading a web page that has just been received.
@ EXPECTING_MAIN_OBJECT
Sent the server a request for a main object and waiting to receive the packets.
@ STOPPED
After StopApplication() is invoked.
@ PARSING_MAIN_OBJECT
Parsing a main object that has just been received.
@ EXPECTING_EMBEDDED_OBJECT
Sent the server a request for an embedded object and waiting to receive the packets.
ns3::TracedCallback< Ptr< const Packet > > m_txMainObjectRequestTrace
The TxMainObjectRequest trace source.
void StopApplication() override
Application specific shutdown code.
ns3::TracedCallback< Ptr< const Packet > > m_rxMainObjectPacketTrace
The TxMainObjectPacket trace source.
void SetRemote(const Address &addr) override
set the remote address
ns3::TracedCallback< const std::string &, const std::string & > m_stateTransitionTrace
The StateTransition trace source.
void RequestMainObject()
Send a request object for a main object to the destination web server.
Time m_objectServerTs
The server time stamp of the ThreeGppHttpHeader from the last received packet.
void NormalCloseCallback(Ptr< Socket > socket)
Invoked when connection between m_socket and the web sever is terminated.
ns3::TracedCallback< Ptr< const ThreeGppHttpClient > > m_connectionEstablishedTrace
The ConnectionEstablished trace source.
ns3::TracedCallback< Ptr< const Packet > > m_txEmbeddedObjectRequestTrace
The TxEmbeddedObjectRequest trace source.
void ReceivedDataCallback(Ptr< Socket > socket)
Invoked when m_socket receives some packet data.
ns3::TracedCallback< Ptr< const Packet > > m_rxEmbeddedObjectPacketTrace
The TxEmbeddedObjectPacket trace source.
void Receive(Ptr< Packet > packet)
Simulate a consumption of the received packet by subtracting the packet size from the internal counte...
void ReceiveEmbeddedObject(Ptr< Packet > packet, const Address &from)
Receive a packet of embedded object from the destination web server.
void OpenConnection()
Initialize m_socket to connect to the destination web server at m_peer and m_peerPort and set up call...
std::string GetStateString() const
Returns the current state of the application in string format.
EventId m_eventRequestEmbeddedObject
An event of either RequestEmbeddedObject() or OpenConnection().
Container of various random variables to assist in generating web browsing traffic pattern.
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:49
uint16_t port
Definition dsdv-manet.cc:33
Every class exported by the ns3 library is enclosed in the ns3 namespace.