# HG changeset patch # User Jens Alfke # Date 1211736506 25200 # Node ID 2bd9d60a2c46661e2356f76065790f724cd9e948 # Parent 76f302097a758d810113f4c41f801d7857133094 More documentation. diff -r 76f302097a75 -r 2bd9d60a2c46 BLIP/BLIP Overview.txt --- a/BLIP/BLIP Overview.txt Sat May 24 21:26:09 2008 -0700 +++ b/BLIP/BLIP Overview.txt Sun May 25 10:28:26 2008 -0700 @@ -22,7 +22,7 @@ All multi-byte numbers are encoded in network byte-order (big-endian). -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. +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. 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. diff -r 76f302097a75 -r 2bd9d60a2c46 BLIP/Demo/BLIPEchoClient.h --- a/BLIP/Demo/BLIPEchoClient.h Sat May 24 21:26:09 2008 -0700 +++ b/BLIP/Demo/BLIPEchoClient.h Sun May 25 10:28:26 2008 -0700 @@ -4,7 +4,8 @@ // // Created by Jens Alfke on 5/24/08. // Copyright 2008 Jens Alfke. All rights reserved. -// Adapted from Apple sample code "CocoaEcho". +// Adapted from Apple sample code "CocoaEcho": +// http://developer.apple.com/samplecode/CocoaEcho/index.html // #import diff -r 76f302097a75 -r 2bd9d60a2c46 BLIP/Demo/BLIPEchoClient.m --- a/BLIP/Demo/BLIPEchoClient.m Sat May 24 21:26:09 2008 -0700 +++ b/BLIP/Demo/BLIPEchoClient.m Sun May 25 10:28:26 2008 -0700 @@ -4,7 +4,8 @@ // // Created by Jens Alfke on 5/24/08. // Copyright 2008 Jens Alfke. All rights reserved. -// Adapted from Apple sample code "CocoaEcho". +// Adapted from Apple sample code "CocoaEcho": +// http://developer.apple.com/samplecode/CocoaEcho/index.html // #import "BLIPEchoClient.h" @@ -29,12 +30,14 @@ #pragma mark - #pragma mark BLIPConnection support +/* Opens a BLIP connection to the given address. */ - (void)openConnection: (IPAddress*)address { _connection = [[BLIPConnection alloc] initToAddress: address]; [_connection open]; } +/* Closes the currently open BLIP connection. */ - (void)closeConnection { [_connection close]; @@ -66,6 +69,7 @@ #pragma mark - #pragma mark NSNetService delegate methods +/* Stop any current Bonjour address resolution */ - (void)stopResolving { if( _resolvingService ) { @@ -76,6 +80,7 @@ } } +/* Ask Bonjour to resolve (look up) the IP address of the given service. */ - (void)startResolving: (NSNetService*)service { [self stopResolving]; @@ -85,9 +90,11 @@ } +/* NSNetService delegate method that will be called when address resolution finishes. */ - (void)netServiceDidResolveAddress:(NSNetService *)sender { if( sender == _resolvingService ) { + // Get the first address, which is an NSData containing a struct sockaddr: NSArray *addresses = _resolvingService.addresses; if( addresses.count > 0 ) { NSData *addressData = [addresses objectAtIndex: 0]; @@ -114,6 +121,7 @@ } } +/* Send a BLIP request containing the string in the textfield */ - (IBAction)sendText:(id)sender { BLIPRequest *r = [_connection requestWithBody: nil]; @@ -122,6 +130,7 @@ response.onComplete = $target(self,gotResponse:); } +/* Receive the response to the BLIP request, and put its contents into the response field */ - (void) gotResponse: (BLIPResponse*)response { [responseField setObjectValue: response.bodyString]; diff -r 76f302097a75 -r 2bd9d60a2c46 maindocs.h --- a/maindocs.h Sat May 24 21:26:09 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: + + + +\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. + */