# HG changeset patch # User Jens Alfke # Date 1211743967 25200 # Node ID 2c4bb6968927ac49809c0f8dcfdc0d1b347e079c # Parent 2bd9d60a2c46661e2356f76065790f724cd9e948 More documentation. diff -r 2bd9d60a2c46 -r 2c4bb6968927 BLIP/BLIPConnection.h --- a/BLIP/BLIPConnection.h Sun May 25 10:28:26 2008 -0700 +++ b/BLIP/BLIPConnection.h Sun May 25 12:32:47 2008 -0700 @@ -12,7 +12,7 @@ @protocol BLIPConnectionDelegate; -/** Represents a connection to a peer, using the BLIP protocol over a TCP socket. +/** Represents a connection to a peer, using the BLIP protocol over a TCP socket. Outgoing connections are made simply by instantiating a BLIPConnection via -initToAddress:. Incoming connections are usually set up by a BLIPListener and passed to the listener's delegate. @@ -34,14 +34,14 @@ a generic error response will be returned. */ @property (readonly) BLIPDispatcher *dispatcher; -/** Creates an outgoing request, with no properties. - The body may be nil. - To send it, call -send. */ -- (BLIPRequest*) requestWithBody: (NSData*)body; +/** Creates a new, empty outgoing request. + You should add properties and/or body data to the request, before sending it by + calling its -send method. */ +- (BLIPRequest*) request; -/** Creates an outgoing request. - The body or properties may be nil. - To send it, call -send. */ +/** Creates a new outgoing request. + The body or properties may be nil; you can add additional data or properties by calling + methods on the request itself, before sending it by calling its -send method. */ - (BLIPRequest*) requestWithBody: (NSData*)body properties: (NSDictionary*)properies; @@ -78,7 +78,7 @@ -/** A "server" that listens on a TCP socket for incoming BLIP connections and creates +/** A "server" that listens on a TCP socket for incoming BLIP connections and creates BLIPConnection instances to handle them. Most of the API is inherited from TCPListener. */ @interface BLIPListener : TCPListener diff -r 2bd9d60a2c46 -r 2c4bb6968927 BLIP/BLIPConnection.m --- a/BLIP/BLIPConnection.m Sun May 25 10:28:26 2008 -0700 +++ b/BLIP/BLIPConnection.m Sun May 25 12:32:47 2008 -0700 @@ -81,9 +81,9 @@ } -- (BLIPRequest*) requestWithBody: (NSData*)body +- (BLIPRequest*) request { - return [[[BLIPRequest alloc] _initWithConnection: self body: body properties: nil] autorelease]; + return [[[BLIPRequest alloc] _initWithConnection: self body: nil properties: nil] autorelease]; } - (BLIPRequest*) requestWithBody: (NSData*)body diff -r 2bd9d60a2c46 -r 2c4bb6968927 BLIP/BLIPMessage.h --- a/BLIP/BLIPMessage.h Sun May 25 10:28:26 2008 -0700 +++ b/BLIP/BLIPMessage.h Sun May 25 12:32:47 2008 -0700 @@ -31,7 +31,7 @@ }; -/** Abstract superclass for BLIP requests and responses. */ +/** Abstract superclass for BLIP requests and responses. */ @interface BLIPMessage : NSObject { BLIPConnection *_connection; diff -r 2bd9d60a2c46 -r 2c4bb6968927 BLIP/BLIPRequest.h --- a/BLIP/BLIPRequest.h Sun May 25 10:28:26 2008 -0700 +++ b/BLIP/BLIPRequest.h Sun May 25 12:32:47 2008 -0700 @@ -10,7 +10,7 @@ @class BLIPResponse, MYTarget; -/** A Request, or initiating message. */ +/** A Request, or initiating message, in the BLIP protocol. */ @interface BLIPRequest : BLIPMessage { @private @@ -80,7 +80,7 @@ -/** A reply to a BLIPRequest. */ +/** A reply to a BLIPRequest, in the BLIP protocol. */ @interface BLIPResponse : BLIPMessage { @private diff -r 2bd9d60a2c46 -r 2c4bb6968927 MYNetwork.xcodeproj/project.pbxproj --- a/MYNetwork.xcodeproj/project.pbxproj Sun May 25 10:28:26 2008 -0700 +++ b/MYNetwork.xcodeproj/project.pbxproj Sun May 25 12:32:47 2008 -0700 @@ -46,13 +46,46 @@ 277904460DE91E3700C6D295 /* Logging.m in Sources */ = {isa = PBXBuildFile; fileRef = 2704612A0DE49088003D9D3F /* Logging.m */; }; 277904480DE91E3900C6D295 /* Target.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461460DE491A6003D9D3F /* Target.m */; }; 277904490DE91E3A00C6D295 /* Test.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461280DE49088003D9D3F /* Test.m */; }; - 2779046D0DE91F4200C6D295 /* BLIPEchoServer.m in Sources */ = {isa = PBXBuildFile; fileRef = 277903D60DE8EE4800C6D295 /* BLIPEchoServer.m */; }; 2779048B0DE9204300C6D295 /* BLIPEchoClient.xib in Resources */ = {isa = PBXBuildFile; fileRef = 2779048A0DE9204300C6D295 /* BLIPEchoClient.xib */; }; + 277905110DE9E5BC00C6D295 /* BLIPConnection.m in Sources */ = {isa = PBXBuildFile; fileRef = 270460F40DE49030003D9D3F /* BLIPConnection.m */; }; + 277905120DE9E5BC00C6D295 /* BLIPDispatcher.m in Sources */ = {isa = PBXBuildFile; fileRef = 270460F60DE49030003D9D3F /* BLIPDispatcher.m */; }; + 277905130DE9E5BC00C6D295 /* BLIPMessage.m in Sources */ = {isa = PBXBuildFile; fileRef = 270460F90DE49030003D9D3F /* BLIPMessage.m */; }; + 277905140DE9E5BC00C6D295 /* BLIPProperties.m in Sources */ = {isa = PBXBuildFile; fileRef = 270460FB0DE49030003D9D3F /* BLIPProperties.m */; }; + 277905150DE9E5BC00C6D295 /* BLIPReader.m in Sources */ = {isa = PBXBuildFile; fileRef = 270460FD0DE49030003D9D3F /* BLIPReader.m */; }; + 277905160DE9E5BC00C6D295 /* BLIPWriter.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461000DE49030003D9D3F /* BLIPWriter.m */; }; + 277905170DE9E5BC00C6D295 /* IPAddress.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461020DE49030003D9D3F /* IPAddress.m */; }; + 277905180DE9E5BC00C6D295 /* TCPConnection.m in Sources */ = {isa = PBXBuildFile; fileRef = 2704610A0DE49030003D9D3F /* TCPConnection.m */; }; + 277905190DE9E5BC00C6D295 /* TCPEndpoint.m in Sources */ = {isa = PBXBuildFile; fileRef = 2704610C0DE49030003D9D3F /* TCPEndpoint.m */; }; + 2779051A0DE9E5BC00C6D295 /* TCPListener.m in Sources */ = {isa = PBXBuildFile; fileRef = 2704610E0DE49030003D9D3F /* TCPListener.m */; }; + 2779051B0DE9E5BC00C6D295 /* TCPStream.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461100DE49030003D9D3F /* TCPStream.m */; }; + 2779051C0DE9E5BC00C6D295 /* TCPWriter.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461120DE49030003D9D3F /* TCPWriter.m */; }; + 2779051D0DE9E5BC00C6D295 /* Test.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461280DE49088003D9D3F /* Test.m */; }; + 2779051E0DE9E5BC00C6D295 /* Logging.m in Sources */ = {isa = PBXBuildFile; fileRef = 2704612A0DE49088003D9D3F /* Logging.m */; }; + 2779051F0DE9E5BC00C6D295 /* ExceptionUtils.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461350DE4918D003D9D3F /* ExceptionUtils.m */; }; + 277905200DE9E5BC00C6D295 /* Target.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461460DE491A6003D9D3F /* Target.m */; }; + 277905210DE9E5BC00C6D295 /* GTMNSData+zlib.m in Sources */ = {isa = PBXBuildFile; fileRef = 2704616F0DE492F3003D9D3F /* GTMNSData+zlib.m */; }; + 277905220DE9E5BC00C6D295 /* CollectionUtils.m in Sources */ = {isa = PBXBuildFile; fileRef = 270461870DE49634003D9D3F /* CollectionUtils.m */; }; + 277905230DE9E5BC00C6D295 /* BLIPRequest.m in Sources */ = {isa = PBXBuildFile; fileRef = 27D5EC060DE5FEDE00CD84FA /* BLIPRequest.m */; }; + 277905240DE9E5BC00C6D295 /* BLIPEchoServer.m in Sources */ = {isa = PBXBuildFile; fileRef = 277903D60DE8EE4800C6D295 /* BLIPEchoServer.m */; }; + 277905260DE9E5BC00C6D295 /* Foundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 08FB779EFE84155DC02AAC07 /* Foundation.framework */; }; + 277905270DE9E5BC00C6D295 /* libz.dylib in Frameworks */ = {isa = PBXBuildFile; fileRef = 2704618B0DE49652003D9D3F /* libz.dylib */; }; + 277905280DE9E5BC00C6D295 /* CoreServices.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 270461910DE4975C003D9D3F /* CoreServices.framework */; }; + 277905300DE9ED9100C6D295 /* MYUtilitiesTest_main.m in Sources */ = {isa = PBXBuildFile; fileRef = 270462C10DE4A64B003D9D3F /* MYUtilitiesTest_main.m */; }; + 2779053B0DE9EDAA00C6D295 /* BLIPTest.m in Sources */ = {isa = PBXBuildFile; fileRef = 270460FE0DE49030003D9D3F /* BLIPTest.m */; }; 27D5EC070DE5FEDE00CD84FA /* BLIPRequest.m in Sources */ = {isa = PBXBuildFile; fileRef = 27D5EC060DE5FEDE00CD84FA /* BLIPRequest.m */; }; 8DD76F9C0486AA7600D96B5E /* Foundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 08FB779EFE84155DC02AAC07 /* Foundation.framework */; }; /* End PBXBuildFile section */ /* Begin PBXCopyFilesBuildPhase section */ + 277905290DE9E5BC00C6D295 /* CopyFiles */ = { + isa = PBXCopyFilesBuildPhase; + buildActionMask = 8; + dstPath = /usr/share/man/man1/; + dstSubfolderSpec = 0; + files = ( + ); + runOnlyForDeploymentPostprocessing = 1; + }; 8DD76F9E0486AA7600D96B5E /* CopyFiles */ = { isa = PBXCopyFilesBuildPhase; buildActionMask = 8; @@ -121,6 +154,7 @@ 277904260DE91C7900C6D295 /* BLIP Echo Client.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "BLIP Echo Client.app"; sourceTree = BUILT_PRODUCTS_DIR; }; 277904280DE91C7900C6D295 /* BLIP Echo Client-Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = "BLIP Echo Client-Info.plist"; sourceTree = ""; }; 2779048A0DE9204300C6D295 /* BLIPEchoClient.xib */ = {isa = PBXFileReference; lastKnownFileType = file.xib; path = BLIPEchoClient.xib; sourceTree = ""; }; + 2779052D0DE9E5BC00C6D295 /* BLIPEchoServer */ = {isa = PBXFileReference; explicitFileType = "compiled.mach-o.executable"; includeInIndex = 0; path = BLIPEchoServer; sourceTree = BUILT_PRODUCTS_DIR; }; 27D5EC050DE5FEDE00CD84FA /* BLIPRequest.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = BLIPRequest.h; sourceTree = ""; }; 27D5EC060DE5FEDE00CD84FA /* BLIPRequest.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = BLIPRequest.m; sourceTree = ""; }; /* End PBXFileReference section */ @@ -133,6 +167,16 @@ ); runOnlyForDeploymentPostprocessing = 0; }; + 277905250DE9E5BC00C6D295 /* Frameworks */ = { + isa = PBXFrameworksBuildPhase; + buildActionMask = 2147483647; + files = ( + 277905260DE9E5BC00C6D295 /* Foundation.framework in Frameworks */, + 277905270DE9E5BC00C6D295 /* libz.dylib in Frameworks */, + 277905280DE9E5BC00C6D295 /* CoreServices.framework in Frameworks */, + ); + runOnlyForDeploymentPostprocessing = 0; + }; 8DD76F9B0486AA7600D96B5E /* Frameworks */ = { isa = PBXFrameworksBuildPhase; buildActionMask = 2147483647; @@ -175,6 +219,7 @@ children = ( 270461720DE49340003D9D3F /* MYNetwork */, 277904260DE91C7900C6D295 /* BLIP Echo Client.app */, + 2779052D0DE9E5BC00C6D295 /* BLIPEchoServer */, ); name = Products; sourceTree = ""; @@ -296,6 +341,24 @@ productReference = 277904260DE91C7900C6D295 /* BLIP Echo Client.app */; productType = "com.apple.product-type.application"; }; + 2779050F0DE9E5BC00C6D295 /* BLIP Echo Server */ = { + isa = PBXNativeTarget; + buildConfigurationList = 2779052A0DE9E5BC00C6D295 /* Build configuration list for PBXNativeTarget "BLIP Echo Server" */; + buildPhases = ( + 277905100DE9E5BC00C6D295 /* Sources */, + 277905250DE9E5BC00C6D295 /* Frameworks */, + 277905290DE9E5BC00C6D295 /* CopyFiles */, + ); + buildRules = ( + ); + dependencies = ( + ); + name = "BLIP Echo Server"; + productInstallPath = "$(HOME)/bin"; + productName = MYNetwork; + productReference = 2779052D0DE9E5BC00C6D295 /* BLIPEchoServer */; + productType = "com.apple.product-type.tool"; + }; 8DD76F960486AA7600D96B5E /* MYNetwork */ = { isa = PBXNativeTarget; buildConfigurationList = 1DEB927408733DD40010E9CD /* Build configuration list for PBXNativeTarget "MYNetwork" */; @@ -328,6 +391,7 @@ targets = ( 8DD76F960486AA7600D96B5E /* MYNetwork */, 277904250DE91C7900C6D295 /* BLIP Echo Client */, + 2779050F0DE9E5BC00C6D295 /* BLIP Echo Server */, ); }; /* End PBXProject section */ @@ -370,6 +434,33 @@ ); runOnlyForDeploymentPostprocessing = 0; }; + 277905100DE9E5BC00C6D295 /* Sources */ = { + isa = PBXSourcesBuildPhase; + buildActionMask = 2147483647; + files = ( + 277905110DE9E5BC00C6D295 /* BLIPConnection.m in Sources */, + 277905120DE9E5BC00C6D295 /* BLIPDispatcher.m in Sources */, + 277905130DE9E5BC00C6D295 /* BLIPMessage.m in Sources */, + 277905140DE9E5BC00C6D295 /* BLIPProperties.m in Sources */, + 277905150DE9E5BC00C6D295 /* BLIPReader.m in Sources */, + 277905160DE9E5BC00C6D295 /* BLIPWriter.m in Sources */, + 277905170DE9E5BC00C6D295 /* IPAddress.m in Sources */, + 277905180DE9E5BC00C6D295 /* TCPConnection.m in Sources */, + 277905190DE9E5BC00C6D295 /* TCPEndpoint.m in Sources */, + 2779051A0DE9E5BC00C6D295 /* TCPListener.m in Sources */, + 2779051B0DE9E5BC00C6D295 /* TCPStream.m in Sources */, + 2779051C0DE9E5BC00C6D295 /* TCPWriter.m in Sources */, + 2779051D0DE9E5BC00C6D295 /* Test.m in Sources */, + 2779051E0DE9E5BC00C6D295 /* Logging.m in Sources */, + 2779051F0DE9E5BC00C6D295 /* ExceptionUtils.m in Sources */, + 277905200DE9E5BC00C6D295 /* Target.m in Sources */, + 277905210DE9E5BC00C6D295 /* GTMNSData+zlib.m in Sources */, + 277905220DE9E5BC00C6D295 /* CollectionUtils.m in Sources */, + 277905230DE9E5BC00C6D295 /* BLIPRequest.m in Sources */, + 277905240DE9E5BC00C6D295 /* BLIPEchoServer.m in Sources */, + ); + runOnlyForDeploymentPostprocessing = 0; + }; 8DD76F990486AA7600D96B5E /* Sources */ = { isa = PBXSourcesBuildPhase; buildActionMask = 2147483647; @@ -393,7 +484,8 @@ 270461700DE492F3003D9D3F /* GTMNSData+zlib.m in Sources */, 270461890DE49634003D9D3F /* CollectionUtils.m in Sources */, 27D5EC070DE5FEDE00CD84FA /* BLIPRequest.m in Sources */, - 2779046D0DE91F4200C6D295 /* BLIPEchoServer.m in Sources */, + 277905300DE9ED9100C6D295 /* MYUtilitiesTest_main.m in Sources */, + 2779053B0DE9EDAA00C6D295 /* BLIPTest.m in Sources */, ); runOnlyForDeploymentPostprocessing = 0; }; @@ -509,6 +601,38 @@ }; name = Release; }; + 2779052B0DE9E5BC00C6D295 /* Debug */ = { + isa = XCBuildConfiguration; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + COPY_PHASE_STRIP = NO; + GCC_C_LANGUAGE_STANDARD = gnu99; + GCC_DYNAMIC_NO_PIC = NO; + GCC_ENABLE_FIX_AND_CONTINUE = YES; + GCC_MODEL_TUNING = G5; + GCC_OPTIMIZATION_LEVEL = 0; + GCC_PRECOMPILE_PREFIX_HEADER = YES; + GCC_PREFIX_HEADER = ../MYUtilities/MYUtilities_Prefix.pch; + GCC_PREPROCESSOR_DEFINITIONS = DEBUG; + INSTALL_PATH = /usr/local/bin; + PRODUCT_NAME = BLIPEchoServer; + }; + name = Debug; + }; + 2779052C0DE9E5BC00C6D295 /* Release */ = { + isa = XCBuildConfiguration; + buildSettings = { + ALWAYS_SEARCH_USER_PATHS = NO; + DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym"; + GCC_C_LANGUAGE_STANDARD = gnu99; + GCC_MODEL_TUNING = G5; + GCC_PRECOMPILE_PREFIX_HEADER = YES; + GCC_PREFIX_HEADER = MYNetwork_Prefix.pch; + INSTALL_PATH = /usr/local/bin; + PRODUCT_NAME = BLIPEchoServer; + }; + name = Release; + }; /* End XCBuildConfiguration section */ /* Begin XCConfigurationList section */ @@ -539,6 +663,15 @@ defaultConfigurationIsVisible = 0; defaultConfigurationName = Release; }; + 2779052A0DE9E5BC00C6D295 /* Build configuration list for PBXNativeTarget "BLIP Echo Server" */ = { + isa = XCConfigurationList; + buildConfigurations = ( + 2779052B0DE9E5BC00C6D295 /* Debug */, + 2779052C0DE9E5BC00C6D295 /* Release */, + ); + defaultConfigurationIsVisible = 0; + defaultConfigurationName = Release; + }; /* End XCConfigurationList section */ }; rootObject = 08FB7793FE84155DC02AAC07 /* Project object */; diff -r 2bd9d60a2c46 -r 2c4bb6968927 maindocs.h --- a/maindocs.h Sun May 25 10:28:26 2008 -0700 +++ b/maindocs.h Sun May 25 12:32:47 2008 -0700 @@ -8,7 +8,9 @@ // This file just contains the Doxygen comments that generate the main (index.html) page content. -/*! \mainpage MYNetwork: Mooseyard Networking library, including BLIP protocol implementation. +/*! \mainpage MYNetwork: Mooseyard Networking Library, With BLIP Protocol Implementation + +
By Jens Alfke
\section intro_sec Introduction @@ -18,12 +20,22 @@
  • Networking utility classes (presently only IPAddress);
  • A generic TCP client/server implementation, useful for implementing your own network protocols; (see TCPListener and TCPConnection) -
  • An implementation of BLIP, a lightweight network protocol I've invented as an easy way +
  • An implementation of BLIP, a lightweight network protocol I've invented as an easy way to send request and response messages between peers. (see BLIPListener, BLIPConnection, BLIPRequest, etc.) - 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 license License and Disclaimer + + 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. + + As I write this (May 2008), MYNetwork is still very much under development. I am using it as the foundation of my own commercial products, at least one of which is currently at about the alpha stage. I'm making changes to this code as I see fit, fairly often. + +That's good, in that the code is getting real-world use. But it also means that APIs and functionality are subject to change. (Of course, the entire revision tree is always available, so you're free to stick with any revision you like, and even "cherry-pick" desired changes from future ones.) + +Not all of this code gets thoroughly exercised by my test cases or my applications, so some things may not work. Obviously, this code comes with no warranty nor any guarantee of tech support, though I will try to do my best to help out. Hopefully the source code is clear enough to let you figure out what's going on. + +If you come across bugs, please tell me about them. If you fix them, I would love to get your fixes and incorporate them. If you add features I would love to know about them, and I will incorporate them if I think they make sense for the project. Thanks! \section blipdesc What's BLIP? @@ -31,7 +43,7 @@ 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. +deliberately simpler and somewhat more limited. That results in a smaller and cleaner implementation, especially since it takes advantage of Cocoa's and CFNetwork's existing support for network streams, SSL and Bonjour. (BLIP is currently a bit under 2,000 lines of code, and the rest of the MYNetwork classes it builds on add up to another 1,500. That's at least an order of magnitude smaller than existing native-code BEEP libraries.) \subsection blipfeatures BLIP Features: