rename class eigerReceiver to EigerReceiver - start class names with a capital letter.

make class EigerReceiver an abstract base class with pure virtual public member functions.
So class EigerReceiver defines the interface, but does not expose the implementation.

Add a preliminary dummy implementation for  EigerReceiver.

Add a test program eigerReceiverTest to test the newly created EigerReceiver class. 
Modify the Makefile accordingly.

Example:

$ make eigerReceiverTest
g++  -DSLS_RECEIVER_FUNCTION_LIST -O3 -DEIGER_RECEIVER     -c -o eigerReceiverTest.o eigerReceiverTest.cpp
g++  -DSLS_RECEIVER_FUNCTION_LIST -O3 -DEIGER_RECEIVER     -c -o eigerReceiver.o eigerReceiver.cpp
g++    eigerReceiverTest.o eigerReceiver.o   -o eigerReceiverTest

$ ./eigerReceiverTest
main: start EigerReceiver tests
create(): Return new EigerReceiverImplementation instance.
initialize() with: detectorHostName= detectors_host_name.
getFileName(): Return some_file_name.
main: got file name some_file_name
getFilePath(): Return some_path.
main: got path name some_path
getDynamicRange(): Return 16.
main: got dynamic range 16.
getScanTag(): return 4711.
main: got scan tag 4711.
setFileName() called with some_other_name.
getFileName(): Return some_file_name.
main: got file name  some_file_name after setting to <some_other_name>
setFilePath() called withsome_other_path.
getFilePath(): Return some_path.
main: got file path  some_path after setting to <some_other_path>
setDynamicRange() called with 8.
getDynamicRange(): Return 16.
main: got dynamic range 16 after setting it to 8.
setNumberOfFrames() called with 11.
getNumberOfFrames(): return 42.
enableFileWrite() called with 1.
startReceiver(): return 0.
stopReceiver(): return 0.
abort(): return 0.
getEnableFileWrite() returns 1.
getDetectorHostname(): Return some_host_name.

HeinerBillich/2014-03-11


git-svn-id: file:///afs/psi.ch/project/sls_det_software/svn/slsDetectorSoftware@766 951219d9-93cf-4727-9268-0efd64621fa3

slsDetectorSoftware/slsReceiver/Makefile

@@ -1,5 +1,6 @@
 CC			=	g++ 
-CLAGS		+=  -DSLS_RECEIVER_FUNCTION_LIST -O3 #-DEIGER_RECEIVER_H
+CFLAGS		+=  -DSLS_RECEIVER_FUNCTION_LIST -O3 -DEIGER_RECEIVER
+CPPFLAGS    = ${CFLAGS}   # for MAC
 LDFLAG=   -L/usr/lib64/ -lpthread -lm  -lstdc++ 
 
 
@@ -45,4 +46,11 @@ lib:
 	cd ../ && $(MAKE) DESTDIR=$(LIBDIR) 
 
 clean:
-	rm -rf $(DESTDIR)/$(PROGS)  *.o 
+	rm -rf $(DESTDIR)/$(PROGS)  *.o  eigerReceiverTest
+
+# EigerDataReceiver
+eigerReceiverTest.o: eigerReceiver.h
+eigerReceiver.o    : eigerReceiver.h
+eigerReceiverTest: eigerReceiver.o eigerReceiverTest.o
+#EOF
+

slsDetectorSoftware/slsReceiver/eigerReceiver.cpp

