From f9188841b02b90fbba493c803f17be082d47f4d1 Mon Sep 17 00:00:00 2001
From: Sebastien Pierre <sebastien.pierre@gmail.com>
Date: Wed, 4 Sep 2013 14:58:07 -0400
Subject: [PATCH] Clarified zmq_socket.txt ZMQ_STREAM section, added example

---
 doc/zmq_socket.txt | 45 +++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 43 insertions(+), 2 deletions(-)

diff --git a/doc/zmq_socket.txt b/doc/zmq_socket.txt
index cd0d3c6c..a18ddd73 100644
--- a/doc/zmq_socket.txt
+++ b/doc/zmq_socket.txt
@@ -347,12 +347,15 @@ routed to, and unroutable messages shall cause an EHOSTUNREACH or EAGAIN error.
 To open a connection to a server, use the zmq_connect call, and then fetch the 
 socket identity using the ZMQ_IDENTITY zmq_getsockopt call.
 
-To close a specific client connection, as a server, send a zero-length message 
-following the identity frame.
+To close a specific client connection, as a server, send the identity frame
+followed by a zero-length message (see EXAMPLE section).
 
 The ZMQ_MSGMORE flag is ignored on data frames. You must send one identity frame
 followed by one data frame.
 
+Also, please note that omitting the ZMQ_MSGMORE flag will prevent sending further
+data (from any client) on the same socket.
+
 [horizontal]
 .Summary of ZMQ_STREAM characteristics
 Compatible peer sockets:: none.
@@ -381,6 +384,44 @@ The limit on the total number of open 0MQ sockets has been reached.
 *ETERM*::
 The context specified was terminated.
 
+EXAMPLE
+-------
+.Creating a simple HTTP server using ZMQ_STREAM
+----
+void *ctx = zmq_ctx_new ();
+assert (ctx);
+/* Create ZMQ_STREAM socket */
+void *socket = zmq_socket (ctx, ZMQ_STREAM);
+assert (socket);
+int rc = zmq_bind (socket, "tcp://*:8080");
+assert (rc == 0);
+/* Data structure to hold the ZMQ_STREAM ID */
+uint8_t id [256];
+size_t id_size = 256;
+while (1) {
+	/*  Get HTTP request; ID frame and then request */
+	id_size = zmq_recv (server, id, 256, 0);
+	assert (id_size > 0);
+	/* Prepares the response */
+	char http_response [] =
+		"HTTP/1.0 200 OK\r\n"
+		"Content-Type: text/plain\r\n"
+		"\r\n"
+		"Hello, World!";
+	/* Sends the ID frame followed by the response */
+	zmq_send (socket, id, id_size, ZMQ_SNDMORE);
+	zmq_send (socket, http_response, strlen (http_response), ZMQ_SNDMORE);
+	/* Closes the connection by sending the ID frame followed by a zero response */
+	zmq_send (socket, id, id_size, ZMQ_SNDMORE);
+	zmq_send (socket, 0, 0, ZMQ_SNDMORE);
+	/* NOTE: If we don't use ZMQ_SNDMORE, then we won't be able to send more */
+	/* message to any client */
+}
+zmq_close (socket);
+zmq_ctx_destroy (ctx);
+----
+
+
 SEE ALSO
 --------
 linkzmq:zmq_init[3]