|
|
developer information [how to develop konspire2b apps]
using the API
core konspire2b functionality has been distilled into an API and a library implementation.
A konspire2b node can be started and manipulated in powerful ways with only a few simple API calls.
In fact, the kast system performs konspire2b operations exclusively through the API interface.
kast serves as a proof of concept: it is possible to write a full-featured konspire2b application using only the API for konspire2b functionality.
kast is essentially a GUI front-end for konspire2b, and it happens to be platform-independent.
Platform-dependent GUI front-ends would also be possible using the API.
the API library has been compiled for the five platforms currently supported by kast, and it should compile for any modern platform.
In fact, the kast releases we distribute were all generated by first compiling the konspire2b library for the target platform and then linking it into the final kast application.
the core API is easy to use--it consists of function calls that take arguments with primitive types.
The complex object-oriented structure of the underlying konspire2b reference implementation is not exposed in the core API.
A few additional function calls require object oriented features, but these calls are provided by a separate header file.
Thus, an application that uses only the core API functionality can be written using C.
the header file for the core API, konspire2b.h is well commented and includes plenty of example code. However, if you want API documentation that is easier to browse, HTML documentation generated by Doxygen is available:
konspire2b API documentation
downloadable distributions of the konspire2b API reference implementation libraries are coming soon.
starting from scratch (not using the API)
the konspire2b protocol is XML-based.
All messages are pure XML, with the exception of content data, which is sent in raw binary form (this is similar to HTTP, which uses text for headers but binary for bulk data transmission).
message types in the konspire2b protocol are fully described by XML DTDs and samples, which are kept in the CVS repository.
nodes in the konspire2b network connect to each other with two distinct connection types:
- permanent---long term connections that make up the konspire2b peer-to-peer network and are used for forwarding messages to neighbors
- temporary---short term connections that are used exclusively for transferring content data between nodes
when one node connects to another, the node initiating the connection sends an establishConnection message to indicate which kind of connection is being created (permanent or temporary).
After the connection is established, two-way message transmission on the connection begins.
permanent connections can carry the following message types:
- hostListRequest---requests a list of hosts
- hostList---a list of known hosts
- prebroadcast---an announcement for broadcast content
- prebroadcastResponse---a request for announced content
messages on a permanent connection can be sent in any order, though the following semantics are suggested:
- a hostListRequest should be responded to at some point with a hostList.
- a new prebroadcast (not seen before) should be forwarded to all permanent connection neighbors after decrementing the time-to-live counter.
- repeat prebroadcasts (seen before) or prebroadcasts with time-to-live counters of zero should be dropped.
- a prebroadcastResponse should be sent in response to a prebroadcast when a node wants the content described by the prebroadcast.
- prebroadcastResponses should be routed back along the path through which the original prebroadcast arrived.
temporary connections can carry the following message types:
- broadcastPermissionRequest---requests permission to send a broadcast
- broadcastPermissionResponse---grants or denies permission to broadcast
- broadcast---the actual content transmission (an XML header followed by binary content data)
messages on a temporary connection must be sent in a fixed order. After establishing a connection (by sending an establishConnection message), the initiator must send a broadcastPermissionRequest. The receiver must respond with a broadcastPermissionResponse. If permission is granted, the initiator must send a broadcast header, followed by the binary data content, and optionally followed by a data signature block.
A node sending a broadcast of content should perform the following steps:
- send out a prebroadcast for the content on all permanent connections
- wait for prebroadcastResponses to be returned on permanent connections (if no responses arrive, terminate the broadcast process)
- pick one of the responding nodes and establish a temporary connection with that node
- send a broadcastPermissionRequest on the temporary connection
- receive a broadcastPermissionResponse on the temporary connection
- if permission is granted, send the broadcast, content, and optional content signature
- close the temporary connection
- return to step 1
A node receiving a prebroadcast on a permanent connection should perform the following steps:
- check whether the prebroadcast has been seen yet
- if not seen, forward it on all other permanent connections (skipping the connection on which the prebroadcast was received)
- note the prebroadcast and connection on which it arrived in some kind of local database for prebroadcastResponses routing purposes
- if described content is wanted, send a prebroadcastResponse back through the connection on which the prebroadcast was received
A node receiving a prebroadcastResponse on a permanent connection should perform the following steps:
- route the prebroadcastResponse back through the channel on which the corresponding prebroadcast was originally received
|