@@ -0,0 +1,119 @@
+/*
+ * eigerReceiver.cpp
+ *
+ *  Created on: Mar 11, 2014
+ *      Author: billich
+ */
+
+#include <iostream>
+#include <string>
+#include "eigerReceiver.h"
+
+class EigerReceiverImplementation: public EigerReceiver {
+
+public:
+	void initialize(const char *detectorHostName) {
+	 std::cout << "initialize() with: detectorHostName= " << detectorHostName << ".\n";
+	}
+
+	char *getDetectorHostname() {
+		const std::string name = "some_host_name";
+	    char *c = new char[name.length()];
+	    name.copy(c, name.length());
+	    c[name.length()] = '\0';
+        std::cout << "getDetectorHostname(): Return " << c << ".\n";
+	    return(c);
+	}
+
+	char *getFileName() {
+		const std::string name = "some_file_name";
+	    char *c = new char[name.length()];
+	    name.copy(c, name.length());
+	    c[name.length()] = '\0';
+        std::cout << "getFileName(): Return " << c << ".\n";
+	    return(c);
+	}
+
+	char *getFilePath() {
+		std::string name = "some_path";
+	    char *c = new char[name.length()];
+	    name.copy(c, name.length());
+	    c[name.length()] = '\0';
+        std::cout << "getFilePath(): Return " << c << ".\n";
+	    return(c);
+	}
+
+	int getDynamicRange() {
+		std::cout << "getDynamicRange(): Return 16.\n";
+		return(16);
+	}
+
+	int getScanTag() {
+		std::cout << "getScanTag(): return 4711.\n";
+		return(4711);
+	}
+
+	int getNumberOfFrames() {
+		std::cout << "getNumberOfFrames(): return 42.\n";
+		return(42);
+	}
+
+	char * setFileName(const char c[]) {
+		std::cout << "setFileName() called with " << c <<".\n";
+		return(this->getFileName());
+	}
+
+	char * setFilePath(const char c[]) {
+		std::cout << "setFilePath() called with" << c << ".\n";
+		return(this->getFilePath());
+	}
+
+	int getEnableFileWrite() {
+		std::cout << "getEnableFileWrite() returns 1.\n";
+		return(1);
+	}
+	int setDynamicRange (const int dr) {
+		std::cout << "setDynamicRange() called with " << dr << '.' << '\n';
+		return(this->getDynamicRange());
+	}
+
+	int setScanTag (const int tag) {
+		std::cout << "setScanTag() called with " << tag << ".\n";
+		return(this->getScanTag());
+	}
+
+	int setNumberOfFrames (const int fnum) {
+		std::cout << "setNumberOfFrames() called with " << fnum << ".\n";
+		return(this->getNumberOfFrames());
+	}
+
+	int setEnableFileWrite(const int i) {
+		std::cout << "enableFileWrite() called with " << i << ".\n";
+		return(0);
+	}
+
+	int startReceiver(char message[]) {
+		std::cout << "startReceiver(): return 0.\n";
+		message = NULL;
+		return(0);
+	}
+
+	int stopReceiver() {
+		std::cout << "stopReceiver(): return 0.\n";
+		return(0);
+	}
+
+	void abort() {
+		std::cout << "abort(): return 0.\n";
+	}
+
+};
+
+EigerReceiver *EigerReceiver::create(void) {
+	std::cout << "create(): Return new EigerReceiverImplementation instance.\n";
+	return new EigerReceiverImplementation();
+}
+
+
+
+

slsDetectorSoftware/slsReceiver/eigerReceiver.h

@@ -1,147 +1,206 @@
-#ifdef EIGER_RECEIVER_H
-/********************************************//**
+
+#ifdef EIGER_RECEIVER
+
+#ifndef EIGERRECEIVER_H
+#define EIGERRECEIVER_H
+/***********************************************
  * @file eigerReceiver.h
  * @short does all the functions for a receiver, set/get parameters, start/stop etc.
  ***********************************************/
 
-
-
-
 /**
  * @short does all the functions for a receiver, set/get parameters, start/stop etc.
  */
 
