samples/net/http_client/README.rst - third_party/github/zephyrproject-rtos/zephyr - Git at Google

 .. _http-client-sample:

 HTTP Client
 ###########

 Overview
 ********

 This sample application shows how to create HTTP 1.1 requests to
 an HTTP server and how to parse the incoming responses.
 Supported HTTP 1.1 methods are: GET, HEAD, OPTIONS and POST.

 The source code for this sample application can be found at:
 :file:`samples/net/http_client`.

 Requirements
 ************

 - Freedom Board (FRDM-K64F)
 - LAN for testing purposes (Ethernet)
 - Terminal emulator software
 - HTTP Server

 Building and Running
 ********************

 Open the project configuration file for your platform, for example:
 :file:`prj_frdm_k64f.conf` is the configuration file for the
 :ref:`frdm_k64f` board. For IPv4 networks, set the following variables:

 .. code-block:: console

 	CONFIG_NET_IPV4=y
 	CONFIG_NET_IPV6=n

 IPv6 is the preferred routing technology for this sample application,
 if CONFIG_NET_IPV6=y is set, the value of CONFIG_NET_IPV4=y is ignored.

 In this sample application, only static IP addresses are supported,
 those addresses are specified in the project configuration file,
 for example:

 .. code-block:: console

 	CONFIG_NET_APP_MY_IPV6_ADDR="2001:db8::1"
 	CONFIG_NET_APP_PEER_IPV6_ADDR="2001:db8::2"

 are the IPv6 addresses for the HTTP client running Zephyr and the
 HTTP server, respectively.

 Alternatively, the IP addresses may be specified in the
 :file:`src/config.h` file.

 Open the :file:`src/config.h` file and set the server port
 to match the HTTP server setup, for example:

 .. code-block:: c

    #define SERVER_PORT		80

 assumes that the HTTP server is listening at the TCP port 80.

 HTTP Server
 ===========

 Setting up an HTTP server on your host computer is beyond the scope
 of this document.
 (We used `Apache 2 <http://httpd.apache.org/docs/2.4/getting-started.html>`_
 for testing this sample application.

 However, this application assumes that there is a server's
 resource that can process an HTTP 1.1 POST request.

 For example, assuming that the Apache 2 server with PHP support
 is used, and that the client sends a POST request with
 "Content-Type = application/x-www-form-urlencoded" the following
 PHP script will echo the POST payload back to the client:

 .. code-block:: html

 	<html>
 	<head>
 		<title>HTTP Server POST test</title>
 	</head>
 	<body>
 		<?php
 			echo '<p>POST key/values:</p>';
 			foreach ($_POST as $key => $value) {
 				echo "<p> {$key} : {$value} </p>";
 			}
 		?>
 	</body>
 	</html>

 In the machine hosting the HTTP server, this php script is at
 :file:`/var/www/html/post_test.php`. However, for your test machine
 this path can be different, but should be at your server's root folder.

 HTTP Responses
 ==============

 Server's responses are processed by the http_receive_cb routine
 defined inside the :file:`src/http_client_rcv.c` file.

 This sample application only prints the HTTP header fields via
 the HTTP Parser Library, see :file:`include/net/http_parser.h`.
 To process the HTTP response's body, use the HTTP Parser's callbacks
 to determine where the body begins. Depending on the payload's size,
 it may be necessary to traverse the network buffer's fragment chain.
 See the :file:`src/http_client_rcv.c` file at line 70 for sample code
 that shows how to walk the fragment chain.

 FRDM K64F
 =========

 Open a terminal window and type:

 .. code-block:: console

     $ make BOARD=frdm_k64f

 The FRDM K64F board is detected as a USB storage device. The board
 must be mounted (i.e. to /mnt) to 'flash' the binary:

 .. code-block:: console

     $ cp outdir/frdm_k64f/zephyr.bin /mnt

 On Linux, use the 'dmesg' program to find the right USB device for the
 FRDM serial console. Assuming that this device is ttyACM0, open a
 terminal window and type:

 .. code-block:: console

     $ screen /dev/ttyACM0 115200

 Once the binary is loaded into the FRDM board, press the RESET button.

 Refer to the board documentation in Zephyr, :ref:`frdm_k64f`,
 for more information about this board and how to access the FRDM
 serial console under other operating systems.

 Sample Output
 =============

 This sample application loops a specified number of times doing four
 HTTP 1.1 requests and displays the header fields that were extracted
 from the server's response. The four requests are:

 - GET "/index.html"
 - HEAD "/"
 - OPTIONS "/"
 - POST "/post_test.php"

 The terminal window where screen is running will show something similar
 to the following:

 .. code-block:: console

 	*******************************************
 	HTTP Client: 2001:db8::1
 	Connecting to: 2001:db8::2 port 80
 	Hostname: 2001:db8::2
 	HTTP Request: GET

 	--------- HTTP response (headers) ---------
 	Date: Thu, 02 Feb 2017 00:51:31 GMT
 	Server: Apache/2.4.10 (Debian)
 	Last-Modified: Sat, 28 Jan 2017 02:55:09 GMT
 	ETag: "3c-5471eb5db3c73"
 	Accept-Ranges: bytes
 	Content-Length: 60
 	Connection: close
 	Content-Type: text/html

 	HTTP server response status: OK
 	HTTP parser status: success
 	HTTP body: 60 bytes, expected: 60 bytes

 	*******************************************
 	HTTP Client: 2001:db8::1
 	Connecting to: 2001:db8::2 port 80
 	Hostname: 2001:db8::2
 	HTTP Request: HEAD

 	--------- HTTP response (headers) ---------
 	Date: Thu, 02 Feb 2017 00:51:37 GMT
 	Server: Apache/2.4.10 (Debian)
 	Last-Modified: Sat, 28 Jan 2017 02:55:09 GMT
 	ETag: "3c-5471eb5db3c73"
 	Accept-Ranges: bytes
 	Content-Length: 60
 	Connection: close
 	Content-Type: text/html

 	HTTP server response status: OK
 	HTTP parser status: success

 	*******************************************
 	HTTP Client: 2001:db8::1
 	Connecting to: 2001:db8::2 port 80
 	Hostname: 2001:db8::2
 	HTTP Request: OPTIONS

 	--------- HTTP response (headers) ---------
 	Date: Thu, 02 Feb 2017 00:51:43 GMT
 	Server: Apache/2.4.10 (Debian)
 	Allow: GET,HEAD,POST,OPTIONS
 	Content-Length: 0
 	Connection: close
 	Content-Type: text/html

 	HTTP server response status: OK
 	HTTP parser status: success

 	*******************************************
 	HTTP Client: 2001:db8::1
 	Connecting to: 2001:db8::2 port 80
 	Hostname: 2001:db8::2
 	HTTP Request: POST

 	--------- HTTP response (headers) ---------
 	Date: Thu, 02 Feb 2017 00:51:49 GMT
 	Server: Apache/2.4.10 (Debian)
 	Vary: Accept-Encoding
 	Content-Length: 231
 	Connection: close
 	Content-Type: text/html; charset=UTF-8

 	HTTP server response status: OK
 	HTTP parser status: success
	.. _http-client-sample:

	HTTP Client
	###########

	Overview
	********

	This sample application shows how to create HTTP 1.1 requests to
	an HTTP server and how to parse the incoming responses.
	Supported HTTP 1.1 methods are: GET, HEAD, OPTIONS and POST.

	The source code for this sample application can be found at:
	:file:`samples/net/http_client`.

	Requirements
	************

	- Freedom Board (FRDM-K64F)
	- LAN for testing purposes (Ethernet)
	- Terminal emulator software
	- HTTP Server

	Building and Running
	********************

	Open the project configuration file for your platform, for example:
	:file:`prj_frdm_k64f.conf` is the configuration file for the
	:ref:`frdm_k64f` board. For IPv4 networks, set the following variables:

	.. code-block:: console

	CONFIG_NET_IPV4=y
	CONFIG_NET_IPV6=n

	IPv6 is the preferred routing technology for this sample application,
	if CONFIG_NET_IPV6=y is set, the value of CONFIG_NET_IPV4=y is ignored.

	In this sample application, only static IP addresses are supported,
	those addresses are specified in the project configuration file,
	for example:

	.. code-block:: console

	CONFIG_NET_APP_MY_IPV6_ADDR="2001:db8::1"
	CONFIG_NET_APP_PEER_IPV6_ADDR="2001:db8::2"

	are the IPv6 addresses for the HTTP client running Zephyr and the
	HTTP server, respectively.

	Alternatively, the IP addresses may be specified in the
	:file:`src/config.h` file.

	Open the :file:`src/config.h` file and set the server port
	to match the HTTP server setup, for example:

	.. code-block:: c

	#define SERVER_PORT 80

	assumes that the HTTP server is listening at the TCP port 80.

	HTTP Server
	===========

	Setting up an HTTP server on your host computer is beyond the scope
	of this document.
	(We used `Apache 2 <http://httpd.apache.org/docs/2.4/getting-started.html>`_
	for testing this sample application.

	However, this application assumes that there is a server's
	resource that can process an HTTP 1.1 POST request.

	For example, assuming that the Apache 2 server with PHP support
	is used, and that the client sends a POST request with
	"Content-Type = application/x-www-form-urlencoded" the following
	PHP script will echo the POST payload back to the client:

	.. code-block:: html

	<html>
	<head>
	<title>HTTP Server POST test</title>
	</head>
	<body>
	<?php
	echo '<p>POST key/values:</p>';
	foreach ($_POST as $key => $value) {
	echo "<p> {$key} : {$value} </p>";
	}
	?>
	</body>
	</html>

	In the machine hosting the HTTP server, this php script is at
	:file:`/var/www/html/post_test.php`. However, for your test machine
	this path can be different, but should be at your server's root folder.

	HTTP Responses
	==============

	Server's responses are processed by the http_receive_cb routine
	defined inside the :file:`src/http_client_rcv.c` file.

	This sample application only prints the HTTP header fields via
	the HTTP Parser Library, see :file:`include/net/http_parser.h`.
	To process the HTTP response's body, use the HTTP Parser's callbacks
	to determine where the body begins. Depending on the payload's size,
	it may be necessary to traverse the network buffer's fragment chain.
	See the :file:`src/http_client_rcv.c` file at line 70 for sample code
	that shows how to walk the fragment chain.

	FRDM K64F
	=========

	Open a terminal window and type:

	.. code-block:: console

	$ make BOARD=frdm_k64f

	The FRDM K64F board is detected as a USB storage device. The board
	must be mounted (i.e. to /mnt) to 'flash' the binary:

	.. code-block:: console

	$ cp outdir/frdm_k64f/zephyr.bin /mnt

	On Linux, use the 'dmesg' program to find the right USB device for the
	FRDM serial console. Assuming that this device is ttyACM0, open a
	terminal window and type:

	.. code-block:: console

	$ screen /dev/ttyACM0 115200

	Once the binary is loaded into the FRDM board, press the RESET button.

	Refer to the board documentation in Zephyr, :ref:`frdm_k64f`,
	for more information about this board and how to access the FRDM
	serial console under other operating systems.

	Sample Output
	=============

	This sample application loops a specified number of times doing four
	HTTP 1.1 requests and displays the header fields that were extracted
	from the server's response. The four requests are:

	- GET "/index.html"
	- HEAD "/"
	- OPTIONS "/"
	- POST "/post_test.php"

	The terminal window where screen is running will show something similar
	to the following:

	.. code-block:: console

	*******************************************
	HTTP Client: 2001:db8::1
	Connecting to: 2001:db8::2 port 80
	Hostname: 2001:db8::2
	HTTP Request: GET

	--------- HTTP response (headers) ---------
	Date: Thu, 02 Feb 2017 00:51:31 GMT
	Server: Apache/2.4.10 (Debian)
	Last-Modified: Sat, 28 Jan 2017 02:55:09 GMT
	ETag: "3c-5471eb5db3c73"
	Accept-Ranges: bytes
	Content-Length: 60
	Connection: close
	Content-Type: text/html

	HTTP server response status: OK
	HTTP parser status: success
	HTTP body: 60 bytes, expected: 60 bytes

	*******************************************
	HTTP Client: 2001:db8::1
	Connecting to: 2001:db8::2 port 80
	Hostname: 2001:db8::2
	HTTP Request: HEAD

	--------- HTTP response (headers) ---------
	Date: Thu, 02 Feb 2017 00:51:37 GMT
	Server: Apache/2.4.10 (Debian)
	Last-Modified: Sat, 28 Jan 2017 02:55:09 GMT
	ETag: "3c-5471eb5db3c73"
	Accept-Ranges: bytes
	Content-Length: 60
	Connection: close
	Content-Type: text/html

	HTTP server response status: OK
	HTTP parser status: success

	*******************************************
	HTTP Client: 2001:db8::1
	Connecting to: 2001:db8::2 port 80
	Hostname: 2001:db8::2
	HTTP Request: OPTIONS

	--------- HTTP response (headers) ---------
	Date: Thu, 02 Feb 2017 00:51:43 GMT
	Server: Apache/2.4.10 (Debian)
	Allow: GET,HEAD,POST,OPTIONS
	Content-Length: 0
	Connection: close
	Content-Type: text/html

	HTTP server response status: OK
	HTTP parser status: success

	*******************************************
	HTTP Client: 2001:db8::1
	Connecting to: 2001:db8::2 port 80
	Hostname: 2001:db8::2
	HTTP Request: POST

	--------- HTTP response (headers) ---------
	Date: Thu, 02 Feb 2017 00:51:49 GMT
	Server: Apache/2.4.10 (Debian)
	Vary: Accept-Encoding
	Content-Length: 231
	Connection: close
	Content-Type: text/html; charset=UTF-8

	HTTP server response status: OK
	HTTP parser status: success