---

konspire2b.h

Go to the documentation of this file.

/*
 * Modification History
 *
 * 2002-July-9   Jason Rohrer
 * Created.
 *
 * 2002-July-10   Jason Rohrer
 * Added functions for startup, shutdown, and log configuration.
 *
 * 2002-July-18   Jason Rohrer
 * Changed all names to avoid conflicts (using OpenGL api as a model).
 * Fixed a macro definition bug. 
 *
 * 2002-July-25   Jason Rohrer
 * Removed external dependency on messages/Broadcast.h from
 * k2bGetPendingBroadcastStatus().
 *
 * 2002-July-31   Jason Rohrer
 * Removed all external dependencies.
 * Added a content type to broadcast initiation functions.
 * Added support for transfer speeds.
 *
 * 2002-August-2   Jason Rohrer
 * Added a function for canceling a pending broadcast receipt.
 *
 * 2002-August-5   Jason Rohrer
 * Fixed errors in documentation.
 *
 * 2002-August-6    Jason Rohrer
 * Added a wanted flag to prebroadcasts.
 *
 * 2002-August-13    Jason Rohrer
 * Changed to create received directories for subscribed channels.
 *
 * 2002-September-8    Jason Rohrer
 * Added support for a user-specified local address.
 *
 * 2002-September-15    Jason Rohrer
 * Added support for a user-specified local address.
 *
 * 2002-September-16    Jason Rohrer
 * Added support for prebroadcast forward probabilities and fuzzy horizons.
 *
 * 2002-September-25    Jason Rohrer
 * Removed local address parameter from startup function.
 * Added functions for getting/setting the local address.
 * Added a function for getting the origin of the local address.
 *
 * 2002-September-26    Jason Rohrer
 * Added support for prebroadcast time to live values.
 *
 * 2002-September-27    Jason Rohrer
 * Added more time to live functions.
 * Removed all fuzzy horizon support.
 *
 * 2002-October-3    Jason Rohrer
 * Added support for sending broadcast series.
 *
 * 2002-October-14    Jason Rohrer
 * Added support for setting number of connections to maintain.
 *
 * 2002-October-29    Jason Rohrer
 * Changed comments to work better with doxygen.
 */



#ifndef KONSPIRE_2B_API_INCLUDED
#define KONSPIRE_2B_API_INCLUDED



#include <stdio.h>



/**
 * @file konspire2b.h
 *
 * 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
 */



/**
 * Constructs and starts the konspire2b reference implementation system.
 *
 * Must be called before calling any other API calls.
 *
 * @param inPort the port the local konspire2b node will listen on
 *   for connections.
 */
void k2bStartup( int inPort );



/**
 * Halts the konspire2b reference implementation system.
 *
 * Should be called before exiting the program to avoid memory leaks.
 */
void k2bShutdown();



#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

/**
 * Sets the logging level used by the reference implementation.
 *
 * @param 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 k2bSetLoggingLevel( int inLoggingLevel );



/**
 * Sets the file to which log messages are written.
 *
 * Defaults to konspire2b.log in the current working directory.
 *
 * @param inLogFilePath path name to the log file.
 *
 * Example: <PRE>
 * k2bSetLogFile( "test.log" );
 * </PRE>
 */
void k2bSetLogFile( char *inLogFilePath );



/**
 * Gets whether the local network address of this node is provided by
 * the network system.
 *
 * @return true if the local address is provided by the network system,
 *   and false if the local address is provided by the user.
 */
char k2bIsLocalAddressProvidedByNetwork();



/**
 * Gets the local network address of this node. 
 */
char *k2bGetLocalHostAddress();



/**
 * Sets the time to live for new prebroadcasts sent by this node.
 *
 * @param inTimeToLive the starting time to live value.
 */
void k2bSetTimeToLive( int inTimeToLive );



/**
 * Gets the time to live for new prebroadcasts sent by this node.
 *
 * @return the starting time to live value.
 */
int k2bGetTimeToLive();



/**
 * Sets the cap for the time to live of forwarded prebroadcasts.
 *
 * @param inCap the limit value, or 0 to specify no cap.
 */
void k2bSetTimeToLiveCap( int inCap );



/**
 * Gets the cap for the time to live of forwarded prebroadcasts.
 *
 * @return the limit value, or 0 to indicate no cap.
 */
