//
// CRAM: CREATE Real-time Applications Manager
// See the copyright and acknowledgment of authors in the file COPYRIGHT
//
//	CRAM.idl -- Pseudo-IDL for the CRAM "CORBA-lite" protocol
//
//	NB: This IDL is not used (since CRAM3 does not use CORBA); 
//	it is included for documentation purposes only
//

// Program interface -- all CRAM components are programs

interface Program {
						// Status flags
	enum Status{ AOK, Warning, Error, Unknown, ... };
	
	Status ping(void);							// Ping message; answer AOK status
	Status test(void);							// test message, test app status and answer ports, timestamp, etc.
	string get_name(void);						// Get_name message
	string get_log(in int max_len);				// Get a program's log messages
	string get_log_after(in int offset);		// Get the tail of a program's log messages
	string truncate_log(in int max_len);		// Truncate a program's log file
	
	Status set_options(in string data);			// Configure this instance (interpretation is left up to subclasses)
	Status set_option(in string name, value);	// Configure this instance (interpretation is left up to subclasses)
	<Sequence string> get_options();			// Get the instance's configuration options/values

	Status emergency_ping_verbose(void);		// emergency thread's ping message
	<Sequence short> emergency_ports(void);		// get listener ports message
	Status emergency_restart(void);				// restart message

					// Low-level safe socket operations
												// Safe_open creates and binds to a socket with exception handling
	int safe_open(int * ssoc, unsigned short port, struct sockaddr_in * scln);
												// Safe_send retries multiple writes to a socket; 
												// returns bytes sent or error code
	int safe_send(int ssoc, char * buf, unsigned ssiz, sockaddr * scln);
												// Safe_recv times-out, has several levels of retry, 
	int safe_recv(int ssoc, char * buf, unsigned ssiz, sockaddr * scln, int * addr_len, int stimeo, int srtry);
												// safe strlen (essentially str_n_len) returns null if string 
												// is longer than max
	int safe_strlen(char * src, unsigned max);
												// scan arguments from a packet (like scanf)
	int scan_packet(CRAMPacketHeader * pkt, char * format, ...);
												// print onto a packet (like printf)
	int print_packet(CRAMPacketHeader * pkt, char * format, ...);
	
};

// Server interface (this is included in CRAM-managed servers)

interface Server : Program {

	Status initialize();		// pre-start set-up
	Status start(void);			// this usually starts your app
	Status stop(void);			// this usually calls exit()
	Status suspend(void);		// might be ignored
	Status resume(void);		// might be ignored
	
};

// Node (manager) interface

interface Node : Program {
						// Starting a service; name is arbitrary, command is fully qualified
	status create_service(in string name, in string command, in string arguments);
						// Kill a service
	status void start_service(in string name);
	status void stop_service(in string name);
	status void suspend_service(in string name);
	status void resume_service(in string name);

	status void ping_service(in string name);
	status void ping_v_service(in string name);
	status void watch_service(in string name);
	status void watch_allmServices(in string name);
	
	status void ping_node(in string name);
	status void ping_node_careful(in string name);
	
	status void get_servicemLog(in string name, short len);

						// List the names of the services the manager knows about
	Sequence(string) listmServices(void);
	
						// machine statistics struct
	struct statistics { int CPU, int Mem, int Disk, int Network };
			
	statistics get_statistics(void);	// Message to query about resource usage (answer estimated %)
	Sequence(int) get_benchmarks(void);	// Message to get a node's estimated performance (answer MIPS/MFLOPS)
	int get_time(void);					// Message to query a node's msec clock

	void reset();
	
};


About the CRAM packet format

Every CRAM message uses the same header structure (12 bytes)

typedef struct {
	unsigned magic;				// Magic number (=0x004200XX, whereby XX is the command)
	unsigned short size;		// Size of packet (including header) (used also as error flag upon return)
	unsigned short sequence;	// Packet sequence number
	int value;					// Argument or return value
} CRAMPacketHeader;

As an example, the ping message looks like

	Bytes	Value
	4		Magic number | ping command flag = 0x00420040
	2		8 (packet size)
	2		1 (sequence number)
	4		0 (no argument)
	
The response to ping simply overwrites the structure's value field with the status flag cramAOK.


