Long live Qt Json Stream!

10 files changed, 1240 insertions, 0 deletions

diff --git a/doc/doc.pri b/doc/doc.pri
new file mode 100644
index 0000000..bd7dd73
--- /dev/null
+++ b/doc/doc.pri
@@ -0,0 +1,7 @@
+OTHER_FILES += $$PWD/jsonstream.qdocconf
+
+docs_target.target = docs
+docs_target.commands = qdoc3 $$PWD/jsonstream.qdocconf
+
+QMAKE_EXTRA_TARGETS = docs_target
+QMAKE_CLEAN += "-r $$PWD/html"
diff --git a/doc/images/classes.png b/doc/images/classes.png
new file mode 100644
index 0000000..c31840f
--- /dev/null
+++ b/doc/images/classes.png
diff --git a/doc/images/diagrams.graffle b/doc/images/diagrams.graffle
new file mode 100644
index 0000000..c0d1714
--- /dev/null
+++ b/doc/images/diagrams.graffle
@@ -0,0 +1,560 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>ActiveLayerIndex</key>
+	<integer>0</integer>
+	<key>ApplicationVersion</key>
+	<array>
+		<string>com.omnigroup.OmniGrafflePro.MacAppStore</string>
+		<string>138.33</string>
+	</array>
+	<key>AutoAdjust</key>
+	<true/>
+	<key>BackgroundGraphic</key>
+	<dict>
+		<key>Bounds</key>
+		<string>{{0, 0}, {576, 733}}</string>
+		<key>Class</key>
+		<string>SolidGraphic</string>
+		<key>ID</key>
+		<integer>2</integer>
+		<key>Style</key>
+		<dict>
+			<key>shadow</key>
+			<dict>
+				<key>Draws</key>
+				<string>NO</string>
+			</dict>
+			<key>stroke</key>
+			<dict>
+				<key>Draws</key>
+				<string>NO</string>
+			</dict>
+		</dict>
+	</dict>
+	<key>CanvasOrigin</key>
+	<string>{0, 0}</string>
+	<key>ColumnAlign</key>
+	<integer>1</integer>
+	<key>ColumnSpacing</key>
+	<real>36</real>
+	<key>CreationDate</key>
+	<string>2011-11-08 00:16:34 +0000</string>
+	<key>Creator</key>
+	<string>andyc</string>
+	<key>DisplayScale</key>
+	<string>1 0/72 in = 1.0000 in</string>
+	<key>GraphDocumentVersion</key>
+	<integer>8</integer>
+	<key>GraphicsList</key>
+	<array>
+		<dict>
+			<key>Bounds</key>
+			<string>{{132.1111, 167.12962}, {78, 11}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FitText</key>
+			<string>YES</string>
+			<key>Flow</key>
+			<string>Resize</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>9</real>
+			</dict>
+			<key>ID</key>
+			<integer>37</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict>
+				<key>fill</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>shadow</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+				<key>stroke</key>
+				<dict>
+					<key>Draws</key>
+					<string>NO</string>
+				</dict>
+			</dict>
+			<key>Text</key>
+			<dict>
+				<key>Pad</key>
+				<integer>0</integer>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1138\cocoasubrtf230
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs18 \cf0 TCP or Unix socket}</string>
+				<key>VerticalPad</key>
+				<integer>0</integer>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>Head</key>
+			<dict>
+				<key>ID</key>
+				<integer>29</integer>
+			</dict>
+			<key>ID</key>
+			<integer>32</integer>
+			<key>Points</key>
+			<array>
+				<string>{302.33423, 103.14796}</string>
+				<string>{342.16797, 103.14796}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>FilledArrow</string>
+					<key>HeadScale</key>
+					<real>0.5</real>
+					<key>LineType</key>
+					<integer>1</integer>
+					<key>TailArrow</key>
+					<string>FilledArrow</string>
+					<key>TailScale</key>
+					<real>0.5</real>
+					<key>Width</key>
+					<real>2</real>
+				</dict>
+			</dict>
+			<key>Tail</key>
+			<dict>
+				<key>ID</key>
+				<integer>28</integer>
+			</dict>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>Head</key>
+			<dict>
+				<key>ID</key>
+				<integer>28</integer>
+			</dict>
+			<key>ID</key>
+			<integer>31</integer>
+			<key>Points</key>
+			<array>
+				<string>{265.841, 141.62962}</string>
+				<string>{265.8483, 121.64796}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>0</string>
+					<key>HeadScale</key>
+					<real>0.5</real>
+					<key>LineType</key>
+					<integer>1</integer>
+					<key>TailArrow</key>
+					<string>0</string>
+					<key>Width</key>
+					<real>2</real>
+				</dict>
+			</dict>
+			<key>Tail</key>
+			<dict>
+				<key>ID</key>
+				<integer>27</integer>
+			</dict>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>Head</key>
+			<dict>
+				<key>ID</key>
+				<integer>27</integer>
+			</dict>
+			<key>ID</key>
+			<integer>30</integer>
+			<key>Points</key>
+			<array>
+				<string>{121.11111, 160.12962}</string>
+				<string>{229.33423, 160.12962}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>0</string>
+					<key>HeadScale</key>
+					<real>0.5</real>
+					<key>LineType</key>
+					<integer>1</integer>
+					<key>Pattern</key>
+					<integer>24</integer>
+					<key>TailArrow</key>
+					<string>0</string>
+					<key>Width</key>
+					<real>2</real>
+				</dict>
+			</dict>
+			<key>Tail</key>
+			<dict>
+				<key>ID</key>
+				<integer>11</integer>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{342.66797, 85.147964}, {72, 36}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>29</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1138\cocoasubrtf230
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 JsonAuthority}</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{229.83423, 85.147964}, {72, 36}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>28</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1138\cocoasubrtf230
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 JsonServer}</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{229.83423, 142.12962}, {72, 36}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>27</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict/>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1138\cocoasubrtf230
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 JsonStream}</string>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+		<dict>
+			<key>Class</key>
+			<string>LineGraphic</string>
+			<key>Head</key>
+			<dict>
+				<key>ID</key>
+				<integer>11</integer>
+			</dict>
+			<key>ID</key>
+			<integer>25</integer>
+			<key>Points</key>
+			<array>
+				<string>{84.604065, 121.64795}</string>
+				<string>{84.596451, 141.62962}</string>
+			</array>
+			<key>Style</key>
+			<dict>
+				<key>stroke</key>
+				<dict>
+					<key>HeadArrow</key>
+					<string>0</string>
+					<key>HeadScale</key>
+					<real>0.5</real>
+					<key>LineType</key>
+					<integer>1</integer>
+					<key>TailArrow</key>
+					<string>0</string>
+					<key>Width</key>
+					<real>2</real>
+				</dict>
+			</dict>
+			<key>Tail</key>
+			<dict>
+				<key>ID</key>
+				<integer>18</integer>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{48.611111, 85.147949}, {72, 36}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>18</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1138\cocoasubrtf230
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 JsonClient}</string>
+			</dict>
+		</dict>
+		<dict>
+			<key>Bounds</key>
+			<string>{{48.611118, 142.12962}, {72, 36}}</string>
+			<key>Class</key>
+			<string>ShapedGraphic</string>
+			<key>FontInfo</key>
+			<dict>
+				<key>Font</key>
+				<string>Helvetica</string>
+				<key>Size</key>
+				<real>12</real>
+			</dict>
+			<key>ID</key>
+			<integer>11</integer>
+			<key>Shape</key>
+			<string>Rectangle</string>
+			<key>Style</key>
+			<dict/>
+			<key>Text</key>
+			<dict>
+				<key>Text</key>
+				<string>{\rtf1\ansi\ansicpg1252\cocoartf1138\cocoasubrtf230
+{\fonttbl\f0\fswiss\fcharset0 Helvetica;}
+{\colortbl;\red255\green255\blue255;}
+\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\pardirnatural\qc
+
+\f0\fs20 \cf0 JsonStream}</string>
+			</dict>
+			<key>Wrap</key>
+			<string>NO</string>
+		</dict>
+	</array>
+	<key>GridInfo</key>
+	<dict/>
+	<key>GuidesLocked</key>
+	<string>NO</string>
+	<key>GuidesVisible</key>
+	<string>YES</string>
+	<key>HPages</key>
+	<integer>1</integer>
+	<key>ImageCounter</key>
+	<integer>1</integer>
+	<key>KeepToScale</key>
+	<false/>
+	<key>Layers</key>
+	<array>
+		<dict>
+			<key>Lock</key>
+			<string>NO</string>
+			<key>Name</key>
+			<string>Layer 1</string>
+			<key>Print</key>
+			<string>YES</string>
+			<key>View</key>
+			<string>YES</string>
+		</dict>
+	</array>
+	<key>LayoutInfo</key>
+	<dict>
+		<key>Animate</key>
+		<string>NO</string>
+		<key>circoMinDist</key>
+		<real>18</real>
+		<key>circoSeparation</key>
+		<real>0.0</real>
+		<key>layoutEngine</key>
+		<string>dot</string>
+		<key>neatoSeparation</key>
+		<real>0.0</real>
+		<key>twopiSeparation</key>
+		<real>0.0</real>
+	</dict>
+	<key>LinksVisible</key>
+	<string>NO</string>
+	<key>MagnetsVisible</key>
+	<string>NO</string>
+	<key>MasterSheets</key>
+	<array/>
+	<key>ModificationDate</key>
+	<string>2011-12-07 13:39:44 +0000</string>
+	<key>Modifier</key>
+	<string>andyc</string>
+	<key>NotesVisible</key>
+	<string>NO</string>
+	<key>Orientation</key>
+	<integer>2</integer>
+	<key>OriginVisible</key>
+	<string>NO</string>
+	<key>PageBreaks</key>
+	<string>YES</string>
+	<key>PrintInfo</key>
+	<dict>
+		<key>NSBottomMargin</key>
+		<array>
+			<string>float</string>
+			<string>41</string>
+		</array>
+		<key>NSHorizonalPagination</key>
+		<array>
+			<string>int</string>
+			<string>0</string>
+		</array>
+		<key>NSLeftMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+		<key>NSPaperSize</key>
+		<array>
+			<string>coded</string>
+			<string>BAtzdHJlYW10eXBlZIHoA4QBQISEhAdOU1ZhbHVlAISECE5TT2JqZWN0AIWEASqEhAx7X05TU2l6ZT1mZn2WgWQCgRgDhg==</string>
+		</array>
+		<key>NSPrintReverseOrientation</key>
+		<array>
+			<string>int</string>
+			<string>0</string>
+		</array>
+		<key>NSRightMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+		<key>NSTopMargin</key>
+		<array>
+			<string>float</string>
+			<string>18</string>
+		</array>
+	</dict>
+	<key>PrintOnePage</key>
+	<false/>
+	<key>ReadOnly</key>
+	<string>NO</string>
+	<key>RowAlign</key>
+	<integer>1</integer>
+	<key>RowSpacing</key>
+	<real>36</real>
+	<key>SheetTitle</key>
+	<string>Canvas 1</string>
+	<key>SmartAlignmentGuidesActive</key>
+	<string>YES</string>
+	<key>SmartDistanceGuidesActive</key>
+	<string>YES</string>
+	<key>UniqueID</key>
+	<integer>1</integer>
+	<key>UseEntirePage</key>
+	<false/>
+	<key>VPages</key>
+	<integer>1</integer>
+	<key>WindowInfo</key>
+	<dict>
+		<key>CurrentSheet</key>
+		<integer>0</integer>
+		<key>ExpandedCanvases</key>
+		<array>
+			<dict>
+				<key>name</key>
+				<string>Canvas 1</string>
+			</dict>
+		</array>
+		<key>Frame</key>
+		<string>{{180, 33}, {1107, 1145}}</string>
+		<key>ListView</key>
+		<true/>
+		<key>OutlineWidth</key>
+		<integer>142</integer>
+		<key>RightSidebar</key>
+		<false/>
+		<key>ShowRuler</key>
+		<true/>
+		<key>Sidebar</key>
+		<true/>
+		<key>SidebarWidth</key>
+		<integer>120</integer>
+		<key>VisibleRegion</key>
+		<string>{{0, 0}, {449.99997, 458.33334}}</string>
+		<key>Zoom</key>
+		<real>2.1600000858306885</real>
+		<key>ZoomValues</key>
+		<array>
+			<array>
+				<string>Canvas 1</string>
+				<real>2.1600000858306885</real>
+				<real>1.0800000429153442</real>
+			</array>
+		</array>
+	</dict>
+	<key>saveQuickLookFiles</key>
+	<string>YES</string>
+</dict>
+</plist>
diff --git a/doc/jsonstream.qdocconf b/doc/jsonstream.qdocconf
new file mode 100644
index 0000000..a1746e0
--- /dev/null
+++ b/doc/jsonstream.qdocconf
@@ -0,0 +1,76 @@
+project     = JsonStream
+description = JSONStream Manager Documentation
+
+exampledirs = ../examples
+headerdirs  = ./src ../src
+imagedirs   = images
+sourcedirs  = ./src ../src
+
+Cpp.ignoretokens = \
+    QT_BEGIN_HEADER \
+    QT_END_HEADER \
+    Q_ENUMS \
+    Q_INVOKABLE \
+    QT_BEGIN_NAMESPACE_JSONSTREAM \
+    QT_END_NAMESPACE_JSONSTREAM \
+    Q_ADDON_JSONSTREAM_EXPORT
+
+# The following parameters are for creating a qhp file, the qhelpgenerator
+# program can convert the qhp file into a qch file which can be opened in
+# Qt Assistant and/or Qt Creator.
+
+# Defines the name of the project. You cannot use operators (+, =, -) in
+# the name. Properties for this project are set using a qhp.<projectname>.property
+# format.
+qhp.projects = JsonStream
+
+# Sets the name of the output qhp file.
+qhp.JsonStream.file = JsonStream.qhp
+
+# Namespace for the output file. This namespace is used to distinguish between
+# different documentation files in Creator/Assistant. The namespace ends with
+# a version being a number containing a major, minor and revision element.
+# E.g. version 1.0 becomes 100.
+qhp.JsonStream.namespace = com.nokia.jsonstream.100
+
+# Title for the package, will be the main title for the package in
+# Assistant/Creator.
+qhp.JsonStream.indexTitle = JSON Stream Reference Documentation
+
+# Extra files to add to the output which are not linked to from anywhere
+# using a qdoc \l command.
+qhp.JsonStream.extraFiles = style/style.css \
+                            index.html
+
+# Only update the name of the project for the next variables.
+qhp.JsonStream.virtualFolder = qdoc
+qhp.JsonStream.subprojects = classes
+qhp.JsonStream.subprojects.classes.title = Classes
+qhp.JsonStream.subprojects.classes.selectors = class fake:headerfile
+qhp.JsonStream.subprojects.classes.sortPages = true
+
+
+# Do NOT change the variables after this line unless you know what you are doing.
+
+outputdir = html
+outputformats = HTML
+
+examples.fileextensions = "*.cpp *.h *.js *.svg *.xml *.ui *.qml"
+examples.imageextensions = "*.png *.jpeg *.jpg *.gif *.mng"
+headers.fileextensions = "*.h *.ch *.h++ *.hh *.hpp *.hxx"
+sources.fileextensions = "*.cpp *.qdoc *.mm *.qml"
+
+HTML.nobreadcrumbs = "true"
+
+HTML.templatedir = .
+HTML.stylesheets = style.css
+
+HTML.headerstyles = "  <link rel=\"stylesheet\" type=\"text/css\" href=\"style/style.css\" />\n"
+HTML.endheader = "</head>\n"
+
+HTML.postheader = \
+  " <div class=\"header\">\n" \
+  "   <div id=\"nav-logo\">\n" \
+  "     <a href=\"index.html\">JSON Stream Reference</a>" \
+  "   </div>\n" \
+  " </div>\n"
diff --git a/doc/src/authorities.qdoc b/doc/src/authorities.qdoc
new file mode 100644
index 0000000..f749a64
--- /dev/null
+++ b/doc/src/authorities.qdoc
@@ -0,0 +1,72 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of JsonStream
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\title Authority notes
+\page authorities.html
+
+\section1 Methods of authorization
+
+There are a number of ways to authorize socket connections.  These
+techniques may be dependent on the operating system and the type
+of connection (TCP or Unix local socket).
+
+The JsonTokenAuthority is the simplest method.  It works for both
+Unix and TCP sockets.  On connection, the JsonTokenAuthority expects
+that the first message received will look like:
+\c {{ "token": MAGIC }}.  The \c{MAGIC} token should be a unique
+string that has been agreed upon.
+
+The JsonPidAuthority maintains a table of authorized process IDs.
+This technique only works for Unix local sockets. Under
+Linux, the process id of the remote end of a Unix local socket can
+be reliably determined by using the \c SO_PEERCRED socket option.
+\code
+  struct ucred cr;
+  socklen_t len = sizeof(struct ucred);
+  if (getsockopt(fd, SOL_SOCKET, SO_PEERCRED, &cr, &len) == 0) {
+    return cr.pid;
+  }
+\endcode
+This same function call gives you the UID and GID of the other
+end of the socket:
+\code
+  struct ucred {
+    pid_t pid;
+    uid_t uid;
+    gid_t gid;
+  };
+\endcode.
+Note that the socket must have the \c SO_PASSCRED option set.
+
+Under BSD systems, the (roughly) equivalent function is \c LOCAL_PEERCRED, which
+is more conveniently accessed through the \c getpeerid() function.  Unfortunately,
+this function only returns the UID and GID of the remote connection.
+On the other hand, the remote connection doesn't have to set \c SO_PASSCRED,
+which is an advantage.
+
+*/
diff --git a/doc/src/index.qdoc b/doc/src/index.qdoc
new file mode 100644
index 0000000..81f8334
--- /dev/null
+++ b/doc/src/index.qdoc
@@ -0,0 +1,92 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of JsonStream
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\title JSON Stream Reference
+\page index.html
+
+\section1 Introduction
+
+QML and Javascript programs often need a way of communicating with a
+server on the same machine or different machines.  There are many
+protocols available, but the easiest for
+Javascript-based programming languages is to use \l
+{http://www.json.org} {JSON} data-interchange format.
+The JSON Stream classes implement a client/server framework.
+
+\bold{Discussion and examples}
+\list
+ \o \l{Stream serialization}
+ \o \l{Using JSON stream classes}
+ \o \l{Authority notes}
+\endlist
+
+The JSON Stream classes depend on the Qt Json experimental JSON module.
+This module may be found at http://codreview.qt-project.org under "playground/qtbinaryjson".
+After you download and compile this module, it may be used in any Qt project by adding a
+\code
+QT += json
+\endcode
+line to your .pro file.
+
+\section1 Interfaces
+
+Conceptually, the JSON Stream classes are divided into a generic client (JsonClient),
+a generic server (JsonServer), a stream transport shared by the client and the server (JsonStream),
+and an optional authentication agent (JsonAuthority) which can be installed on the server.
+Each connection to the JsonServer is given a unique \i{identifier} so that the different
+connections can be disambiguated.
+
+\image classes.png
+
+When a new socket connection is opened to the server, the authentication agent "absorbs" all
+communication over that socket until the connection has been properly authenticated.
+The authentication agent is also responsible for setting the \i{identifier} of the connection.
+For example, an authentication agent that matches the process ID (PID) of the connecting
+client to an appropriate user and permission writes may set the \i{identifier} of the
+connection to the Unix name of the UID of the connecting process.
+
+\section2 C++ API
+
+\generatelist annotatedclasses
+
+*/
+
+/*!
+  \page classes.html
+  \title All Classes
+
+  \brief If you know the name of the class, it should be here
+
+  This is a list of all of the classes provided by JSON Stream Manager.
+
+  \generatelist classes
+
+
+    \generatelist{namespaces}
+
+*/
diff --git a/doc/src/jsonstreamnamespace.qdoc b/doc/src/jsonstreamnamespace.qdoc
new file mode 100644
index 0000000..50a382d
--- /dev/null
+++ b/doc/src/jsonstreamnamespace.qdoc
@@ -0,0 +1,59 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the QtAddOn.JsonStream module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** GNU Lesser General Public License Usage
+** This file may be used under the terms of the GNU Lesser General Public
+** License version 2.1 as published by the Free Software Foundation and
+** appearing in the file LICENSE.LGPL included in the packaging of this
+** file. Please review the following information to ensure the GNU Lesser
+** General Public License version 2.1 requirements will be met:
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU General
+** Public License version 3.0 as published by the Free Software Foundation
+** and appearing in the file LICENSE.GPL included in the packaging of this
+** file. Please review the following information to ensure the GNU General
+** Public License version 3.0 requirements will be met:
+** http://www.gnu.org/copyleft/gpl.html.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms and
+** conditions contained in a signed written agreement between you and Nokia.
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+\*!
+    \namespace JsonStream
+    \brief The JsonStream namespace contains miscellaneous identifiers
+     used throughout the JsonStream library.
+*/
+
+/*!
+  \enum EncodingFormat
+
+  This enum is used to control the serialization format of the data stream.
+  All data streams start as \c JsonStream::FormatUndefined.  Once a data message is received,
+  the stream automatically switches to the format of the received message.
+
+  \value FormatUndefined    No messages have been sent or received yet.
+  \value FormatUTF8         UTF-8
+  \value FormatBSON         BSON binary format
+  \value FormatQBJS         Qt Binary Json
+*/
diff --git a/doc/src/serialization.qdoc b/doc/src/serialization.qdoc
new file mode 100644
index 0000000..eefd41a
--- /dev/null
+++ b/doc/src/serialization.qdoc
@@ -0,0 +1,118 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of JsonStream
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\title JSON Stream Serialization
+\target serialization
+\page serialization.html
+
+\section1 Stream serialization
+
+One key challenge with JSON is that there are a number of different
+ways that JSON can be serialized to be sent over a socket connection:
+\list
+ \o UTF-8 encoded (the default)
+ \o UTF-16 LE or BE
+ \o UTF-32 LE or BE
+ \o \l {http://bsonspec.org} {BSON} (Binary JSON)
+ \o \l Qt Json [ssh://codereview.qt-project.org:29418/playground/qtbinaryjson.git]
+\endlist
+For a discussion of the UTF encoding formats, see \l
+{http://www.ietf.org/rfc/rfc4627} {RFC4627}.
+
+The JSON stream reference supports all standard encoding formats by
+\bold{auto-detection}.  The server class assumes that communication
+will be initiated by the client. The initial bytes received are
+matched to the signature of one of the serialization techniques and
+the connection is set to that format.
+
+To be specific, the server matches (table data from \l
+{http://www.ietf.org/rfc/rfc4627} {RFC4627}):
+\table
+\header
+  \o Encoding
+  \o Bytes
+  \o Discussion
+\row
+  \o UTF-8
+  \o 7B xx yy zz
+  \o First byte should be the '{' character, followed by whitespace
+     and a '"' quotation mark.
+\row
+  \o BSON
+  \o 62 73 6F 6E
+  \o First four bytes are 'bson'.  Strictly speaking, this is
+     not the true BSON format (which starts with an int32 length)
+     but in the interests of autodetection we've enforced this
+     requirement.  The BSON packet follows.
+\row
+  \o QBJS
+  \o 71 62 6A 73
+  \o First four bytes are 'qbjs'.  This matches the standard
+     QtJson::JsonDocument header.
+\row
+  \o UTF-32BE
+  \o 00 00 00 7B
+  \o First four bytes should be the '{' character
+\row
+  \o UTF-32LE
+  \o 7B 00 00 00
+  \o First four bytes should be the '{' character.
+\row
+  \o Raw UTF-16BE
+  \o 00 7B 00 xx
+  \o First two bytes should be the '{' character.
+\row
+  \o Raw UTF-16LE
+  \o 7B 00 xx 00
+  \o First two bytes should be the '{' character.
+\row
+  \o UTF-16BE with BOM
+  \o FE FF 00 7B
+  \o U+FEFF + '{'
+\row
+  \o UTF-16LE with BOM
+  \o FF FE 7B 00
+  \o U+FEFF + '{'
+\endtable
+
+Clearly, there is a danger that the BSON encoding format could be
+confused with UTF-32LE, UTF-16BE, UTF-16LE, or even UTF-8 (for
+example, "7B 20 7D 00" which is '{ }'). To avoid confusion, it is
+recommended that UTF-16 encodings send a BOM (U+FEFF) character to
+start their stream.  When in doubt, the protcol will select UTF
+encoding formats before BSON, which means that UTF-32LE is
+particularly susceptable to being done incorrectly.
+
+\warning We probably will disallow UTF-32 encoding formats to resolve
+         ambiguity.  Or, we may require a BSON header to be
+         transmitted to avoid confusion.
+
+Packet sizes are limited by this protocol.  If too large of a packet
+is received (typically 65535 bytes), the connection will be dropped.
+
+*/
diff --git a/doc/src/using.qdoc b/doc/src/using.qdoc
new file mode 100644
index 0000000..3844bb2
--- /dev/null
+++ b/doc/src/using.qdoc
@@ -0,0 +1,110 @@
+/****************************************************************************
+**
+** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of JsonStream
+**
+** $QT_BEGIN_LICENSE:FDL$
+** GNU Free Documentation License
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file.
+**
+** Other Usage
+** Alternatively, this file may be used in accordance with the terms
+** and conditions contained in a signed written agreement between you
+** and Nokia.
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+\title Using JSON stream classes
+\target using
+\page using.html
+
+\section1 Using the JSON Stream Manager
+
+The JSON Stream classes don't enforce a particular message protocol;
+instead, they provide the base classes for implementing your own
+client/server protocol using JSON serialization. In this section we
+describe how you can use the classes to implement your own protocol.
+
+First, an example of a simple server.  This server uses no authentication
+protocol.
+
+\code
+  #include <JsonServer>
+
+  void start()
+  {
+    QString socket = qgetenv("JSON_SOCKET");
+    if (socket.isEmpty())
+       socket = "/tmp/jsonsocket";
+    JsonServer *server = new JsonServer;
+    connect(server, SIGNAL(connectionAdded(const QString&)),  ...);
+    connect(server, SIGNAL(messageReceived(const QString&, const QJsonObject&)),  ... );
+    if (!server->listen(socket))
+      qCritical() << Q_FUNC_INFO << "Unable to open socket" << socket;
+  }
+\endcode
+
+Next, a client that connects to that server:
+
+\code
+  #include <JsonClient>
+
+  void start()
+  {
+    JsonClient *client = new JsonClient();
+    connect(client, SIGNAL(messageReceived(const QJsonObject&)), ...);
+
+    QString socketname = qgetenv("JSON_SOCKET");
+    if (socketname.isEmpty())
+      socketname = "/tmp/jsonsocket";
+
+    if (!client->connectLocal(socketname))
+      qCritical() << Q_FUNC_INFO << "Unable to open socket " << socketname;
+  }
+\endcode
+
+\section2 Authentication
+
+
+If we want to add an authentication agent to the server, we only need to add
+an appropriate JsonAuthority subclass to the server.  For example, to
+authenticate clients based on strings tokens, we can modify
+the server code as follows:
+
+\code
+  JsonAuthority *authority = new JsonTokenAuthority;
+  JsonServer *server = new JsonServer(authority);
+
+  // Before clients attempt to connect, set authorization:
+  authority->authorize("XXXYYYZZZ", "valid-client");
+\endcode
+
+The client code needs to add an authorization token:
+
+\code
+  JsonClient *client = new JsonClient("XXXYYYZZZ");
+\endcode
+
+In many cases, this authorization token will be passed to the client
+when the client application is started.  For example, the client token
+could be passed as an environment variable \c {JSONTOKEN}.  Then the
+client can be written as:
+
+\code
+  QString token = qgetenv("JSONTOKEN");
+  JsonClient *client = new JsonClient(token);
+\endcode
+
+*/
diff --git a/doc/style.css b/doc/style.css
new file mode 100644
index 0000000..24b0e0e
--- /dev/null
+++ b/doc/style.css
@@ -0,0 +1,146 @@
+a:link, a:visited {
+    color: #00732F;
+    text-decoration: none;
+    font-weight: bold;
+}
+
+body {
+    font: normal 400 14px/1.2 Arial;
+#    margin-top: 85px;
+}
+
+h1 {
+    margin: 0;
+}
+
+h2 {
+    font: 500 20px/1.2 Arial;
+}
+
+h3.fn, span.fn {
+    -moz-border-radius: 7px 7px 7px 7px;
+    -webkit-border-radius: 7px 7px 7px 7px;
+    border-radius: 7px 7px 7px 7px;
+    background-color: #F6F6F6;
+    border-width: 1px;
+    border-style: solid;
+    border-color: #E6E6E6;
+    word-spacing: 3px;
+    padding: 3px 5px;
+}
+
+table, pre {
+    -moz-border-radius: 7px 7px 7px 7px;
+    -webkit-border-radius: 7px 7px 7px 7px;
+    border-radius: 7px 7px 7px 7px;
+    background-color: #F6F6F6;
+    border: 1px solid #E6E6E6;
+    border-collapse: separate;
+    font-size: 12px;
+    line-height: 1.2;
+    margin-bottom: 25px;
+    margin-left: 15px;
+}
+
+table td {
+    padding: 3px 15px 3px 20px;
+}
+
+table tr.even {
+    background-color: white;
+    color: #66666E;
+}
+
+table tr.odd {
+    background-color: #F6F6F6;
+    color: #66666E;
+}
+
+li {
+    margin-bottom: 10px;
+    padding-left: 12px;
+}
+
+.cpp {
+    display: block;
+    margin: 10;
+    overflow: hidden;
+    overflow-x: hidden;
+    overflow-y: hidden;
+    padding: 20px 0 20px 0;
+}
+
+.footer {
+    margin-top: 50px;
+}
+
+.memItemLeft {
+    padding-right: 3px;
+}
+
+.memItemRight {
+    padding: 3px 15px 3px 0;
+}
+
+.qml {
+    display: block;
+    margin: 10;
+    overflow: hidden;
+    overflow-x: hidden;
+    overflow-y: hidden;
+    padding: 20px 0 20px 0;
+}
+
+.qmldefault {
+    padding-left: 5px;
+    float: right;
+    color: red;
+}
+
+.qmlreadonly {
+    padding-left: 5px;
+    float: right;
+    color: #254117;
+}
+
+.rightAlign {
+    padding: 3px 5px 3px 10px;
+    text-align: right;
+}
+
+.header {
+    background-color: #F6F6F6;
+    border: 1px solid #DDD;
+    padding: 5px 5px;
+    margin: 5px 5px;
+    -moz-border-radius: 7px 7px 7px 7px;
+    -webkit-border-radius: 7px 7px 7px 7px;
+}
+
+.title {
+    background-color: white;
+    color: #44A51C;
+    font-family: Verdana;
+    font-size: 35px;
+    font-weight: normal;
+    left: 0;
+    padding-bottom: 5px;
+    padding-left: 16px;
+    padding-top: 5px;
+#    position: absolute;
+    right: 0;
+    top: 0;
+}
+
+.toc {
+    float: right;
+    -moz-border-radius: 7px 7px 7px 7px;
+    -webkit-border-radius: 7px 7px 7px 7px;
+    border-radius: 7px 7px 7px 7px;
+    background-color: #F6F6F6;
+    border: 1px solid #DDD;
+    margin: 0 20px 10px 10px;
+    padding: 20px 15px 20px 20px;
+    height: auto;
+    width: 200px;
+}