int k2bGetTimeToLiveCap();



/**
 * 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.
 *
 * @param inLocalHostAddress the address this node will send out as its
 *   local host address, or NULL to use the address obtainable from the
 *   system.
 */
void k2bSetLocalHostAddress( char *inAddress );



/**
 * Sets the number of connections maintained by this node.
 *
 * @param inTarget the target number of connections to maintain.
 */
void k2bSetTargetNumberOfConnections( int inTarget );



/**
 * Sets the number of connections this node is trying to maintain.
 *
 * @return the target number of connections being maintained..
 */
int k2bGetTargetNumberOfConnections();



/**
 * Adds a host to the local host list.
 *
 * @param inHostAddress the internet address of the host to add.
 * @param inHostPort the konspire2b port of the host to add.
 *
 * Examples: <PRE>
 * k2bAddHost( "k2b.myhost.com", 6089 );
 * k2bAddHost( "128.243.100.9", 6089 );
 * </PRE>
 */
void k2bAddHost( char *inHostAddress, int inHostPort );




/**
 * Gets a list of hosts that the local node is directly connected to.
 *
 * @param 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.
 * @param outHostPorts pointer to location where an array of host ports should
 *   be returned.  The array must be destroyed by caller.
 *
 * @return the number of hosts returned (in other words, the length of
 *   each returned array).
 *
 * Example: <PRE>
 * 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;
 * </PRE>
 */
int k2bGetConnectedHostList( char ***outHostAddresses, int **outHostPorts );



/**
 * Subscribes to a channel and creates a received directory for the channel
 * if the directory does not exist.
 *
 * @param inChannelName the name of the channel to subscribe to.
 *
 * Example: <PRE>
 * k2bSubscribeToChannel( "testChannel" );
 * </PRE>
 */
void k2bSubscribeToChannel( char *inChannelName );



/**
 * Unsubscribes from a channel.
 *
 * @param inChannelName the name of the channel to unsubscribe from.
 *
 * Example: <PRE>
 * k2bUnsubscribeFromChannel( "testChannel" );
 * </PRE>
 */
void k2bUnsubscribeFromChannel( char *inChannelName );



/**
 * Gets a list of subscribed channels.
 *
 * @param 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.
 *
 * @return the number of channel names returned (in other words, the length of
 *   the returned array).
 *
 * Example: <PRE>
 * 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;
 * </PRE>
 */
int k2bGetSubscriptionList( char ***outChannelNames );



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



/**
 * 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.
 *
 * @param inChannelName the channel to send the broadcasts on.
 * @param inNumBroadcasts the number of broadcasts to send.
 * @param inBroadcastNames the name of each broadcast (for example,
 *   the file name, if appropriate).
 * @param inBroadcastComments the comment for each broadcast.
 * @param inFilePath the platform-specific path string locating the
 *   file containing the contents for each broadcast.
 * @param inContentType the MIME type of the content for each broadcast,
 *   or NULL if the content has no type.
 *
 * Example: <PRE>
 * 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;
 * </PRE>
 */
void k2bInitiateBroadcastSeries( char *inChannelName,
                                 int inNumBroadcasts,
                                 char **inBroadcastNames,
                                 char **inBroadcastComments,
                                 char **inFilePaths,
                                 char **inContentTypes );



/**
 * Gets a list of caught prebroadcasts.
 *
 * Note that the reference implementation discards old caught Prebroadcasts,
 * so the returned list is bounded in sized.
 *
 * @param 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.
 * @param 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.
 * @param outComments location where the comments for the caught prebroadcasts
 *   should be returned.
 *   The array and the strings it contains must be destroyed by caller.
 * @param 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.
 * @param outContentLengthsInBytes pointer to location where array of
 *   content lengths for each caught prebroadcast should be returned. 
 *   Must be destroyed by caller.
 * @param 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.
 *
 * @return the number of Prebroadcasts caught (in other words, the length of
 *   each of the returned arrays).
 *
 * Example: <PRE>
 * 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;
 * </PRE>
 */
int k2bGetCaughtPrebroadcasts( char ***outChannelNames,
                               char ***outBroadcastNames,
                               char ***outComments,
                               char ***outContentTypes,
                               unsigned long **outContentLengthsInBytes,
                               char **outWantedFlags );



