1.1 --- a/BLIP/BLIP Overview.txt Sat May 24 21:26:09 2008 -0700
1.2 +++ b/BLIP/BLIP Overview.txt Sun May 25 10:28:26 2008 -0700
1.3 @@ -22,7 +22,7 @@
1.4
1.5 All multi-byte numbers are encoded in network byte-order (big-endian).
1.6
1.7 -Each message is packed into a series of bytes consisting of the properties followed by the body. The properties are encoded as a 16-bit byte-count followed by a series of NUL-terminated C strings alternating keys and values.
1.8 +Each message is first packed into a series of bytes consisting of the properties followed by the body. The properties are encoded as a 16-bit byte-count followed by a series of NUL-terminated C strings alternating keys and values.
1.9
1.10 The message is then broken up into "frames", usually 4k to 12k bytes. Each frame is prefixed with a 12-byte header containing its length in bytes, message number, and some flags.
1.11
2.1 --- a/BLIP/Demo/BLIPEchoClient.h Sat May 24 21:26:09 2008 -0700
2.2 +++ b/BLIP/Demo/BLIPEchoClient.h Sun May 25 10:28:26 2008 -0700
2.3 @@ -4,7 +4,8 @@
2.4 //
2.5 // Created by Jens Alfke on 5/24/08.
2.6 // Copyright 2008 Jens Alfke. All rights reserved.
2.7 -// Adapted from Apple sample code "CocoaEcho".
2.8 +// Adapted from Apple sample code "CocoaEcho":
2.9 +// http://developer.apple.com/samplecode/CocoaEcho/index.html
2.10 //
2.11
2.12 #import <Cocoa/Cocoa.h>
3.1 --- a/BLIP/Demo/BLIPEchoClient.m Sat May 24 21:26:09 2008 -0700
3.2 +++ b/BLIP/Demo/BLIPEchoClient.m Sun May 25 10:28:26 2008 -0700
3.3 @@ -4,7 +4,8 @@
3.4 //
3.5 // Created by Jens Alfke on 5/24/08.
3.6 // Copyright 2008 Jens Alfke. All rights reserved.
3.7 -// Adapted from Apple sample code "CocoaEcho".
3.8 +// Adapted from Apple sample code "CocoaEcho":
3.9 +// http://developer.apple.com/samplecode/CocoaEcho/index.html
3.10 //
3.11
3.12 #import "BLIPEchoClient.h"
3.13 @@ -29,12 +30,14 @@
3.14 #pragma mark -
3.15 #pragma mark BLIPConnection support
3.16
3.17 +/* Opens a BLIP connection to the given address. */
3.18 - (void)openConnection: (IPAddress*)address
3.19 {
3.20 _connection = [[BLIPConnection alloc] initToAddress: address];
3.21 [_connection open];
3.22 }
3.23
3.24 +/* Closes the currently open BLIP connection. */
3.25 - (void)closeConnection
3.26 {
3.27 [_connection close];
3.28 @@ -66,6 +69,7 @@
3.29 #pragma mark -
3.30 #pragma mark NSNetService delegate methods
3.31
3.32 +/* Stop any current Bonjour address resolution */
3.33 - (void)stopResolving
3.34 {
3.35 if( _resolvingService ) {
3.36 @@ -76,6 +80,7 @@
3.37 }
3.38 }
3.39
3.40 +/* Ask Bonjour to resolve (look up) the IP address of the given service. */
3.41 - (void)startResolving: (NSNetService*)service
3.42 {
3.43 [self stopResolving];
3.44 @@ -85,9 +90,11 @@
3.45
3.46 }
3.47
3.48 +/* NSNetService delegate method that will be called when address resolution finishes. */
3.49 - (void)netServiceDidResolveAddress:(NSNetService *)sender
3.50 {
3.51 if( sender == _resolvingService ) {
3.52 + // Get the first address, which is an NSData containing a struct sockaddr:
3.53 NSArray *addresses = _resolvingService.addresses;
3.54 if( addresses.count > 0 ) {
3.55 NSData *addressData = [addresses objectAtIndex: 0];
3.56 @@ -114,6 +121,7 @@
3.57 }
3.58 }
3.59
3.60 +/* Send a BLIP request containing the string in the textfield */
3.61 - (IBAction)sendText:(id)sender
3.62 {
3.63 BLIPRequest *r = [_connection requestWithBody: nil];
3.64 @@ -122,6 +130,7 @@
3.65 response.onComplete = $target(self,gotResponse:);
3.66 }
3.67
3.68 +/* Receive the response to the BLIP request, and put its contents into the response field */
3.69 - (void) gotResponse: (BLIPResponse*)response
3.70 {
3.71 [responseField setObjectValue: response.bodyString];
4.1 --- a/maindocs.h Sat May 24 21:26:09 2008 -0700
4.2 +++ b/maindocs.h Sun May 25 10:28:26 2008 -0700
4.3 @@ -10,7 +10,7 @@
4.4
4.5 /*! \mainpage MYNetwork: Mooseyard Networking library, including BLIP protocol implementation.
4.6
4.7 - \section intro_sec Introduction
4.8 +\section intro_sec Introduction
4.9
4.10 MYNetwork is a set of Objective-C networking classes for Cocoa applications on Mac OS X.
4.11 It consists of:
4.12 @@ -24,8 +24,49 @@
4.13
4.14 MYNetwork is released under a BSD license, which means you can freely use it in open-source
4.15 or commercial projects, provided you give credit in your documentation or About box.
4.16 +
4.17 +\section blipdesc What's BLIP?
4.18
4.19 - \section config Configuration
4.20 +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.
4.21 +
4.22 +BLIP was inspired by <a
4.23 +href="http://beepcore.org">BEEP</a> (in fact BLIP stands for "BEEP-LIke Protocol") but is
4.24 +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.
4.25 +
4.26 +\subsection blipfeatures BLIP Features:
4.27 +
4.28 + <ul>
4.29 + <li>Each message is very much like a MIME body, as in email or HTTP: it consists of a
4.30 +blob of data of arbitrary length, plus a set of key/value pairs called "properties". The
4.31 +properties are mostly ignored by BLIP itself, but clients can use them for metadata about the
4.32 +body, and for delivery information (i.e. something like BEEP's "profiles".)
4.33 +
4.34 +<li>Either peer can send a request at any time; there's no notion of "client" and "server" roles.
4.35 +
4.36 +<li> Multiple messages can be transmitted simultaneously in the same direction over the same connection, so a very long
4.37 +message does not block any other messages from being delivered. This means that message ordering
4.38 +is a bit looser than in BEEP or HTTP 1.1: the receiver will see the beginnings of messages in the
4.39 +same order in which the sender posted them, but they might not <i>end</i> in that same order. (For
4.40 +example, a long message will take longer to be delivered, so it may finish after messages that
4.41 +were begun after it.)
4.42 +
4.43 +<li>The sender can indicate whether or not a message needs to be replied to; the response is tagged with the
4.44 +identity of the original message, to make it easy for the sender to recognize. This makes it
4.45 +straighforward to implement RPC-style (or REST-style) interactions. (Responses
4.46 +cannot be replied to again, however.)
4.47 +
4.48 +<li>A message can be flagged as "urgent". Urgent messages are pushed ahead in the outgoing queue and
4.49 +get a higher fraction of the available bandwidth.
4.50 +
4.51 +<li>A message can be flagged as "compressed". This runs its body through the gzip algorithm, ideally
4.52 +making it faster to transmit. (Common markup-based data formats like XML and JSON compress
4.53 +extremely well, at ratios up to 10::1.) The message is decompressed on the receiving end,
4.54 +invisibly to client code.
4.55 +
4.56 +<li>The implementation supports SSL connections (with optional client-side certificates), and Bonjour service advertising.
4.57 +</ul>
4.58 +
4.59 +\section config Configuration
4.60
4.61 MYNetwork requires Mac OS X 10.5 or later, since it uses Objective-C 2 features like
4.62 properties and for...in loops.
4.63 @@ -35,19 +76,26 @@
4.64 which contains the minimal set of MYUtilities files needed to build MYUtilities. (That project
4.65 has its search paths set up to assume that MYUtilities is in a directory next to MYNetwork.)
4.66
4.67 - \section download How To Get It
4.68 +\section download How To Get It
4.69
4.70 <ul>
4.71 - <li><a href="http://mooseyard.com/hg/hgwebdir.cgi/MYNetwork/archive/tip.zip">Download the current source code</a>
4.72 + <li><a href="/hg/hgwebdir.cgi/MYNetwork/archive/tip.zip">Download the current source code</a>
4.73 <li>To check out the source code using <a href="http://selenic.com/mercurial">Mercurial</a>:
4.74 - \verbatim hg clone http://mooseyard.com/hg/hgwebdir.cgi/MYNetwork/ MYNetwork \endverbatim
4.75 + \verbatim hg clone /hg/hgwebdir.cgi/MYNetwork/ MYNetwork \endverbatim
4.76 + <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
4.77 + a directory next to MYNetwork.
4.78 </ul>
4.79
4.80 Or if you're just looking:
4.81
4.82 <ul>
4.83 - <li><a href="http://mooseyard.com/hg/hgwebdir.cgi/MYNetwork/file/tip">Browse the source code</a>
4.84 + <li><a href="/hg/hgwebdir.cgi/MYNetwork/file/tip">Browse the source code</a>
4.85 <li><a href="annotated.html">Browse the class documentation</a>
4.86 </ul>
4.87
4.88 + There isn't any conceptual documentation yet, beyond what's in the API docs, but you can
4.89 + <a href="/hg/hgwebdir.cgi/MYNetwork/file/tip/BLIP/Demo/">look
4.90 + at the sample BLIPEcho client and server</a>, which are based on Apple's
4.91 + <a href="http://developer.apple.com/samplecode/CocoaEcho/index.html">CocoaEcho</a> sample code.
4.92 +
4.93 */