---

libcomm.h File Reference

Definitions for libcomm. More...

#include <stdio.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>
#include <pthread.h>

Go to the source code of this file.

Data Structures
struct	AUTHINFO
struct	LIBCOMMPTHREADP
struct	LIBCOMMPTHREADS
struct	LINEMONITOR_THREAD_DATA
Defines
#define	true   1
#define	false   0
#define	authfile0   "./libcomm_md5auth.pwd"
#define	authfile1   "/etc/libcomm_md5auth.pwd"
#define	authfilefieldseperator   ':'
#define	authfilemaxlinelenght   4096
#define	authrandomstringsize   (int) 16
#define	authmessagetype   65535
Functions
int	socket_md5auth (int fd, char *netname, char *name, struct AUTHINFO **locallogin, struct AUTHINFO **remotelogin)
	Do both side authentification. More...
AUTHINFO *	getauthinfo (char *netname, char *name)
	Load authentication informations (netname, name, passwd, keyencrypt, keydecrypt) from authfile. More...
void	socket_accept_thread (struct LIBCOMMPTHREADP *libcommpthreadp)
	This is a part of socket_accept() and must not called from the user. More...
int	socket_accept (int sockport, int id, void(*socket_accept_do)(int fd, int id, char *pip, struct sockaddr_in their_addr))
	Start a new thread, wait for connections and start socket_accept_do() when someone connects. More...
void	thread1 (struct LIBCOMMPTHREADS *libcommpthreads)
	This is a part of block_call() and must not called from the user. More...
int	block_call (int fd, int id, int term, void(*block_call_do)(int fd, int id, unsigned int type, char *buf, unsigned int size, int term), void(*block_call_term)(int fd, int id))
	Waits in a new thread for a datablock to be received and calls the function block_call_do() if this event occurs or block_call_term() when the connection terminates. More...
char *	block_receive_poll (int fd, unsigned int *type, char *buf, unsigned int *size, unsigned int maxsize, int term)
	Test if is there data available on the socket's input buffer and starts receiving a block if there is. More...
char *	block_receive (int fd, unsigned int *type, char *buf, unsigned int *size, unsigned int maxsize, int term)
	Receive a block (composition of: type, size of datablock and datablock) from a socket. More...
int	block_receive_integer (int fd, unsigned int *recvi)
	Receive an integer (two bytes; 16Bit) from the socket. More...
int	block_receive_nbytes (int fd, char *buf, int n)
	Receive n bytes from socket. More...
int	block_send (int fd, unsigned int type, char *buf, unsigned int size)
	Send a block (composition of: type, size of datablock and datablock (buf)) to a socket. More...
char *	block_random (char *buf, int size)
	Get random numbers/bytes. More...
int	socket_bind (int port, int cqueue)
	Bind a socket to a port (Server side). More...
int	socket_connect (char *host, int port)
	Connect a TCP-stream to a server (Client side). More...
void	linemonitor_server_thread (struct LINEMONITOR_THREAD_DATA *linemonitor_thread_data)
	Thread used by linemonitor_server() NOT for direct usage. More...
int	linemonitor_server (int port, int soft_msec, int hard_msec, int wait_msec, void(*linemonitor_exception)(char *server, int port, int type))
	Monitor if the "line" is fast enough: Server Application. More...
void	linemonitor_emergencystop (int sock)
	Sends an "Emergency Stop" to the client's side, linemonitor() will produce an "Emergency Stop" exception (type 4). More...
int	linemonitor_thread (struct LINEMONITOR_THREAD_DATA *linemonitor_thread_data)
	Thread used by linemonitor() NOT for direct usage. More...
int	linemonitor (char *server, int port, int soft_msec, int hard_msec, int wait_msec, void(*linemonitor_exception)(char *server, int port, int type))
	Monitor if the "line" is fast enough: Client/Robot Application. More...

---

Detailed Description

Definitions for libcomm.

---

Define Documentation

#define authfile0   "./libcomm_md5auth.pwd"

#define authfile1   "/etc/libcomm_md5auth.pwd"

#define authfilefieldseperator   ':'

#define authfilemaxlinelenght   4096

#define authmessagetype   65535

#define authrandomstringsize   (int) 16

#define false   0

#define true   1

---

Function Documentation

int block_call (  int    fd, int    id, int    term, void(*    block_call_do)(int fd, int id, unsigned int type, char *buf, unsigned int size, int term), void(*    block_call_term)(int fd, int id) )

Waits in a new thread for a datablock to be received and calls the function block_call_do() if this event occurs or block_call_term() when the connection terminates. Parameters: fd  (int) descriptor of socket id  (int) arbitrary id of background process / thread term  (int) 0: do not terminate the buffer, 1: terminate the buffer by appending a 0x00. block_call_do  (int fd, int id, unsigned int type, char *buf, unsigned int size, int term) (function) this function is called if a datablock was received. fd, id and term are the same as in block_call(). type describes the type of the received datablock, buf is a pointer to this datablock and size is the number of bytes of the datablock block_call_term  (int fd, int id) (function) this function is called if the connection terminates. fd and id are the same as in block_call(). Returns: If all right zero otherwise non zero.