/**
 * 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".
 *
 * @param inChannelName the name of the channel to generate a key for.
 * @param 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: <PRE>
 * k2bGenerateSenderKeyPair( "testChannel", "sdfj fjsdf u48932 fjk83mv9 df9" );
 * </PRE>
 */
void k2bGenerateSenderKeyPair( char *inChannelName, char *inRandomSeed );



/**
 * 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".
 *
 * @param inChannelName the name of the channel to fetch a key for.
 * @param inKeyURL the URL of the key to download.
 *
 * @return true if fetching the key succeeds, and false if fetching fails.
 *
 * Example: <PRE>
 * char fetched = k2bFetchReceiverKey(
 *     "testChannel",
 *     "http://www.myserver.com/testChan.key" );
 * </PRE>
 */
char k2bFetchReceiverKey( char *inChannelName, char *inKeyURL );



/**
 * Note that the following two functions,
 * getSenderKeyFile() and getReceiverKeyFile(),
 * are provided to avoid external dependency on the location of the key
 * files (for example, in the sender_keys and receiver_keys folders).
 */



/**
 * Gets the path to the sender (private) portion of a key for a channel,
 * if it exists.
 *
 * @param inChannelName the name of the channel to get a key for.
 *
 * @return 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: <PRE>
 * char *filePath = k2bGetSenderKeyFile( "testChan" );
 * if( filePath != NULL ) {
 *     // process file path here
 *     ...
 *     // destroy file path
 *     delete [] filePath;
 *     }
 * </PRE>
 */
char *k2bGetSenderKeyFile( char *inChannelName );



/**
 * Gets the path to the receiver (public) portion of a key for a channel,
 * if it exists.
 *
 * @param inChannelName the name of the channel to get a key for.
 *
 * @return 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: <PRE>
 * char *filePath = k2bGetReceiverKeyFile( "testChan" );
 * if( filePath != NULL ) {
 *     // process file path here
 *     ...
 *     // destroy file path
 *     delete [] filePath;
 *     }
 * </PRE>
 */
char *k2bGetReceiverKeyFile( char *inChannelName );



/**
 * Gets a list of channels for which we have sender keys.
 *
 * @param 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.
 *
 * @return the number of channel names returned (in other words, the length of
 *   the returned array).
 *
 * Example: <PRE>
 * 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 k2bGetChannelsWithSenderKeys( char ***outChannelNames );



/**
 * Gets a list of channels for which we have receiver keys.
 *
 * @param 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.
 *
 * @return the number of channel names returned (in other words, the length of
 *   the returned array).
 *
 * Example: <PRE>
 * 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;
 * </PRE>
 */
int k2bGetChannelsWithReceiverKeys( char ***outChannelNames );




/**
 * 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.
 *
 * @param 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.
 * @param 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.
 * @param outComments location where the comments for the pending broadcasts
 *   should be returned.
 *   The array and the strings it contains must be destroyed by caller.
 * @param 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.
 * @param outContentLengthsInBytes pointer to location where array of
 *   content lengths for each broadcast should be returned. 
 *   Must be destroyed by caller.
 * @param outFractionComplete pointer to location where array of
 *   fraction complete values for each Broadcast should be returned. 
 *   Must be destroyed by caller.
 * @param outKiBPerSecond pointer to location where array of
 *   KiB/sec transfer speed values for each Broadcast should be returned. 
 *   Must be destroyed by caller.
 * @param outCancelFlags pointer to location where array of
 *   cancel flags (true iff cancel pending) for each Broadcast should be
 *   returned. 
 *   Must be destroyed by caller.
 *
 * @return the number of Broadcasts pending (in other words, the length of
 *   each of the returned arrays).
 *
 * Example: <PRE>
 * 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;
 * </PRE>
 */
int k2bGetPendingBroadcastStatus( char ***outChannelNames,
                                  char ***outBroadcastNames,
                                  char ***outComments,
                                  char ***outContentTypes,
                                  unsigned long **outContentLengthsInBytes,
                                  float **outFractionComplete,
                                  float **outKiBPerSecond,
                                  char **outCancelFlags );



/**
 * Cancels receipt of a pending broadcast.
 *
 * @param inChannelName the channel the broadcast is being received on.
 * @param inBroadcastName the name of the pending broadcast.
 */
void k2bCancelPendingBroadcast( char *inChannelName,
                                char *inBroadcastName );



#endif

---