ccdoc SPMsocket ../fsio/SPMSocket.h:42:class

FemtoScan Online SDK Documentation

class SPMsocket

? ^

Bidirectional TCP/IP socket-based stream for message exchange between remote clients.
This stream is closely integrated with MessageType class.

Source:
../fsio/SPMSocket.h:42

Author:
ATC

Version:
1.0

Entity Type Scope Short Description

~SPMsocket destructor public Standart destructor.

SPMsocket constructor public Default constructor

SPMsocket constructor public Attach to the existing windows socket.

SPMsocket constructor public Copy constructor.

Accept method public Accept incoming connection.

Attach method public Attach to existing windows socket.

Cipher enum public Enumerates possible cipher types.

CipherMode enum public Enumerates possible cipher modes.

CipherPadding enum public Enumerates possible cipher modes.

Close method public Close socket.

Connect method public Try to connect to the specified adddress.

DecryptSessionKeys static method public undocumented

Detach method public Detach underlying windows socket

Digest enum public Enumerates possible digest types.

Disconnect method public Gracefully disconnect socket.

EncryptSessionKeys static method public undocumented

FlushWriteBuffer method public Try to send pending data.

FreeLine static method public Free buffer returned by ReadLine function.

GenerateSessionKeys static method public undocumented

getCipherBlockSize static method public Get cipher block size.

getCipherKeyLength static method public Get cipher key length.

GetClientAddr method public Get human-readable address of connected client.

getDigestKeyLength static method public Get digest key length.

GetSessionIdleTime method public Get connect timeout

GetState method public Get socket state.

GetWriteBufferSize method public Get write buffer size.

IsOk method public Check socket state.

isSecured method public Get security state.

Listen method public Listen for incoming connections.

operator SOCKET operator public Get underlying windows socket.

PutBack method public Rewind read buffer.

Read method public Read data from sream.

ReadLine method public Read next line from stream.

ReadMsg method public Read message from stream.

SecureDirection enum public Enumerates possible secure modes.

setSecurity method public Configure security on socket.

SetSessionIdleTime method public Set connect timeout.

State enum public Enumerates possible socket states.

Write method public Write data to stream.

WriteLine method public Write line to stream.

WriteMsg method public Write message to stream.

Entity	Type	Scope	Short Description
~SPMsocket	destructor	public	Standart destructor.
SPMsocket	constructor	public	Default constructor
SPMsocket	constructor	public	Attach to the existing windows socket.
SPMsocket	constructor	public	Copy constructor.
Accept	method	public	Accept incoming connection.
Attach	method	public	Attach to existing windows socket.
Cipher	enum	public	Enumerates possible cipher types.
CipherMode	enum	public	Enumerates possible cipher modes.
CipherPadding	enum	public	Enumerates possible cipher modes.
Close	method	public	Close socket.
Connect	method	public	Try to connect to the specified adddress.
DecryptSessionKeys	static method	public	undocumented
Detach	method	public	Detach underlying windows socket
Digest	enum	public	Enumerates possible digest types.
Disconnect	method	public	Gracefully disconnect socket.
EncryptSessionKeys	static method	public	undocumented
FlushWriteBuffer	method	public	Try to send pending data.
FreeLine	static method	public	Free buffer returned by ReadLine function.
GenerateSessionKeys	static method	public	undocumented
getCipherBlockSize	static method	public	Get cipher block size.
getCipherKeyLength	static method	public	Get cipher key length.
GetClientAddr	method	public	Get human-readable address of connected client.
getDigestKeyLength	static method	public	Get digest key length.
GetSessionIdleTime	method	public	Get connect timeout
GetState	method	public	Get socket state.
GetWriteBufferSize	method	public	Get write buffer size.
IsOk	method	public	Check socket state.
isSecured	method	public	Get security state.
Listen	method	public	Listen for incoming connections.
operator SOCKET	operator	public	Get underlying windows socket.
PutBack	method	public	Rewind read buffer.
Read	method	public	Read data from sream.
ReadLine	method	public	Read next line from stream.
ReadMsg	method	public	Read message from stream.
SecureDirection	enum	public	Enumerates possible secure modes.
setSecurity	method	public	Configure security on socket.
SetSessionIdleTime	method	public	Set connect timeout.
State	enum	public	Enumerates possible socket states.
Write	method	public	Write data to stream.
WriteLine	method	public	Write line to stream.
WriteMsg	method	public	Write message to stream.

