---

konspire2b.h File Reference

#include <stdio.h>

Go to the source code of this file.

Defines
#define	K2B_DEACTIVATE_LEVEL   0
#define	K2B_CRITICAL_ERROR_LEVEL   1
#define	K2B_ERROR_LEVEL   2
#define	K2B_WARNING_LEVEL   3
#define	K2B_INFO_LEVEL   4
#define	K2B_DETAIL_LEVEL   5
#define	K2B_TRACE_LEVEL   6
Functions
void	k2bStartup (int inPort)
void	k2bShutdown ()
void	k2bSetLoggingLevel (int inLoggingLevel)
void	k2bSetLogFile (char *inLogFilePath)
char	k2bIsLocalAddressProvidedByNetwork ()
char*	k2bGetLocalHostAddress ()
void	k2bSetTimeToLive (int inTimeToLive)
int	k2bGetTimeToLive ()
void	k2bSetTimeToLiveCap (int inCap)
int	k2bGetTimeToLiveCap ()
void	k2bSetLocalHostAddress (char *inAddress)
void	k2bSetTargetNumberOfConnections (int inTarget)
int	k2bGetTargetNumberOfConnections ()
void	k2bAddHost (char *inHostAddress, int inHostPort)
int	k2bGetConnectedHostList (char ***outHostAddresses, int **outHostPorts)
void	k2bSubscribeToChannel (char *inChannelName)
void	k2bUnsubscribeFromChannel (char *inChannelName)
int	k2bGetSubscriptionList (char ***outChannelNames)
void	k2bInitiateBroadcast (char *inChannelName, char *inBroadcastName, char *inBroadcastComment, char *inFilePath, char *inContentType)
void	k2bInitiateBroadcastSeries (char *inChannelName, int inNumBroadcasts, char **inBroadcastNames, char **inBroadcastComments, char **inFilePaths, char **inContentTypes)
int	k2bGetCaughtPrebroadcasts (char ***outChannelNames, char ***outBroadcastNames, char ***outComments, char ***outContentTypes, unsigned long **outContentLengthsInBytes, char **outWantedFlags)
void	k2bGenerateSenderKeyPair (char *inChannelName, char *inRandomSeed)
char	k2bFetchReceiverKey (char *inChannelName, char *inKeyURL)
char*	k2bGetSenderKeyFile (char *inChannelName)
char*	k2bGetReceiverKeyFile (char *inChannelName)
int	k2bGetChannelsWithSenderKeys (char ***outChannelNames)
int	k2bGetChannelsWithReceiverKeys (char ***outChannelNames)
int	k2bGetPendingBroadcastStatus (char ***outChannelNames, char ***outBroadcastNames, char ***outComments, char ***outContentTypes, unsigned long **outContentLengthsInBytes, float **outFractionComplete, float **outKiBPerSecond, char **outCancelFlags)
void	k2bCancelPendingBroadcast (char *inChannelName, char *inBroadcastName)

---

Detailed Description

The API (Application Programming Interface) for interfacing with the functionality of the konspire2b reference implementation.

This API is essentially a collection of functions for controling the behavior of a konspire2b-compliant node.

All parameters of type (char *) must be \0-terminated strings. Such parameters must be destroyed by the function caller if non-const: the parameters are copied internally by the callee.

Author:

Jason Rohrer

---

Define Documentation

#define K2B_CRITICAL_ERROR_LEVEL   1

#define K2B_DEACTIVATE_LEVEL   0

#define K2B_DETAIL_LEVEL   5

#define K2B_ERROR_LEVEL   2

#define K2B_INFO_LEVEL   4

#define K2B_TRACE_LEVEL   6

#define K2B_WARNING_LEVEL   3

---

Function Documentation

void k2bAddHost ( char * inHostAddress, int inHostPort )

Adds a host to the local host list. Parameters: inHostAddress   the internet address of the host to add. inHostPort   the konspire2b port of the host to add. Examples: k2bAddHost( "k2b.myhost.com", 6089 ); k2bAddHost( "128.243.100.9", 6089 );

void k2bCancelPendingBroadcast ( char * inChannelName, char * inBroadcastName )

Cancels receipt of a pending broadcast. Parameters: inChannelName   the channel the broadcast is being received on. inBroadcastName   the name of the pending broadcast.

char k2bFetchReceiverKey ( char * inChannelName, char * inKeyURL )

Adds a receiver key by downloading it from a URL. The public portion of the key will be saved into the receiver key folder with the name "channelName.key". Parameters: inChannelName   the name of the channel to fetch a key for. inKeyURL   the URL of the key to download. Returns: true if fetching the key succeeds, and false if fetching fails. Example: char fetched = k2bFetchReceiverKey( "testChannel", "http://www.myserver.com/testChan.key" );

