jens@2: //
jens@2: //  maindocs.h
jens@2: //  MYNetwork
jens@2: //
jens@2: //  Created by Jens Alfke on 5/24/08.
jens@2: //  Copyright 2008 Jens Alfke. All rights reserved.
jens@2: //
jens@2: // This file just contains the Doxygen comments that generate the main (index.html) page content.
jens@2: 
jens@2: 
jens@2: /*! \mainpage MYNetwork: Mooseyard Networking library, including BLIP protocol implementation. 
jens@2:  
jens@4: \section intro_sec Introduction
jens@2:  
jens@2:     MYNetwork is a set of Objective-C networking classes for Cocoa applications on Mac OS X.
jens@2:     It consists of:
jens@2:     <ul>
jens@2:     <li>Networking utility classes (presently only IPAddress);
jens@2:     <li>A generic TCP client/server implementation,
jens@2:         useful for implementing your own network protocols; (see TCPListener and TCPConnection)
jens@2:     <li>An implementation of BLIP, a lightweight network protocol I've invented as an easy way
jens@2:         to send request and response messages between peers. (see BLIPListener, BLIPConnection, BLIPRequest, etc.)
jens@2:     </ul>
jens@2:  
jens@2:     MYNetwork is released under a BSD license, which means you can freely use it in open-source
jens@2:     or commercial projects, provided you give credit in your documentation or About box.
jens@4: 
jens@4: \section blipdesc What's BLIP?
jens@2:  
jens@4: 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. 
jens@4:  
jens@4: BLIP was inspired by <a
jens@4: href="http://beepcore.org">BEEP</a> (in fact BLIP stands for "BEEP-LIke Protocol") but is
jens@4: 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.
jens@4:  
jens@4: \subsection blipfeatures BLIP Features:
jens@4: 
jens@4:  <ul>
jens@4:  <li>Each message is very much like a MIME body, as in email or HTTP: it consists of a
jens@4: blob of data of arbitrary length, plus a set of key/value pairs called "properties". The
jens@4: properties are mostly ignored by BLIP itself, but clients can use them for metadata about the
jens@4: body, and for delivery information (i.e. something like BEEP's "profiles".)
jens@4: 
jens@4: <li>Either peer can send a request at any time; there's no notion of "client" and "server" roles.
jens@4:  
jens@4: <li> Multiple messages can be transmitted simultaneously in the same direction over the same connection, so a very long
jens@4: message does not block any other messages from being delivered. This means that message ordering
jens@4: is a bit looser than in BEEP or HTTP 1.1: the receiver will see the beginnings of messages in the
jens@4: same order in which the sender posted them, but they might not <i>end</i> in that same order. (For
jens@4: example, a long message will take longer to be delivered, so it may finish after messages that
jens@4: were begun after it.)
jens@4: 
jens@4: <li>The sender can indicate whether or not a message needs to be replied to; the response is tagged with the
jens@4: identity of the original message, to make it easy for the sender to recognize. This makes it
jens@4: straighforward to implement RPC-style (or REST-style) interactions. (Responses
jens@4: cannot be replied to again, however.)
jens@4: 
jens@4: <li>A message can be flagged as "urgent". Urgent messages are pushed ahead in the outgoing queue and
jens@4: get a higher fraction of the available bandwidth.
jens@4: 
jens@4: <li>A message can be flagged as "compressed". This runs its body through the gzip algorithm, ideally
jens@4: making it faster to transmit. (Common markup-based data formats like XML and JSON compress
jens@4: extremely well, at ratios up to 10::1.) The message is decompressed on the receiving end,
jens@4: invisibly to client code.
jens@4:  
jens@4: <li>The implementation supports SSL connections (with optional client-side certificates), and Bonjour service advertising.
jens@4: </ul>
jens@4:  
jens@4: \section config Configuration
jens@2:  
jens@2:     MYNetwork requires Mac OS X 10.5 or later, since it uses Objective-C 2 features like
jens@2:     properties and for...in loops.
jens@2:  
jens@2:     MYNetwork uses my <a href="/hg/hgwebdir.cgi/MYUtilities">MYUtilities</a> library. You'll need to have downloaded that library, and added
jens@2:     the necessary source files and headers to your project. See the MYNetwork Xcode project,
jens@2:     which contains the minimal set of MYUtilities files needed to build MYUtilities. (That project
jens@2:     has its search paths set up to assume that MYUtilities is in a directory next to MYNetwork.)
jens@2: 
jens@4: \section download How To Get It
jens@2: 
jens@2:     <ul>
jens@4:     <li><a href="/hg/hgwebdir.cgi/MYNetwork/archive/tip.zip">Download the current source code</a>
jens@2:     <li>To check out the source code using <a href="http://selenic.com/mercurial">Mercurial</a>:
jens@4:     \verbatim hg clone /hg/hgwebdir.cgi/MYNetwork/ MYNetwork \endverbatim
jens@4:     <li>As described above, you'll also need to download or check out <a href="/hg/hgwebdir.cgi/MYUtilities">MYUtilities</a> and put it in 
jens@4:     a directory next to MYNetwork.
jens@2:     </ul>
jens@2: 
jens@2:     Or if you're just looking:
jens@2: 
jens@2:     <ul>
jens@4:     <li><a href="/hg/hgwebdir.cgi/MYNetwork/file/tip">Browse the source code</a>
jens@2:     <li><a href="annotated.html">Browse the class documentation</a>
jens@2:     </ul>
jens@2:  
jens@4:     There isn't any conceptual documentation yet, beyond what's in the API docs, but you can 
jens@4:     <a href="/hg/hgwebdir.cgi/MYNetwork/file/tip/BLIP/Demo/">look
jens@4:     at the sample BLIPEcho client and server</a>, which are based on Apple's 
jens@4:     <a href="http://developer.apple.com/samplecode/CocoaEcho/index.html">CocoaEcho</a> sample code.
jens@4:  
jens@2:  */