-class eigerReceiver{ /** public slsDetectorDefs Its an enum unders slsDetectorsPackage/slsDetectorSoftware/commonFiles/slsDetectorDefs.h
+class EigerReceiver {
+	/* abstract class that defines the public interface of an eiger data receiver.
+	 *
+	 * Use the factory method EigerReceiver::create() to get an instance:
+	 *
+	 *      EigerReceiver *receiver = EigerReceiver::create()
+	 *
+	 *  supported sequence of method-calls:
+	 *
+	 *  initialize() : once and only once after create()
+	 *
+	 *  get*()       : anytime after initialize(), multiples times
+	 *  set*()       : anytime after initialize(), multiple times
+	 *
+	 *  startReceiver(): anytime after initialize(). Will fail if state already is 'running'
+	 *
+	 *  abort(),
+	 *  stopReceiver() : anytime after initialize(). Will do nothing if state already is idle.
+	 *
+	 *  getStatus() returns the actual state of the data receiver - running or idle. All other
+	 *  get*() and set*() methods access the local cache of configuration values only and *do not* modify the data receiver settings.
+	 *
+	 *  Only startReceiver() does change the data receiver configuration, it does pass the whole configuration cache to the data receiver.
+	 *
+	 *  get- and set-methods that return a char array (char *) allocate a new array at each call. The caller is responsible to free the allocated space:
+	 *
+	 *      char *c = receiver->getFileName();
+	 *          ....
+	 *      delete[] c;
+	 *
+	 *  always: 1:YES       0:NO      for int as bool-like arguments
+	 *
+	 */
 
 public:
+
 	/**
-	 * Constructor
+	 * factory method to create instances
 	 */
-	eigerReceiver();
+	static EigerReceiver *create();
 
 	/**
 	 * Destructor
 	 */
-	virtual ~eigerReceiver();
+	virtual ~EigerReceiver() {};
 
 	/**
 	 * Initialize the Receiver
 	 @param detectorHostName detector hostname
+	 * you can call this function only once. You must call it before you call startReceiver() for  the first time.
 	 */
-	void initialize(char* detectorHostName);
+	virtual void initialize(const char *detectorHostName) = 0;
+
+	/**
+ 	 * Set detector hostname
+ 	 @param c hostname
+ 	 /returns hostname
+ 	 */
+ 	/*FIXME: char* setDetectorHostname(char c[]);  Can/want we support this setter function? Can't change after initialization */
+
+	 /* Returns detector hostname
+ 	 /returns hostname
+ 	  * caller needs to deallocate the returned char array.
+ 	 */
+ 	virtual char *getDetectorHostname() = 0;
 
 	/**
 	 * Returns status of receiver: idle, running or error
 	 */
-	runStatus getStatus();
+	/*FIXME: need to implement runStatus getStatus();*/
+ 	/* the struct slsDetectorDefs is available in  slsDetectorsPackage/slsDetectorSoftware/commonFiles/slsDetectorDefs.h */
 
-	/**
-	 * Returns detector hostname
-	 /returns hostname
-	 */
-	char* getDetectorHostname();
 
 	/**
 	 * Returns File Name
+	 * caller is responsible to deallocate the returned char array.
 	 */
-	char* getFileName();
+	virtual char *getFileName() = 0;
+
 
 	/**
 	 * Returns File Path
+	 * caller is responsible to deallocate the returned char array
 	 */
-	char* getFilePath();
+	virtual char *getFilePath() = 0; //FIXME: Does the caller need to free() the returned pointer?
+
 
 	/**
 	 * Returns the number of bits per pixel
 	 */
-	int getDynamicRange();
+	virtual int getDynamicRange() = 0;
 
 	/**
 	 * Returns scan tag
 	 */
-	int getScanTag();
+	virtual int getScanTag() = 0;
+
+	/*
+	 * Returns number of frames to receive
+	 * This is the number of frames to expect to receiver from the detector.
+	 * The data receiver will change from running to idle when it got this number of frames
+	 */
+	virtual int getNumberOfFrames() = 0;
 
 	/**
-	 * Returns number of frames
-	 */
-	int getNumberOfFrames();
-
-	/**
-	 * Returns file write enable
-	 */
-	int getEnableFileWrite();
-
-	/**
-	 * Set detector hostname
-	 @param c hostname
-	 /returns hostname
-	 */
-	char* setDetectorHostname(char c[]);
+	* Returns file write enable
+	* 1: YES 0: NO
+	*/
+	virtual int getEnableFileWrite() = 0;
 
 	/**
 	 * Set File Name (without frame index, file index and extension)
 	 @param c file name
 	 /returns file name
+	  * returns NULL on failure (like bad file name)
+	  * does not check the existence of the file - we don't know which path we'll finally use, so no point to check.
+	  * caller is responsible to deallocate the returned char array.
 	 */
-	char* setFileName(char c[]);
+	virtual char* setFileName(const char c[]) = 0;
 
 	/**
 	 * Set File Path
 	 @param c file path
 	 /returns file path
+	  * checks the existence of the directory. returns NULL if directory does not exist or is not readable.
+	  * caller is responsible to deallocate the returned char array.
 	 */
-	char* setFilePath(char c[]);
+	virtual char* setFilePath(const char c[]) = 0;
 
 	/**
 	 * Returns the number of bits per pixel
 	 @param dr sets dynamic range
 	 /returns dynamic range
+	  * returns -1 on failure
+	  * FIXME: what are the allowd values - should we use an enum as argument?
 	 */
-	int setDynamicRange(int dr);
+	virtual int setDynamicRange(const int dr) = 0;
+
 
 	/**
 	 * Set scan tag
 	 @param tag scan tag
-	 /returns scan tag
+	 /returns scan tag (always non-negative)
+	  * FIXME: valid range - only positive? 16bit ore 32bit?
+	  * returns -1 on failure
 	 */
-	int setScanTag(int tag);
+	virtual int setScanTag(const int tag) = 0;
 
 	/**
 	 * Sets number of frames
 	 @param fnum number of frames
 	 /returns number of frames
 	 */
-	int setNumberOfFrames(int fnum);
+	virtual int setNumberOfFrames(const int fnum) = 0;
 
 	/**
 	 * Set enable file write
 	 * @param i file write enable
 	 /returns file write enable
 	 */
-	int setEnableFileWrite(int i);
+	virtual int setEnableFileWrite(const int i) = 0;
 
 	/**
-	 * Starts Receiver - starts to listen for packets
+	 * Starts Receiver - activate all configuration settings to the eiger receiver and start to listen for packets
 	 @param message is the error message if there is an error
-	 /returns success
+	 /returns 0 on success or -1 on failure
 	 */
-	int startReceiver(char message[]);
+	//FIXME: success == 0 or success == 1?
+	virtual int startReceiver(char message[]) = 0; //FIXME: who allocates message[]?
 
 	/**
 	 * Stops Receiver - stops listening for packets
 	 /returns success
+	  * same as abort(). Always returns 0.
 	 */
-	int stopReceiver();
+	virtual int stopReceiver() = 0;
 
 	/**
-	 * abort program with minimum damage
+	 * abort acquisition with minimum damage: close open files, cleanup.
+	 * does nothing if state already is 'idle'
 	 */
-	void abort();
+	virtual void abort() = 0;
 
+protected:
 
 private:
 	
 };
 