void k2bGenerateSenderKeyPair ( char * inChannelName, char * inRandomSeed )

Generates a sender key pair. The private portion of the key will be saved into the sender key folder with the name "channelName.key". The public portion of the key will be saved into the receiver key folder with the name "channelName.key". Parameters: inChannelName   the name of the channel to generate a key for. inRandomSeed   the random seed string to use when generating the key. The key is only as secure as the random seed string. In general, the random seed should be provided by the user typing in a "random" or "garbled" character string. Example: k2bGenerateSenderKeyPair( "testChannel", "sdfj fjsdf u48932 fjk83mv9 df9" );

int k2bGetCaughtPrebroadcasts ( char *** outChannelNames, char *** outBroadcastNames, char *** outComments, char *** outContentTypes, unsigned long ** outContentLengthsInBytes, char ** outWantedFlags )

Gets a list of caught prebroadcasts. Note that the reference implementation discards old caught Prebroadcasts, so the returned list is bounded in sized. Parameters: outChannelNames   location where the channel names for the caught prebroadcasts should be returned. The array and the strings it contains must be destroyed by caller. outBroadcastNames   location where the broadcast names for the caught prebroadcasts should be returned. The array and the strings it contains must be destroyed by caller. outComments   location where the comments for the caught prebroadcasts should be returned. The array and the strings it contains must be destroyed by caller. outContentTypes   location where the content types for the caught prebroadcasts should be returned. The array and the strings it contains must be destroyed by caller. outContentLengthsInBytes   pointer to location where array of content lengths for each caught prebroadcast should be returned. Must be destroyed by caller. outWantedFlags   pointer to location where array of wanted flags should be returned. Each flag is true iff the corresponding prebroadcast was wanted by the current node (for example, if the node is subscribed to the channel, the prebroadcast has not yet been received, and the name signature passes). Must be destroyed by caller. Returns: the number of Prebroadcasts caught (in other words, the length of each of the returned arrays). Example: char **caughtChannelNames; char **caughtBroadcastNames; char **caughtComments; char **caughtContentTypes; unsigned long *caughtContentLengths; char *caughtWantedFlags; int numCaught = k2bGetCaughtPrebroadcasts( &caughtChannelNames, &caughtBroadcastNames, &caughtComments, &caughtContentTypes, &caughtContentLengths ); // process caught Prebroadcasts here ... // now destroyed returned arrays for( int i=0; i<numCaught; i++ ) { delete [] caughtChannelNames[i]; delete [] caughtBroadcastNames[i]; delete [] caughtComments[i]; delete [] caughtContentTypes[i]; } delete [] caughtChannelNames; delete [] caughtBroadcastNames; delete [] caughtComments; delete [] caughtContentTypes; delete [] caughtContentLengths; delete [] caughtWantedFlags;

int k2bGetChannelsWithReceiverKeys ( char *** outChannelNames )

Gets a list of channels for which we have receiver keys. Parameters: outChannelNames   pointer to location where array of channel name strings should be returned. The array and the strings it contains must be destroyed by caller. Returns: the number of channel names returned (in other words, the length of the returned array). Example: char **channelNames; int numChannels = k2bGetChannelsWithReceiverKeys( &channelNames ); // process channel names here ... // now destroyed returned array for( int i=0; i<numChannels; i++ ) { delete [] channelNames[i]; } delete [] channelNames;

int k2bGetChannelsWithSenderKeys ( char *** outChannelNames )

Gets a list of channels for which we have sender keys. Parameters: outChannelNames   pointer to location where array of channel name strings should be returned. The array and the strings it contains must be destroyed by caller. Returns: the number of channel names returned (in other words, the length of the returned array). Example: char **channelNames; int numChannels = k2bGetChannelsWithSenderKeys( &channelNames ); // process channel names here ... // now destroyed returned array for( int i=0; i<numChannels; i++ ) { delete [] channelNames[i]; } delete [] channelNames;

int k2bGetConnectedHostList ( char *** outHostAddresses, int ** outHostPorts )

Gets a list of hosts that the local node is directly connected to. Parameters: outHostAddresses   pointer to location where an array of host address strings should be returned. The array and the strings it contains must be destroyed by caller. outHostPorts   pointer to location where an array of host ports should be returned. The array must be destroyed by caller. Returns: the number of hosts returned (in other words, the length of each returned array). Example: char **addresses; int *ports; int numHosts = k2bGetConnectedHostList( &addresses, &ports ); // process addresses here ... // now destroyed returned arrays for( int i=0; i<numHosts; i++ ) { delete [] addresses[i]; } delete [] addresses; delete [] ports;