destructor ~SPMsocket

? ^ >

Standart destructor.

Source:
../fsio/SPMSocket.h:66

Code:
public virtual ~ SPMsocket ( )

constructor SPMsocket

? ^ < >

Default constructor

Source:
../fsio/SPMSocket.h:48

Code:
public SPMsocket ( )

constructor SPMsocket

? ^ < >

Attach to the existing windows socket.
This constructor should be used to create stream, attached to the windows socket, returned by call to the Accept .

Source:
../fsio/SPMSocket.h:56

Param:

sock windows socket attach to.

Code:
public SPMsocket ( SOCKET sock )

constructor SPMsocket

? ^ < >

Copy constructor.

Source:
../fsio/SPMSocket.h:61

Code:
public SPMsocket ( const SPMsocket & sock )

method Accept

? ^ < >

Accept incoming connection.
If socket is in listening state (IOListen), incomig connections (if any) can be accepted. The socket itself remains in listening state, but returned socket can be attached by SPMsocket and used for data transfer.

Source:
../fsio/SPMSocket.h:116

Returns:
accepted socket (if any). Otherwise returns INVALID_SOCKET value.

See Also:
SPMsocket, State, Attach

Code:
public SOCKET Accept ( )

method Attach

? ^ < >

Attach to existing windows socket.

Source:
../fsio/SPMSocket.h:133

Param:

