===== SteereoCommunicator =====

==== Description ====
This is the base class and interface definition for all communicators like the [[steereo:classes:steereosocketcommunicator|SteereoSocketCommunicator]].
The Communicators are used to accept connections to clients (or connect to simulations if you are the client) and sending data between simulation and client. 

==== Functions ====

=== If you want to implement your own communicator ===
This are the functions you have to implement in your own communicator:
  * <code cpp> ssize_t writen(SteereoSingleConnection* fd, const void *vptr, size_t n) </code> <code cpp> ssize_t writen(SteereoSingleConnection* fd, const char* ptr, size_t n, int flags) </code> Specify how //n// bytes of the data pointed to from //vptr// or //ptr// are written over the [[steereo:classes::steereosingleconnection|connection]] //fd//. 
  * <code cpp> ssize_t readn(SteereoSingleConnection* fd, void *vptr, size_t n) </code> <code cpp> ssize_t readn(SteereoSingleConnection* fd, char *ptr, size_t n, int flags) </code> Specify how //n// bytes of the data can be read from the connection //fd// to the memory pointed at by //vptr// or //ptr//.
  * <code cpp> int startConnection (SteereoSingleConnection** partner, const std::string ip, std::string connPort) </code> Specify how to connect to //ip// at "port" //connPort// and return a adequate [[steereo:classes:steereosingleconnection|SteereoSingleConnection]] which identifies the connection. The semantic of the last two parameters can of course vary with the type of the communicator. For example with MPI you wouldn't use the //ip// parameter and the //connPort// would be some previously published string.
  * <code cpp> SteereoSingleConnection* startListening (std::string listenPort) </code> With this function you would listen for incoming data at port //listenPort// (usually you will do that in simulations) and return the adequate "connection".
  * <code cpp> void acceptConnection(SteereoSingleConnection* listenfd, SteereoSingleConnection** acceptfd) </code> Specify here how to accept incoming connections given the listening "connection" and return the connection data in //acceptfd//.

=== Functions to use the communicator ===
The functions //startConnection//, //startListening// and //acceptConnection// from above are of course also needed for the daily usage of communicators. Other than that
you will do communication with these functions, which are based on the ones in the previous section:
  * <code cpp> void sendStream (SteereoSingleConnection* dest, SteereoStream& stream, steereoCompression* compression=NULL) </code> <code cpp> void receiveStream (SteereoSingleConnection* src, SteereoStream* stream, steereoCompression* compression=NULL) </code> send/receive the [[steereo:classes:steereostream|SteereoStream]] //stream// which may be compressed using the [[steereo:classed:steereoCompression|SteereoCompression]]//compression// over the connection //dest// / //src//.
  * <code cpp> void sendString (SteereoSingleConnection* dest, std::string request) </code> <code cpp> void sendInteger (SteereoSingleConnection* dest, int data) </code> <code cpp> void sendDouble (SteereoSingleConnection* dest, double data) </code> <code cpp> void receiveString (SteereoSingleConnection* src, std::string* data) </code> <code cpp> void receiveInteger (SteereoSingleConnection* src, int* data) </code> <code cpp> void receiveDouble (SteereoSingleConnection* src, double *d) </code> sending/receiving strings or integer or doubles. May be used when you really want to send/receive only one value. Otherwise you should use a [[steereo:classes:steereostream|SteereoStream]] and use the functions above.