macedon_api.h

这是一个著名的应用层组播中间件的源码

//Copyright (c) 2004, Charles Killian, Adolfo Rodriguez, Dejan Kostic, Sooraj Bhat, and Amin Vahdat
//All rights reserved.
//
//Redistribution and use in source and binary forms, with or without
//modification, are permitted provided that the following conditions are met:
//
//   * Redistributions of source code must retain the above copyright
//     notice, this list of conditions and the following disclaimer.
//   * Redistributions in binary form must reproduce the above copyright
//     notice, this list of conditions and the following disclaimer in
//     the documentation and/or other materials provided with the
//     distribution.
//   * Neither the names of Duke University nor The University of
//     California, San Diego, nor the names of its contributors
//     may be used to endorse or promote products derived from
//     this software without specific prior written permission.
//
//THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
//AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
//IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
//DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
//FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
//DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
//SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
//CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
//OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
//USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

#ifndef macedon_api_h
#define macedon_api_h

#include "params.h"
#include "scheduler.h"

// Defines standard types of neighbors
#define NBR_TYPE_PARENT 1
#define NBR_TYPE_CHILDREN 2
#define NBR_TYPE_PEER 3
#define NBR_TYPE_TREE 4

// Defines communication semantics
#define COMM_TYPE_UNICAST 1
#define COMM_TYPE_MULTICAST 2
#define COMM_TYPE_COLLECT 3
#define COMM_TYPE_ANYCAST 4

// Defines transport priority (0 - 10)
#define PRIORITY_HIGHEST 10
#define PRIORITY_HIGH 8
#define PRIORITY_MED 6
#define PRIORITY_LOW 4
#define PRIORITY_BEST_EFFORT 0

// Definitions of status codes passed into status_changed
#define STATUS_READY 0
#define STATUS_UNREADY 1

// Defines standard error codes
#define ERROR_NEIGHBOR_FAILURE 5
#define ERROR_JOIN 6

extern params parameters;

// For now assume IP address is just an int and a hash is of type key.
#define macedon_key int

class macedon_Agent;

//*********** Overlay calls these application functions  *********
// These applications are registered by the application or higher-layer
// protocol implementation (such as Scribe).
// These are actually declared in macedon.h, but copied here for 
// completeness.

// Called by overlay at each hop during forwarding of a packet via the 
// overlay.  
// Returns 0 if data is to be forwarded, 1 otherwise.
typedef int ( *macedon_forward_handler) (char *msg, int size, int type, int nextHop, macedon_key nextHopKey); 

// Overlay calls this funtion to deliver data to a final destination (the
// last hop of a route message or the destination of a message sent via 
// sendmsg.  Type specifies multicast or collect.
typedef void ( *macedon_deliver_handler) (char *msg, int size, int type); 

// Overlay calls this function when a neighbor set has changed.  NBR_CLASS_* indicate
// the types of valid classes (PARENT, CHILDREN, PEERS, etc).
typedef void ( *macedon_notify_handler) (int type, int size, int *neighbors); 

// Overlay calls this when an error has occured.
typedef void ( *macedon_error_handler) (int type, int aux); 

// Overlays can extend the API using upcalls and downcalls.
typedef int ( *macedon_upcall_handler) (int operation, void *arg); 

//****************************************************************** 


//*********** App calls these overlay functions  *****************

// Initialize the protocol to use.  The bootstrap_node is the IP address
// of the known rendezvous node used by the agent.  The protocol value
// specifies the MACEDON assigned protocol value.  
// Returns:  0 on no error
macedon_Agent *macedon_init(int bootstrap_node, int protocol);    

class macedon_Agent 
{
public:
  macedon_Agent() {}
  ~macedon_Agent() {}

  int local_addr;
  // Exits the overlay.
  void macedon_exit();

  // The API call to initialize the overlay.  Called automagically for now.
  virtual void macedon_init()=0;
  
  // Generic downcall facility
  virtual int macedon_downcall_ext(int operation, void *arg)=0;
  
  // Register forward and deliver handlers.
  virtual void macedon_register_handlers(macedon_forward_handler, macedon_deliver_handler, macedon_notify_handler=0, macedon_upcall_handler=0)=0;
  
  // Sleeps for specified time in seconds
  void macedon_wait(double sleep_time);
  
  // Create a multicast/collect session.  This is done by the source of
  // the data in the cast of multicast and the receiver in the case of
  // collect.  The group's id is passed an arg.
  // Returns:  0 on no error
  virtual int macedon_create_group(macedon_key groupID)=0; 
  
  // Join a multicast/collection session.  This is done by all receivers
  // in multicast and by all senders in collect.  The group's id is specified.
  virtual void macedon_join(macedon_key groupID)=0; 
  
  // Leave a multicast/collection session.  This is done by all receivers
  // in multicast and by all senders in collect.  The group's id is specified.
  virtual void macedon_leave(macedon_key groupID)=0; 
  
  // Send a key via the overlay to the destination hash value.  The
  // destination (hash) is input as well as the message to send;
  // Returns:  0 on no error
  virtual int macedon_route(macedon_key dest, char *msg, int size, int priority)=0;  
  
  // Send a message directly to a node using IP address.  This goes over
  // the IP network directly (no overlay) if the address mapping is known.  
  // The hash address is used.
  // Returns:  0 on no error
  virtual int macedon_routeIP(macedon_key dest, char *msg, int size, int priority)=0;   
  
  // Multicast a message to group specified
  // Returns:  0 on no error
  virtual int macedon_multicast(macedon_key groupID, char *msg, int size, int priority)=0; 
  
  // Multicast a message to group specified
  // Returns:  0 on no error
  virtual int macedon_anycast(macedon_key groupID, char *msg, int size, int priority)=0; 
  
  // Send a message toward the root of the tree through the overlay.
  // macedon_forward() is called at each hop along the way.
  // Returns:  0 on no error
  virtual int macedon_collect(macedon_key groupID, char *msg, int size, int priority)=0;

  // Trace function.
  virtual void trace_print()=0;
};
//+***************************************************************** 

#endif