char* block_random (  char *    buf, int    size )

Get random numbers/bytes. This function reads random numbers/bytes from /dev/urandom and stores this bytes in a buffer. Parameters: buf  (char *) in which the bytes will be stored. If this parameter is equal to NULL dynamic memory will be allocated. size  an integer, specifies ths size of the buffer (the number of the random bytes). WARNING: If buf is not equal to null, n*(size) bytes will be stored in this buffer without any check of ths size of this buf. Returns: (char *) a pointer to the buffer in which the random bytes are stored.

char* block_receive (  int    fd, unsigned int *    type, char *    buf, unsigned int *    size, unsigned int    maxsize, int    term )

Receive a block (composition of: type, size of datablock and datablock) from a socket. Waits for a block to be received completely. WARNING: The integers (type and size; excluding fd) are only 16 bit values (0 - 65535). Parameters: fd  (int) descriptor of socket type  (unsigned int *) pointer to integer, this value can be used as buyer's option buf  (char *) buffer for datablock. Memory will be allocated if this parameter is equal to null. size  (unsigned int *) pointer to integer in which the size of the received datablock is saved. maxsize  (unsigned int *) describes size of buf. This parameter will be ignored if buf is equal to null. term  (int) 0: do not terminate the buffer, 1: terminate the buffer by appending a 0x00. Returns: (char *) pointer to buffer which contains the received datablock; NULL if fail.

int block_receive_integer (  int    fd, unsigned int *    recvi )

Receive an integer (two bytes; 16Bit) from the socket. Parameters: fd  (int) descriptor of socket recvi  (unsigned int *) pointer to integer in which the received integer is saved. Returns: (int) 2: OK; -1: fail

int block_receive_nbytes (  int    fd, char *    buf, int    n )

Receive n bytes from socket. Parameters: fd  (integer) descriptor of socket buf  (char *) buffer for saving the received bytes n  (integer) number of bytes to receive Returns: (integer) n: OK; -1 fial

char* block_receive_poll (  int    fd, unsigned int *    type, char *    buf, unsigned int *    size, unsigned int    maxsize, int    term )

Test if is there data available on the socket's input buffer and starts receiving a block if there is. WARNING: The integers (type and size; excluding fd) are only 16 bit values (0 - 65535). Parameters: fd  (int) descriptor of socket type  (unsigned int *) pointer to integer, this value can be used as buyer's option buf  (char *) buffer for datablock. Memory will be allocated if this parameter is equal to null. size  (unsigned int *) pointer to integer in which the size of the received datablock is saved. maxsize  (unsigned int *) describes size of buf. This parameter will be ignored if buf is equal to null. term  (int) 0: do not terminate the buffer, 1: terminate the buffer by appending a 0x00. Returns: (char *) pointer to buffer which contains the received datablock; NULL if fail; 1 if no data available.

int block_send (  int    fd, unsigned int    type, char *    buf, unsigned int    size )

Send a block (composition of: type, size of datablock and datablock (buf)) to a socket. The function blocks until the whole block is transfered to the buffer. If the buffer is full, data has to be sent first. WARNING: The integers (type and size; excluding fd) are only 16 bit values (0 - 65535). Parameters: fd  (int) descriptor of the socket to which buf should send type  (unsigned int) This value can be used as buyer's option buf  (char *) which should be send Returns: number of sent bytes, -1 if an error is occurt.

struct AUTHINFO* getauthinfo (  char *    netname, char *    name )

Load authentication informations (netname, name, passwd, keyencrypt, keydecrypt) from authfile. Parameters: netname  (char *) specify the network name (may IP). NULL not specified. name  (char *) specity the login name. NULL not specified. Returns: (struct AUTHINFO *) the first entry from authfile which matches network name OR login name. If both values are NULL, the first entry of the authfile is given back.

int linemonitor (  char *    server, int    port, int    soft_msec, int    hard_msec, int    wait_msec, void(*    linemonitor_exception)(char *server, int port, int type) )

Monitor if the "line" is fast enough: Client/Robot Application. This function opens a socket stream, sents pings/bytes and wait for them to come back. The soft-timeout will called after soft_msec is timeouted. The hard-timeout will called after soft-timeout was called AND hard_msec is timeouted. wait_msec specifies the time which is waited after a ping is received befor the next one will be launched. Parameters: server  (char *) server to be connected port  (int) port to be connected soft_msec  (int) timeout in milliseconds which causes soft-real-time exception. hard_msec  (int) timeout in milliseconds which causes hard-real-time exception. wait_msec  (int) timeout for resent -- sending of the next ping. linemonitor_exception  (pointer to function) This function will be called if an exception occurs. It becomes the following parameters: server name (char *) which is always null, port (int): listend port and type (int) of exception which can be: 0: Connicion Fault, 1: Soft Real Time Exception, 2: HARD Real Time Exception, 3: Transmission Fault, 4: Emergency Stop.

void linemonitor_emergencystop (  int    sock )

Sends an "Emergency Stop" to the client's side, linemonitor() will produce an "Emergency Stop" exception (type 4).

