WARNING : this is the documentation for an old version of SFML ; the documentation for the latest official release is available through the main menu

Tutorial - Network - Using HTTP

Introduction

HTTP (HyperText Transfer Protocol) is the protocol which is used to transfer files through internet: web pages, images, etc. It consists of a client-server architecture where the client sends requests, and the server sends back responses containing the requested resources.

SFML provides a class which implements a HTTP client: sf::Http.

Requests

An HTTP request in SFML is represented by the sf::Http::Request class. It contains five members:

• A method, which is the action to execute; it can be one of the following values:
  • sf::Http::Request::Get: gets the specified resource (page, image, etc.)
  • sf::Http::Request::Post: sends the specified content to the server
  • sf::Http::Request::Head: gets only the header of the specified resource, without its body
• A target URI, which is the resource to get if the method is Get or Head, or the page to send the content to, if the method is Post; this URI is relative to the host address (see later)
• A body, which is the content to send if the method is Post; it is ignored if the method is Get or Head
• An HTTP version, which is used by the server to identify which version of the protocol the client is using; this version is 1.0 if you don't explicitely change it (which will work in most situations)
• A set of <name, value> pairs, which represent options to pass to the server; some of them are mandatory (like "Host", "From", "Content-Length") but SFML takes care of filling them if you don't do it

Each of these five members can be set through an accessor of the sf::Http::Request:

sf::Http::Request Request;
Request.SetMethod(sf::Http::Request::Get);
Request.SetURI("/");
Request.SetBody("");
Request.SetHttpVersion(1, 0);
Request.SetField("From", "my_email@gmail.com");

Note that all these members have a correct default value; SFML always makes sure that your requests are well-formed so that you can focus on the important parameters (most likely the target URI).
This request could thus be simplified to the following piece of code:

sf::Http::Request Request;
Request.SetURI("/");

Responses

After sending a request (we'll see that in the next section), you receive a response from the server. Such a response is represented by the sf::Http::Response class in SFML.

A response consists of four members:

• A status code which informs about the success or failure of the operation
• A body, which is the content of the requested resource; if the requested resource is a web page, it contains the HTML code of the page. It can also be empty or contain the HTML code of an error page, if the operation failed
• An HTTP version, which is the one used by the server
• A set of <name, value> pairs, which represent various informations about the server which are passed back to the client

All these members can be read through accessors of the sf::Http::Response class:

sf::Http::Response Response;
...
sf::Http::Response::Status Status = Response.GetStatus();
unsigned int Major = Response.GetMajorHttpVersion();
unsigned int Minor = Response.GetMinorHttpVersion();
std::string Body = Response.GetBody();
std::string Type = Response.GetField("Content-Type");

Statuses are described in the sf::Http::Response::Status enumeration. There are multiple success codes, but the most common one is sf::Http::Response::Ok.

Putting it all together

Now that you can write requests and read responses, you only need to know two more things: connecting to an HTTP server, and sending requests.

Connection to a server can be done through the SetHost function:

sf::Http Http;
Http.SetHost("www.whatismyip.org");

In fact, this function does nothing more than storing the host name, the actual connection is done each time you send a request, and is closed after receiving the response. This is why this function is called SetHost rather than Connect.

This function can accept an additionnal parameter: the network port to use for connection. If you don't explicitely specify it, SFML will just use the default port associated to the protocol: 80 for HTTP, and 443 for HTTPS.

Once the host server is set, you can send requests with the SendRequest function:

sf::Http::Response Response = Http.SendRequest(Request);

This function takes an argument of type sf::Http::Request, and returns an instance of sf::Http::Response.

That's all for the interface of the sf::Http class, only two functions! There's no need to explicitely disconnect from the server, as the connection is automatically closed after each call to SendRequest

Conclusion

The sf::Http class is a powerful tool for manipulating the HTTP protocol, and access web page or files through internet.
Let's now have a look at its friend, the FTP protocol.

Download source code :