diff -r 9fdd8dba529c -r 2bd9d60a2c46 maindocs.h
--- a/maindocs.h Sat May 24 17:25:06 2008 -0700
+++ b/maindocs.h Sun May 25 10:28:26 2008 -0700
@@ -10,7 +10,7 @@
/*! \mainpage MYNetwork: Mooseyard Networking library, including BLIP protocol implementation.
- \section intro_sec Introduction
+\section intro_sec Introduction
MYNetwork is a set of Objective-C networking classes for Cocoa applications on Mac OS X.
It consists of:
@@ -24,8 +24,49 @@
MYNetwork is released under a BSD license, which means you can freely use it in open-source
or commercial projects, provided you give credit in your documentation or About box.
+
+\section blipdesc What's BLIP?
- \section config Configuration
+BLIP is a message-oriented network protocol that lets the two peers on either end of a TCP socket send request and response messages to each other. It's a generic protocol, in that the requests and responses can contain any kind of data you like.
+
+BLIP was inspired by BEEP (in fact BLIP stands for "BEEP-LIke Protocol") but is
+deliberately simpler and somewhat more limited. That translates to a smaller and cleaner implemenation, especially since it takes advantage of Cocoa's and CFNetwork's existing support for network streams, SSL and Bonjour.
+
+\subsection blipfeatures BLIP Features:
+
+
+ - Each message is very much like a MIME body, as in email or HTTP: it consists of a
+blob of data of arbitrary length, plus a set of key/value pairs called "properties". The
+properties are mostly ignored by BLIP itself, but clients can use them for metadata about the
+body, and for delivery information (i.e. something like BEEP's "profiles".)
+
+
- Either peer can send a request at any time; there's no notion of "client" and "server" roles.
+
+
- Multiple messages can be transmitted simultaneously in the same direction over the same connection, so a very long
+message does not block any other messages from being delivered. This means that message ordering
+is a bit looser than in BEEP or HTTP 1.1: the receiver will see the beginnings of messages in the
+same order in which the sender posted them, but they might not end in that same order. (For
+example, a long message will take longer to be delivered, so it may finish after messages that
+were begun after it.)
+
+
- The sender can indicate whether or not a message needs to be replied to; the response is tagged with the
+identity of the original message, to make it easy for the sender to recognize. This makes it
+straighforward to implement RPC-style (or REST-style) interactions. (Responses
+cannot be replied to again, however.)
+
+
- A message can be flagged as "urgent". Urgent messages are pushed ahead in the outgoing queue and
+get a higher fraction of the available bandwidth.
+
+
- A message can be flagged as "compressed". This runs its body through the gzip algorithm, ideally
+making it faster to transmit. (Common markup-based data formats like XML and JSON compress
+extremely well, at ratios up to 10::1.) The message is decompressed on the receiving end,
+invisibly to client code.
+
+
- The implementation supports SSL connections (with optional client-side certificates), and Bonjour service advertising.
+
+
+\section config Configuration
MYNetwork requires Mac OS X 10.5 or later, since it uses Objective-C 2 features like
properties and for...in loops.
@@ -35,19 +76,26 @@
which contains the minimal set of MYUtilities files needed to build MYUtilities. (That project
has its search paths set up to assume that MYUtilities is in a directory next to MYNetwork.)
- \section download How To Get It
+\section download How To Get It
Or if you're just looking:
+ There isn't any conceptual documentation yet, beyond what's in the API docs, but you can
+ look
+ at the sample BLIPEcho client and server, which are based on Apple's
+ CocoaEcho sample code.
+
*/