-#endif
+#endif  /* #ifndef EIGERRECEIVER_H */
+#endif  /* #ifdef EIGER_RECEIVER */
 

slsDetectorSoftware/slsReceiver/eigerReceiverTest.cpp

@@ -0,0 +1,61 @@
+/*
+ * eigerReceiverTest.cpp
+
+ *
+ *  Created on: Mar 11, 2014
+ *      Author: billich
+ */
+
+#include <iostream>
+#include <string>
+#include "eigerReceiver.h"
+
+int main(int argc, char *argv[]){
+
+	const char *name = "detectors_host_name";
+	std::string prefix = "main: ";
+	std::cout <<prefix<< "start EigerReceiver tests\n";
+
+	EigerReceiver *receiver = EigerReceiver::create();
+	receiver->initialize(name);
+
+	char *c1 = receiver->getFileName();
+	std::cout <<prefix<< "got file name " << c1 << '\n';
+	delete[] c1;
+
+	char *c2 = receiver->getFilePath();
+	std::cout <<prefix<< "got path name " << c2 << '\n';
+	delete[]c2;
+
+	int range = receiver->getDynamicRange();
+	std::cout <<prefix<< "got dynamic range " << range << ".\n";
+
+	int tag = receiver->getScanTag();
+	std::cout <<prefix<< "got scan tag " << tag << ".\n";
+
+	char *c3 = receiver->setFileName( "some_other_name");
+	std::cout <<prefix<< "got file name  " << c3 << " after setting to <some_other_name>\n";
+	delete[] c3;
+
+	char *c4 = receiver->setFilePath( "some_other_path");
+	std::cout <<prefix<< "got file path  " << c4 << " after setting to <some_other_path>\n";
+	delete[] c4;
+
+	range = receiver->setDynamicRange(8);
+	std::cout <<prefix<< "got dynamic range "  << range << " after setting it to 8.\n";
+
+	int n = receiver->setNumberOfFrames(11);
+	int w = receiver->setEnableFileWrite(1);
+
+	char *c5;
+	receiver->startReceiver(c5);
+	receiver->stopReceiver();
+	receiver->abort();
+	receiver->getEnableFileWrite();
+	char *c6 = receiver->getDetectorHostname();
+	delete[] c6;
+}
+
+
+
+