char * k2bGetLocalHostAddress ( )

Gets the local network address of this node.

int k2bGetPendingBroadcastStatus ( char *** outChannelNames, char *** outBroadcastNames, char *** outComments, char *** outContentTypes, unsigned long ** outContentLengthsInBytes, float ** outFractionComplete, float ** outKiBPerSecond, char ** outCancelFlags )

Gets the status of any broadcast in the process of being received. When these broadcasts are completely received, they will be copied into the received folder and into the appropriate channel sub-folder. Parameters: outChannelNames   location where the channel names for the pending broadcasts should be returned. The array and the strings it contains must be destroyed by caller. outBroadcastNames   location where the broadcast names for the pending broadcasts should be returned. The array and the strings it contains must be destroyed by caller. outComments   location where the comments for the pending broadcasts should be returned. The array and the strings it contains must be destroyed by caller. outContentTypes   location where the content types for the pending broadcasts should be returned. The array and the strings it contains must be destroyed by caller. outContentLengthsInBytes   pointer to location where array of content lengths for each broadcast should be returned. Must be destroyed by caller. outFractionComplete   pointer to location where array of fraction complete values for each Broadcast should be returned. Must be destroyed by caller. outKiBPerSecond   pointer to location where array of KiB/sec transfer speed values for each Broadcast should be returned. Must be destroyed by caller. outCancelFlags   pointer to location where array of cancel flags (true iff cancel pending) for each Broadcast should be returned. Must be destroyed by caller. Returns: the number of Broadcasts pending (in other words, the length of each of the returned arrays). Example: char **pendingChannelNames; char **pendingBroadcastNames; char **pendingComments; char **pendingContentTypes; unsigned long *pendingContentLengths; float *fractionComplete; float *pendingSpeeds; char *cancelFlags; int numPending = k2bGetPendingBroadcastStatus( &pendingChannelNames, &pendingBroadcastNames, &pendingComments, &pendingContentTypes, &pendingContentLengths, &fractionComplete, &pendingSpeeds, &cancelFlags ); // process pending Broadcasts here ... // now destroyed returned arrays for( int i=0; i<numPending; i++ ) { delete [] pendingChannelNames[i]; delete [] pendingBroadcastNames[i]; delete [] pendingComments[i]; delete [] pendingContentTypes[i]; } delete [] pendingChannelNames; delete [] pendingBroadcastNames; delete [] pendingComments; delete [] pendingContentTypes; delete [] pendingContentLengths; delete [] fractionComplete; delete [] pendingSpeeds; delete [] cancelFlags;

char * k2bGetReceiverKeyFile ( char * inChannelName )