sock windows socket (e.g. returned by @link #Accept @endlink)

Returns:
true if attached successfully (all it needs is juast a valid sock value.

See Also:
Accept

Code:
public bool Attach ( SOCKET sock )

enum Cipher

? ^ < >

Enumerates possible cipher types.

ciphNone - no cipher used

ciphDES - DES cipher (64 bits block, 56 bits key)

ciphTDES - Triple DES cipher (64 bits block, 3x56 bits keys)

ciphRijndael128 - Rijndael cipher (128 bits block, 128, 192 or 256 key)

ciphRijndael192 - Rijndael cipher (192 bits block, 128, 192 or 256 key)

ciphRijndael256 - Rijndael cipher (256 bits block, 128, 192 or 256 key)

ciphBlowFish - Blowfish cipher (64 bits block, key up to 448 bits)

ciphTwoFish - TwoFish cipher (128 bits block, key up to 256 bits)

Source:
../fsio/SPMSocket.h:355

Code:
public enum Cipher { ciphNone ,
ciphDES ,
ciphTDES ,
ciphRijndael128 ,
ciphRijndael192 ,
ciphRijndael256 ,
ciphBlowFish ,
ciphTwoFish ,
}

enum CipherMode

? ^ < >

Enumerates possible cipher modes.

cmECB - Electronic Code Book mode

cmCBC - Cipher Block Chain mode

cmCFB - Cipher Feedback mode

Source:
../fsio/SPMSocket.h:374

Code:
public enum CipherMode { cmECB ,
cmCBC ,
cmCFB ,
}

enum CipherPadding

? ^ < >

Enumerates possible cipher modes.

cpZeros - Zero-padding used

cpPKCS7 - PKCS7 padding mode

Source:
../fsio/SPMSocket.h:387

Code:
public enum CipherPadding { cpZeros ,
cpPKCS7 ,
}

method Close

? ^ < >

Close socket.
First tryes to disconnect socket, then destroys it unconditionally. Frees all stream buffers. Socket state after this operation will be set to IOError.

Source:
../fsio/SPMSocket.h:74

See Also:
State

Code:
public bool Close ( )

method Connect

? ^ < >

Try to connect to the specified adddress.
Since this routine can take significant amount of time, it is made user-cancellable. While tryyng to connect, the socket state will be IOConnect.

Source:
../fsio/SPMSocket.h:90

Params:

server server address in form "<address>:<port>", where <address> is DNS name or IPV4 address, <port> is TCP/IP port in decimal form, e.g. "www.nanoscopy.org:25000".

pccfn user-specified routine, function of type FSIOCancelConnectRoutine . If pccfn is set to NULL, the Connect routine will be performed in non-cancellable manner.

pParam user parameter to be transferred to FSIOCancelConnectRoutine.

Returns:
true if socket was connected.

See Also:
State

Code:
public bool Connect ( const char * server ,
FSIOCancelConnectRoutine pccfn = 0 ,
void * pParam = 0 )

static method DecryptSessionKeys

? ^ < >

undocumented

Source:
../fsio/SPMSocket.h:463

Code:
public static bool DecryptSessionKeys ( const unsigned char * key ,
unsigned keylen ,
Digest digest ,
Cipher cipher ,
int cipher_key_length ,
const unsigned char * enckeydata ,
int enckeydatasize ,
unsigned * cipher_key_offset ,
unsigned char * keydata ,
unsigned * keydatasize )

method Detach

? ^ < >

Detach underlying windows socket

Source:
../fsio/SPMSocket.h:138

Code:
public void Detach ( )

enum Digest

? ^ < >

Enumerates possible digest types.

digNone - no digest signing used

digMD5 - MD5 digest (128 bits)

digSHA1 - SHA1 digest (160 bits)

digSHA256 - SHA digest (256 bits)

digSHA384 - SHA digest (384 bits)

digSHA512 - SHA digest (512 bits)

Source:
../fsio/SPMSocket.h:333

Code:
public enum Digest { digNone ,
digMD5 ,
digSHA1 ,
digSHA256 ,
digSHA384 ,
digSHA512 ,
}

method Disconnect

? ^ < >

Gracefully disconnect socket.
Flush all pending write operations, shutdown write end, receive all remaining data, then put socket in disconnected state (IODisconnected).

Source:
../fsio/SPMSocket.h:125

Returns:
true if socket was disconnected, false if diconnect in process.

See Also:
State

Code:
public bool Disconnect ( )

static method EncryptSessionKeys

? ^ < >

undocumented

Source:
../fsio/SPMSocket.h:471

Code:
public static bool EncryptSessionKeys ( const unsigned char * key ,
unsigned keylen ,
const unsigned char * keydata ,
int keydatasize ,
unsigned char * enckeydata ,
int * enckeydatasize )

method FlushWriteBuffer

? ^ < >

Try to send pending data.

Source:
../fsio/SPMSocket.h:177

Returns:
true if operation should be repeated to send remaining data.

Code:
public bool FlushWriteBuffer ( )

static method FreeLine

? ^ < >

Free buffer returned by ReadLine function.

Source:
../fsio/SPMSocket.h:214

Param:

line pointer to the buffer returned by ReadLine function.

Code:
public static void FreeLine ( void * line )

static method GenerateSessionKeys

? ^ < >

undocumented

Source:
../fsio/SPMSocket.h:467

Code:
public static bool GenerateSessionKeys ( Digest digest ,
Cipher cipher ,
unsigned cipher_key_length ,
unsigned * cipher_key_offset ,
unsigned char * keydata ,
unsigned * keydatasize )

static method getCipherBlockSize

? ^ < >

Get cipher block size.

Source:
../fsio/SPMSocket.h:458

Param:

ciph cipher type

Returns:
block size for specified cipher type

See Also:
Cipher

Code:
public static int getCipherBlockSize ( Cipher ciph )

static method getCipherKeyLength

? ^ < >

Get cipher key length.

Source:
../fsio/SPMSocket.h:450

Params:

ciph cipher type

key_len key length (if not fixed for cpecified type)

Returns:
key length for specified cipher type and optional key length

See Also:
Cipher

Code:
public static int getCipherKeyLength ( Cipher ciph ,
unsigned key_len )

method GetClientAddr

? ^ < >

Get human-readable address of connected client.

Source:
../fsio/SPMSocket.h:150

Returns:
address of the client on the other end of link.

Code:
public const char * GetClientAddr ( ) const

static method getDigestKeyLength

? ^ < >

Get digest key length.

Source:
../fsio/SPMSocket.h:441

Param:

dgst digest type

Returns:
key length for specified digest type

See Also:
Digest

Code:
public static int getDigestKeyLength ( Digest dgst )

method GetSessionIdleTime

? ^ < >

Get connect timeout

Source:
../fsio/SPMSocket.h:164

Returns:
time slice for user status update during Connect (in seconds).

Code:
public int GetSessionIdleTime ( ) const

method GetState

? ^ < >

Get socket state.
Get current state.

Source:
../fsio/SPMSocket.h:308

See Also:
State

Code:
public State GetState ( ) const

method GetWriteBufferSize

? ^ < >

Get write buffer size.

Source:
../fsio/SPMSocket.h:171

Returns:
send buffer size in bytes - data that was enqueued but not sent yet. This value can be used to detect slow links.

Code:
public size_t GetWriteBufferSize ( ) const

method IsOk

? ^ < >

Check socket state.

Source:
../fsio/SPMSocket.h:144

Returns:
true if underlying windows socket is Ok and no read/write errors occured.

Code:
public bool IsOk ( ) const

method isSecured

? ^ < >

Get security state.
Check if security is enabled in the specified direction(s).

Source:
../fsio/SPMSocket.h:433

Param:

sec_dir direction to check

Returns:
true if security enabled

Code:
public bool isSecured ( SecureDirection sec_dir ) const

method Listen

? ^ < >

Listen for incoming connections.
Socket will be put into the listening state (IOListen). Incoming connections should be accepted with Accept .

Source:
../fsio/SPMSocket.h:104

Params:

port TCP/IP port where to listen for incoming connections.

addr listening address (if no address cpecifyed, socket will listen on all available addresses).

af address family, values other then AF_INET never where tested

type address family, values other then SOCK_STREAM never where tested

protocol 0 by default, which means TCP/IP

See Also:
State

Code:
public bool Listen ( u_short port ,
const char * addr = 0 ,
int af = AF_INET ,
int type = SOCK_STREAM ,
int protocol = 0 )

operator SOCKET

? ^ < >

Get underlying windows socket.

Source:
../fsio/SPMSocket.h:183

Returns:
underlying windows socket.

Code:
public operator SOCKET ( ) const

method PutBack

? ^ < >

Rewind read buffer.
Put readen data back to the read buffer and rewind buffer pointer on the specified amount.

Source:
../fsio/SPMSocket.h:222

Params:

buf data to put back.

n size of data.

Code:
public void PutBack ( const char * buf ,
int n )

method Read

? ^ < >

Read data from sream.

Source:
../fsio/SPMSocket.h:191

Params:

buf data buffer.

n buffer size.

Returns:
number of bytes that were read.

Code:
public int Read ( char * buf ,
int n )

method ReadLine

? ^ < >

Read next line from stream.
Read all the data from stream until delimiter will be found. If no delimiter found and socket was closed or disconnected, no data will be read. If delimiter was found, it will be extracted from stream but not appended to the string. This routine can block for indefinite amount of time if no delimiter occurs in data stream while the socket remains valid.

Source:
../fsio/SPMSocket.h:207

Params:

size pointer to the location where will be stored number of characters, extracted from stream.

delim end-of-line delimiter, newline ('\n') by default.

Returns:
line which was read from the stream. It shoul be freed with FreeLine function.

Code:
public char * ReadLine ( unsigned * size ,
char delim = '\n' )

method ReadMsg

? ^ < >

Read message from stream.
Retrieve next message from stream. The message should be checked for validity by MessageType::IsOk . The typical usage of this function looks as follows:
 while(1) (
 	MessageType rdmsg;
 	if(!m_Socket.ReadMsg(rdmsg)) {
 		m_Socket.Close();
 		return -1;
 	}

 	if(rdmsg.IsOk()) {
 		//.....
		//	process message
		//.....
		if(terminate_flag)
			return 1;
	} else
		Sleep(1000);
}
 
Source:
../fsio/SPMSocket.h:270

Params:

M the object where to store retrieved mesage.

readen pointer to the number of bytes actually readen.

Returns:
true if stream is in good state.

See Also:
Close, MessageType::IsOk

Code:
public bool ReadMsg ( MessageType & M ,
unsigned * readen = 0 )

enum SecureDirection

? ^ < >

Enumerates possible secure modes.

sNone - don't secure connection

sRead - secure read operations on socket

sWrite - secure write operations on socket

sBoth - secure all operations on socke

Source:
../fsio/SPMSocket.h:315

Code:
public enum SecureDirection { sNone = 0x0 ,
sRead = 0x1 ,
sWrite = 0x2 ,
sBoth = 0x3 ,
}

method setSecurity

? ^ < >

Configure security on socket.
Configures encryption and/or message digest on socket. Alocates necessary structures, validates digest and key lengths, and stores key if needed. If digNone specified as digest type, and ciphNone as cipher type, security will be disabled. Encrypted message structure:

message length (4 bytes)

HMAC signature (optional)

IV (if required by cipher mode, CBC and CFB modes only)

ciphertext of the message

Message contains:

plain text length (4bytes)

plain text

optional padding (so that total message length will be multiple of ciphertext block size)

Source:
../fsio/SPMSocket.h:425

Params:

sec_dir to which direction to apply parameters below

dgst digest type

dig_key digest key

ciph cipher type

ciphmd cipher mode

ciph_key cipher key data

key_len cipher key data length

ciphpad cipher padding mode

Returns:
true if security was enabled on socket in specified direction

Code:
public bool setSecurity ( SecureDirection sec_dir ,
Digest dgst ,
const unsigned char * dig_key ,
Cipher ciph ,
CipherMode ciphmd ,
const unsigned char * ciph_key ,
unsigned key_len ,
CipherPadding ciphpad )

method SetSessionIdleTime

? ^ < >

Set connect timeout.

Source:
../fsio/SPMSocket.h:157

Param:

seconds time slice for user status update during Connect .

Code:
public void SetSessionIdleTime ( int seconds )

enum State

? ^ < >

Enumerates possible socket states.

IOError - socket is not functioning

IOListen - socket is listening for incoming connections

IOConnect - socket is waiting for connection acceptance

IOWaiting - this is normal socket state, it is ready and waiting for IO operation

IOShutdown - socket shutdown initiated

IODisconnected - socket was gracefully disconnected and can be safely destroyed

Source:
../fsio/SPMSocket.h:289

Code:
public enum State { IOError ,
IOListen ,
IOConnect ,
IOWaiting ,
IOShutdown ,
IODisconnected ,
}

method Write

? ^ < >

Write data to stream.

Source:
../fsio/SPMSocket.h:232

Params:

buf data buffer.

n buffer size.

Returns:
number of bytes that where put to stream or 0 if the socket can't write data. if return value is less than n, operation should be repeated with buf being offset by returned value.

Code:
public int Write ( const char * buf ,
int n )

method WriteLine

? ^ < >

Write line to stream.

Source:
../fsio/SPMSocket.h:239

Param:

buf zero-delimited string.

Returns:
number of bytes that where put to stream or 0 if the socket can't write data.

Code:
public int WriteLine ( const char * str )

method WriteMsg

? ^ < >

Write message to stream.
Put message to stream.

Source:
../fsio/SPMSocket.h:280

Params:

M message to send.

written pointer to the size of actually written data (for statistics)

Returns:
true if message was set to stream. If false returned, it means that either message was too big, either stream can't send data.

Code:
public bool WriteMsg ( const MessageType & M ,
unsigned * written = 0 )

public enum Cipher {	ciphNone ,
	ciphDES ,
	ciphTDES ,
	ciphRijndael128 ,
	ciphRijndael192 ,
	ciphRijndael256 ,
	ciphBlowFish ,
	ciphTwoFish ,
	}

server	server address in form "<address>:<port>", where <address> is DNS name or IPV4 address, <port> is TCP/IP port in decimal form, e.g. "www.nanoscopy.org:25000".
pccfn	user-specified routine, function of type FSIOCancelConnectRoutine . If pccfn is set to NULL, the Connect routine will be performed in non-cancellable manner.
pParam	user parameter to be transferred to FSIOCancelConnectRoutine.

public bool Connect (	const char * server ,
	FSIOCancelConnectRoutine pccfn = 0 ,
	void * pParam = 0 )

public static bool DecryptSessionKeys (	const unsigned char * key ,
	unsigned keylen ,
	Digest digest ,
	Cipher cipher ,
	int cipher_key_length ,
	const unsigned char * enckeydata ,
	int enckeydatasize ,
	unsigned * cipher_key_offset ,
	unsigned char * keydata ,
	unsigned * keydatasize )

public enum Digest {	digNone ,
	digMD5 ,
	digSHA1 ,
	digSHA256 ,
	digSHA384 ,
	digSHA512 ,
	}

public static bool EncryptSessionKeys (	const unsigned char * key ,
	unsigned keylen ,
	const unsigned char * keydata ,
	int keydatasize ,
	unsigned char * enckeydata ,
	int * enckeydatasize )

public static bool GenerateSessionKeys (	Digest digest ,
	Cipher cipher ,
	unsigned cipher_key_length ,
	unsigned * cipher_key_offset ,
	unsigned char * keydata ,
	unsigned * keydatasize )

ciph	cipher type
key_len	key length (if not fixed for cpecified type)

public static int getCipherKeyLength (	Cipher ciph ,
	unsigned key_len )

port	TCP/IP port where to listen for incoming connections.
addr	listening address (if no address cpecifyed, socket will listen on all available addresses).
af	address family, values other then AF_INET never where tested
type	address family, values other then SOCK_STREAM never where tested
protocol	0 by default, which means TCP/IP

public bool Listen (	u_short port ,
	const char * addr = 0 ,
	int af = AF_INET ,
	int type = SOCK_STREAM ,
	int protocol = 0 )

public void PutBack (	const char * buf ,
	int n )

size	pointer to the location where will be stored number of characters, extracted from stream.
delim	end-of-line delimiter, newline ('\n') by default.

public char * ReadLine (	unsigned * size ,
	char delim = '\n' )

M	the object where to store retrieved mesage.
readen	pointer to the number of bytes actually readen.

public bool ReadMsg (	MessageType & M ,
	unsigned * readen = 0 )

public enum SecureDirection {	sNone = 0x0 ,
	sRead = 0x1 ,
	sWrite = 0x2 ,
	sBoth = 0x3 ,
	}

sec_dir	to which direction to apply parameters below
dgst	digest type
dig_key	digest key
ciph	cipher type
ciphmd	cipher mode
ciph_key	cipher key data
key_len	cipher key data length
ciphpad	cipher padding mode

public bool setSecurity (	SecureDirection sec_dir ,
	Digest dgst ,
	const unsigned char * dig_key ,
	Cipher ciph ,
	CipherMode ciphmd ,
	const unsigned char * ciph_key ,
	unsigned key_len ,
	CipherPadding ciphpad )

public enum State {	IOError ,
	IOListen ,
	IOConnect ,
	IOWaiting ,
	IOShutdown ,
	IODisconnected ,
	}

class SPMsocket

Contents

destructor ~SPMsocket

constructor SPMsocket

constructor SPMsocket

constructor SPMsocket

method Accept

method Attach

enum Cipher

enum CipherMode

enum CipherPadding

method Close

method Connect

static method DecryptSessionKeys

method Detach

enum Digest

method Disconnect

static method EncryptSessionKeys

method FlushWriteBuffer

static method FreeLine

static method GenerateSessionKeys

static method getCipherBlockSize

static method getCipherKeyLength

method GetClientAddr

static method getDigestKeyLength

method GetSessionIdleTime

method GetState

method GetWriteBufferSize

method IsOk

method isSecured

method Listen

operator SOCKET

method PutBack

method Read

method ReadLine

method ReadMsg

enum SecureDirection

method setSecurity

method SetSessionIdleTime

enum State

method Write

method WriteLine

method WriteMsg

public int Write (	const char * buf ,
	int n )

M	message to send.
written	pointer to the size of actually written data (for statistics)

public bool WriteMsg (	const MessageType & M ,
	unsigned * written = 0 )