int linemonitor_server (  int    port, int    soft_msec, int    hard_msec, int    wait_msec, void(*    linemonitor_exception)(char *server, int port, int type) )

Monitor if the "line" is fast enough: Server Application. This function opens a port and wait for the first connection on this port. All data/pings which is sent by this first connection will be sent back. The soft-timeout will called after wait_msec AND soft_msec is timeouted. The hard-timeout will called after soft-timeout was called AND hard_msec is timeouted. Parameters: port  (int) port which should be listend soft_msec  (int) timeout in milliseconds which causes soft-real-time exception. hard_msec  (int) timeout in milliseconds which causes hard-real-time exception. wait_msec  (int) timeout for resent -- sending of the next ping. linemonitor_exception  (pointer to function) This function will be called if an exception occurs. It becomes the following parameters: server name (char *) which is always null, port (int): listend port and type (int) of exception which can be: 0: Connicion Fault, 1: Soft Real Time Exception, 2: HARD Real Time Exception. Returns: (int) Filediscriptor to the used socket. Only for usage with linemonitor_emergencystop().

void linemonitor_server_thread (  struct LINEMONITOR_THREAD_DATA *    linemonitor_thread_data )

Thread used by linemonitor_server() NOT for direct usage.

int linemonitor_thread (  struct LINEMONITOR_THREAD_DATA *    linemonitor_thread_data )

Thread used by linemonitor() NOT for direct usage.

int socket_accept (  int    sockport, int    id, void(*    socket_accept_do)(int fd, int id, char *pip, struct sockaddr_in their_addr) )

Start a new thread, wait for connections and start socket_accept_do() when someone connects. Parameters: sockport  (int) descriptor of a tcp socket/port from socket_bind() id  (int) arbitrary id of background process / thread. (May be it is a good idea to use the portnumber.) aocket_accept_do  (int fd, int id, char *pip, struct sockaddr_in their_addr) (function) this function is called if somebody connects. fd is the descriptor of the new socket to the connected tcp-tream. id is the same as in socket_accept(). pip contains the ip-address of the connected client. The structure their_addr contails all known information about the connected client. Returns: If all right zero otherwise non zero.

void socket_accept_thread (  struct LIBCOMMPTHREADP *    libcommpthreadp )

This is a part of socket_accept() and must not called from the user. This function is the thread which is started from socket_accept() and runs in background.

int socket_bind (  int    port, int    cqueue )

Bind a socket to a port (Server side). This function creates a socket and binds it to a local port. Parameters: port  an integer which specifies the port cqueue  an integer how many pending connections queue will hold in the waiting queue. Returns: The File Descriptor (FD) which allows access to the bound port.

int socket_connect (  char *    host, int    port )

Connect a TCP-stream to a server (Client side). Creates a socket and connect it over a TCP-stream to the specified port on the specified server. Parameters: host  a string (char *) which specifies the name or the IP-address of the server. port  an integer which specifies the port on the server. Returns: The File Descriptor (FD) which allows access to the TCP-stream-socket or -1 if the connection fails.

int socket_md5auth (  int    fd, char *    netname, char *    name, struct AUTHINFO **    plocallogin, struct AUTHINFO **    premotelogin )

Do both side authentification. This function is usually called just after a socket stream is established. The function must be called on both sides. WARNING: This authentication can be bypassed simply by using the multiple session attack if multiple session are allowd and the same password is used for both sides. Both sides following these steps: 1. get auth info ([login] name, passwd) by using getauthinfo() from name or netname for remote login 2. generate random numbers 3. exchange (first send, then receive) login names 4. exchange random numbers 5. calculate md5 checksum over the random numbers (received from other side) and the remote passwd. 6. exchange md5 checksums 7. get auth info from name (received from other side) for local login 8. calculate md5 checksum over the local random numbers and the local passwd. 9. check login -- compare the received md5sum (6.) with the generated one (8.); send acknowledgement 10. receive remote acknowledgement 11. return suitable values Parameters: fd  (int) describes the socket on which the authentication has to be done netname  (char *) use netname to resolve [login] name and passwd of the remote machine (NULL: not specified) netname  (char *) use [login] name to resolve passwd of the remote machine (NULL: not specified; both NULL use first entry in file, see getauthinfo()) plocallogin  (struct AUTHINFO **) (pointer to pointer to an AUTHINFO struct) in this (double pointed) struct the local authinfo will be loaded, if the parameter is not null. premotelogin  (struct AUTHINFO **) in this (double pointed) struct the remote authinfo will be loaded, if the parameter is not null. Returns: (int) 0: Authentication/Login OK; -1: remote login error; -2: login error on both sides; -3: local login error; -4: other (network) error; -5: cannot load remote auth info; -6: cannot load local auth info;

void thread1 (  struct LIBCOMMPTHREADS *    libcommpthreads )

This is a part of block_call() and must not called from the user. This function is the thread which is started from block_call() and runs in background. Parameters: libcommpthreads  (struct LIBCOMMPTHREADS *) holds pointers to the functions to be call, fd (socket discriptor) and id.

---