Gets the path to the receiver (public) portion of a key for a channel, if it exists. Parameters: inChannelName   the name of the channel to get a key for. Returns: a platform-specific path to the key file, or NULL if no receiver key is present for this channel. Must be destroyed by caller if not NULL. Example: char *filePath = k2bGetReceiverKeyFile( "testChan" ); if( filePath != NULL ) { // process file path here ... // destroy file path delete [] filePath; }

char * k2bGetSenderKeyFile ( char * inChannelName )

Gets the path to the sender (private) portion of a key for a channel, if it exists. Parameters: inChannelName   the name of the channel to get a key for. Returns: a platform-specific path to the key file, or NULL if no sender key is present for this channel. Must be destroyed by caller if not NULL. Example: char *filePath = k2bGetSenderKeyFile( "testChan" ); if( filePath != NULL ) { // process file path here ... // destroy file path delete [] filePath; }

int k2bGetSubscriptionList ( char *** outChannelNames )

Gets a list of subscribed channels. Parameters: outChannelNames   pointer to location where array of channel name strings should be returned. The array and the strings it contains must be destroyed by caller. Returns: the number of channel names returned (in other words, the length of the returned array). Example: char **channelNames; int numChannels = k2bGetSubscriptionList( &channelNames ); // process channel names here ... // now destroyed returned array for( int i=0; i<numChannels; i++ ) { delete [] channelNames[i]; } delete [] channelNames;

int k2bGetTargetNumberOfConnections ( )

Sets the number of connections this node is trying to maintain. Returns: the target number of connections being maintained..

int k2bGetTimeToLive ( )

Gets the time to live for new prebroadcasts sent by this node. Returns: the starting time to live value.

int k2bGetTimeToLiveCap ( )

Gets the cap for the time to live of forwarded prebroadcasts. Returns: the limit value, or 0 to indicate no cap.

void k2bInitiateBroadcast ( char * inChannelName, char * inBroadcastName, char * inBroadcastComment, char * inFilePath, char * inContentType )

Sends a broadcast. Note: If a sender key exists for the specified channel, it will be used to sign the broadcast. Parameters: inChannelName   the channel to send the broadcast on. inBroadcastName   the name of the broadcast (for example, the file name, if appropriate). inBroadcastComment   the comment for the broadcast. inFilePath   the platform-specific path string locating the file containing the contents for this broadcast. inContentType   the MIME type of the content, or NULL if the content has no type. Example: k2bInitiateBroadcast( "testChan", "testBroadcast.txt", "This is a test broadcast.", "myFiles/testMessage.txt", "text/plain" );

void k2bInitiateBroadcastSeries ( char * inChannelName, int inNumBroadcasts, char ** inBroadcastNames, char ** inBroadcastComments, char ** inFilePaths, char ** inContentTypes )

Sends a series of broadcasts out on the same channel, one by one. Note: If a sender key exists for the specified channel, it will be used to sign the broadcast. Parameters: inChannelName   the channel to send the broadcasts on. inNumBroadcasts   the number of broadcasts to send. inBroadcastNames   the name of each broadcast (for example, the file name, if appropriate). inBroadcastComments   the comment for each broadcast. inFilePath   the platform-specific path string locating the file containing the contents for each broadcast. inContentType   the MIME type of the content for each broadcast, or NULL if the content has no type. Example: int numBroadcasts = 2; char **names = new char*[ numBroadcasts ]; names[0] = "testFile1.txt"; names[2] = "testFile2.txt"; char **comments = new char*[ numBroadcasts ]; comments[0] = "The first in this series."; comments[2] = "The second in this series."; char **paths = new char*[ numBroadcasts ]; paths[0] = "myFiles/testMessage1.txt"; paths[2] = "myFiles/testMessage2.txt"; char **types = new char*[ numBroadcasts ]; types[0] = "text/plain"; types[2] = "text/plain"; k2bInitiateBroadcastSeries( "testChan", numBroadcasts, names, comments, paths, types ); delete [] names; delete [] comments; delete [] paths; delete [] types;

char k2bIsLocalAddressProvidedByNetwork ( )

Gets whether the local network address of this node is provided by the network system. Returns: true if the local address is provided by the network system, and false if the local address is provided by the user.

void k2bSetLocalHostAddress ( char * inAddress )

Sets the local network address of this node. This parameter is useful for nodes operating behind firewalls with tunnels for k2b traffic. In such cases, the address of the firewall must be specified so that other nodes outside the firewall can innitiate connections to the firewall-protected node. Parameters: inLocalHostAddress   the address this node will send out as its local host address, or NULL to use the address obtainable from the system.

void k2bSetLogFile ( char * inLogFilePath )

Sets the file to which log messages are written. Defaults to konspire2b.log in the current working directory. Parameters: inLogFilePath   path name to the log file. Example: k2bSetLogFile( "test.log" );

void k2bSetLoggingLevel ( int inLoggingLevel )

Sets the logging level used by the reference implementation. Parameters: inLoggingLevel   the logging level to use. One of: K2B_DEACTIVATE_LEVEL K2B_CRITICAL_ERROR_LEVEL K2B_ERROR_LEVEL K2B_WARNING_LEVEL K2B_INFO_LEVEL K2B_DETAIL_LEVEL K2B_TRACE_LEVEL Values further down on this list show more detailed log messages.

void k2bSetTargetNumberOfConnections ( int inTarget )

Sets the number of connections maintained by this node. Parameters: inTarget   the target number of connections to maintain.

void k2bSetTimeToLive ( int inTimeToLive )

Sets the time to live for new prebroadcasts sent by this node. Parameters: inTimeToLive   the starting time to live value.

void k2bSetTimeToLiveCap ( int inCap )

Sets the cap for the time to live of forwarded prebroadcasts. Parameters: inCap   the limit value, or 0 to specify no cap.

void k2bShutdown ( )

Halts the konspire2b reference implementation system. Should be called before exiting the program to avoid memory leaks.

void k2bStartup ( int inPort )

Constructs and starts the konspire2b reference implementation system. Must be called before calling any other API calls. Parameters: inPort   the port the local konspire2b node will listen on for connections.

void k2bSubscribeToChannel ( char * inChannelName )

Subscribes to a channel and creates a received directory for the channel if the directory does not exist. Parameters: inChannelName   the name of the channel to subscribe to. Example: k2bSubscribeToChannel( "testChannel" );

void k2bUnsubscribeFromChannel ( char * inChannelName )

Unsubscribes from a channel. Parameters: inChannelName   the name of the channel to unsubscribe from. Example: k2bUnsubscribeFromChannel( "testChannel" );

---