PPL6-Icon Patrick's Programming Library Version 6.4.21 - Dokumentation
ppl6::CTCPSocket Klassenreferenz

TCP-Socket-Klasse. Mehr ...

SSL-Verschlüsselung

Die nachfolgenden Befehle werden benötigt, wenn die Kommunikation zwischen Client und Server mit SSL verschlüsselt werden soll. Voraussetzung dafür ist, dass die PPL-Library mit OpenSSL-Unterstützung kompiliert wurde.

int SSL_Write (const void *buffer, int size)
 Verschlüsselte Daten schreiben. Mehr ...
 
int SSL_Read (void *buffer, int bytes)
 Verschlüsselte Daten lesen. Mehr ...
 
int ConnectSSL (const char *host_and_port, CSSL *ssl=NULL)
 Verschlüsselte Verbindung aufbauen. Mehr ...
 
int ConnectSSL (const char *host, int port, CSSL *ssl=NULL)
 Verschlüsselte Verbindung aufbauen. Mehr ...
 
int SSL_Init (CSSL *ssl)
 Verwendung von OpenSSL initialisieren. Mehr ...
 
int SSL_Shutdown ()
 SSL für diese Klasse deinitialisieren. Mehr ...
 
int SSL_Init_Client ()
 Socket als SSL-Client vorbereiten. Mehr ...
 
int SSL_Init_Server ()
 Socket als SSL-Server vorbereiten. Mehr ...
 
int SSL_Start ()
 SSL-Kommunikation starten. Mehr ...
 
int SSL_Stop ()
 SSL-Kommunikation stoppen. Mehr ...
 
int SSL_CheckCertificate (const char *hostname, bool AcceptSelfSignedCert=false)
 SSL-Zertifikat der Gegenstelle prüfen. Mehr ...
 
int SSL_Accept ()
 Auf eine TLS/SSL-Handshake warten. Mehr ...
 
int SSL_WaitForAccept (int timeout=0)
 Auf eine TLS/SSL-Handshake warten. Mehr ...
 
void SSL_Info ()
 
bool SSL_IsEncrypted () const
 
CString SSL_GetCipherName () const
 
CString SSL_GetCipherVersion () const
 
int SSL_GetCipherBits () const
 

Öffentliche Methoden

 CTCPSocket ()
 Konstruktor der Klasse. Mehr ...
 
virtual ~CTCPSocket ()
 Destruktor der Klasse. Mehr ...
 
int Bind (const char *ip, int port)
 Socket auf eine IP-Adresse und Port binden. Mehr ...
 
int Connect (const char *host_and_port)
 Verbindung aufbauen. Mehr ...
 
int Connect (const char *host, int port)
 Verbindung aufbauen. Mehr ...
 
int Disconnect ()
 Verbindung trennen. Mehr ...
 
void DispatchErrno ()
 Fehlercode des Betriebssystems in PPL-Fehler übersetzen. Mehr ...
 
int GetBytesRead ()
 Anzahl gelesender Bytes. Mehr ...
 
int GetBytesWritten ()
 Anzahl gesendeter Bytes. Mehr ...
 
int GetDescriptor ()
 Descriptor des Sockets auslesen. Mehr ...
 
const CStringgetHostname () const
 
int getPort () const
 
int IsConnected ()
 Prüfen, ob eine Verbindung besteht. Mehr ...
 
int IsListening ()
 Prüfen, ob der Socket auf eingehende Verbindungen wartet. Mehr ...
 
int IsReadable ()
 Prüfen, ob Daten vom Socket gelesen werden können. Mehr ...
 
int IsWriteable ()
 Prüfen, ob Daten auf den Socket geschrieben werden können. Mehr ...
 
int Listen (int timeout=100)
 Server starten und auf eingehende Verbindung warten. Mehr ...
 
int Read (void *buffer, int bytes)
 Daten lesen. Mehr ...
 
int Read (CString &buffer, int bytes)
 Daten in einen String einlesen. Mehr ...
 
int Read (CString *buffer, int bytes)
 Daten in einen String einlesen. Mehr ...
 
int Read (CBinary &buffer, int bytes)
 Daten in ein CBinary-Objekt einlesen. Mehr ...
 
char * Read (int bytes)
 Daten lesen. Mehr ...
 
int ReadOnce (void *buffer, int bytes)
 Daten lesen. Mehr ...
 
int ReadOnce (CString &buffer, int bytes)
 Daten lesen. Mehr ...
 
int ReadOnce (CString *buffer, int bytes)
 Daten lesen. Mehr ...
 
char * ReadOnce (int bytes)
 Daten lesen. Mehr ...
 
virtual int ReceiveConnect (CTCPSocket *socket, const char *host, int port)
 Eingehende Verbindung verarbeiten. Mehr ...
 
int SetBlocking (bool value)
 Bei Lesezugriffen blockieren. Mehr ...
 
void SetConnectTimeout (int seconds, int useconds)
 Timeout für Connect-Funktion definieren. Mehr ...
 
void SetLogfile (CLog *log)
 Logfile definieren. Mehr ...
 
int SetReadTimeout (int seconds, int useconds)
 Lese-Timeout festlegen. Mehr ...
 
void SetSource (const char *host, int port=0)
 Quell-Interface und Port festlegen. Mehr ...
 
int SetWriteTimeout (int seconds, int useconds)
 Schreib-Timeout festlegen. Mehr ...
 
int Shutdown ()
 Verbindung trennen. Mehr ...
 
int SignalStopListen ()
 TCP-Server signalisieren, dass er stoppen soll. Mehr ...
 
int StopListen ()
 TCP-Server anhalten. Mehr ...
 
int WaitForIncomingData (int seconds, int useconds)
 Auf eingehende Daten warten. Mehr ...
 
int WaitForMessage (CSocketMessage &msg, int timeout=0)
 Nachricht verschicken. Mehr ...
 
int WaitForOutgoingData (int seconds, int useconds)
 Warten, bis der Socket beschreibbar ist. Mehr ...
 
int WatchThread (CThread *thread)
 Überwachungsthread definieren. Mehr ...
 
int Write (const CString &str)
 String schreiben. Mehr ...
 
int Write (const CBinary &bin)
 Binäre Daten schreiben. Mehr ...
 
int Write (const CString *str)
 String schreiben. Mehr ...
 
int Write (const void *buffer, int bytes)
 Daten schreiben. Mehr ...
 
int Write (CSocketMessage &msg)
 Nachricht verschicken. Mehr ...
 
int WriteBuffer (const void *buffer, int bytes)
 Daten schreiben. Mehr ...
 
int Writef (const char *fmt,...)
 Formatierten String schreiben. Mehr ...
 

Öffentliche, statische Methoden

static ppluint32 Htonl (ppluint32 host)
 32-Bit-Wert von Host-Byteorder in Netzwerk-Byteorder wandeln Mehr ...
 
static ppluint16 Htons (ppluint16 host)
 16-Bit-Wert von Host-Byteorder in Netzwerk-Byteorder wandeln Mehr ...
 
static ppluint32 Ntohl (ppluint32 net)
 32-Bit-Wert von Host-Byteorder in Hostbyteorder wandeln Mehr ...
 
static ppluint16 Ntohs (ppluint16 net)
 16-Bit-Wert von Netzwerk-Byteorder in Host-Byteorder wandeln Mehr ...
 

Private Attribute

int BytesRead
 
int BytesWritten
 
int connect_timeout_sec
 
int connect_timeout_usec
 
int connected
 
CString HostName
 
int islisten
 
CLoglog
 
CMutex mutex
 
int PortNum
 
void * socket
 
CString SourceHost
 
int SourcePort
 
void * ssl
 
CSSLsslclass
 
void * sslreference
 
bool stoplisten
 
CThreadthread
 

Verwandte Funktionen

(Es handelt sich hierbei nicht um Elementfunktionen.)

static int out_bind (const char *host, int port)
 Socket auf ausgehendes Interface legen. Mehr ...
 
static int ppl_connect_nb (int sockfd, struct sockaddr *serv_addr, int addrlen, int sec, int usec)
 Non-Blocking-Connect. Mehr ...
 
int SSL_Exit ()
 OpenSSL-Schnittstelle deinitialisieren. Mehr ...
 
int SSL_Init ()
 OpenSSL-Schnittstelle initialisieren. Mehr ...
 

Ausführliche Beschreibung

Socket-Klasse für TCP-Verbindungen.

Include:
#include <ppl6.h>
Beschreibung:
Mit dieser Klasse kann eine TCP-Verbindung (Transmission Control Protocol) zu einem über IP erreichbaren Server aufgebaut oder ein eigener Server gestartet werden. Über eine bestehende Verbindung können Daten gesenden und empfangen werden. Mit Hilfe der Klasse CSSL und der OpenSSL-Bibliothek können die Daten auch verschlüsselt übertragen werden.
Beispiel: TCP-Client
Das nachfolgende Beispiel zeigt einen einfachen Client, der eine Verbindung zu einem Server öffnet, ein Datenpaket sendet und auf ein Datenpaket wartet.
int Socket_Example1() {
// Wir bauen eine Verbindung zum Zielrechner auf
if (!Socket.Connect("localhost",9020)) {
return 0;
}
ppl6::CString Daten="Mein erstes Datenpaket";
// Nun senden wir das Datenpaket
if (!Socket.Write(Daten)) {
return 0;
}
// Und warten auf die Antwort
if (!Socket.ReadOnce(Daten,100)) {
return 0;
}
printf ("Daten erhalten: %s",(const char *)Daten);
// Verbindung trennen
Socket.Disconnect();
} // EOF
Beispiel: TCP-Server
Das zweite Beispiel zeigt, wie ein einfacher TCP-Server programmiert wird. Zunächst wird ein Server gestartet, der auf eingehende Verbindungen wartet. Nach Verbindungseingang wird auf Datenpakete gewartet, die sofort wieder an den Client zurückgeschickt werden. Durch Abbruch der Verbindung wird die Schleife wieder beendet.
// Socket_Example2
// Zunächst leitet wir eine eigene Klasse von CTCPSocket ab, in der wir
// nur die virtuelle Funktion ReceiveConnect implementieren:
class MySocket : public ppl6::CTCPSocket
{
public:
virtual int ReceiveConnect(CTCPSocket *socket, const char *host, int port);
};
// Implementation der Funktion
int MySocket::ReceiveConnect(CTCPSocket *socket, const char *host, int port)
{
// Speicher für die eingehenden Datenpakete allokieren
char *buffer=(char*)malloc(100);
// Wir schalten den Socket auf Non-Blocking
socket->SetBlocking(false);
int bytes;
// Endlosschleife, die erst bei Auftreten eines Fehlers beendet wird, z.B.
// infolge einer Verbindungstrennung
while (1) {
// Auf Daten warten, maximal aber 100 Millisekunden
if (socket->WaitForIncomingData(0,10000)) {
// Daten lesen
if (!socket->ReadOnce(buffer,100)) {
// Es ist ein Fehler aufgetreten
break;
}
// Wieviel Bytes haben wir bekommen?
bytes=socket->GetBytesRead();
// Datenpaket zurückschicken
if (!socket->Write(buffer,bytes)) {
// Es ist ein Fehler aufgetreten
break;
}
}
}
free(buffer);
return 0;
}
// Nun die Main-Funktion
int main (int argc, char **argv)
{
// Instanz von MySocket definieren
MySocket Socket;
printf ("Starte Server auf localhost:9020\n");
// Server auf "localhost" und Port 9020 binden
if (!Socket.Bind("localhost",9020)) {
return 0;
}
// Auf Verbindungen warten
if (!Socket.Listen()) {
return 0;
}
} // EOF
Ein weiteres Beispiel mit einer verschlüsselten Datenübertragung ist in der Dokumentation der Klasse CSSL zu finden.

Beschreibung der Konstruktoren und Destruktoren

ppl6::CTCPSocket::CTCPSocket ( )
ppl6::CTCPSocket::~CTCPSocket ( )
virtual

Dokumentation der Elementfunktionen

int ppl6::CTCPSocket::Bind ( const char *  host,
int  port 
)
Beschreibung:
Diese Funktion muss aufgerufen werden, bevor man mit CTCPSocket::Listen einen TCP-Server starten kann. Dabei wird mit host die IP-Adresse festgelegt, auf die sich der Server binden soll und mit port der TCP-Port. Es ist nicht möglich einen Socket auf mehrere Adressen zu binden.
Parameter
[in]hostIP-Adresse, Hostname, "*" oder NULL. Bei Angabe von "*" oder NULL bindet sich der Socket auf alle Interfaces des Servers.
[in]portDer gewünschte TCP-Port
Rückgabe
Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::Connect ( const char *  host)

Mit dieser Funktion wird eine Verbindung zur angegebenen Adresse aufgebaut.

Parameter
hostDer Parameter "host" muss das Format "hostname:port" haben, wobei "hostname" auch eine IP-Adresse sein kann. Der Port kann entweder als Zahl oder als Servicename angegeben werden, z.B. "smtp" für Port 25.
Rückgabe
Konnte die Verbindung erfolgreich aufgebaut werden, wird true (1) zurückgegeben, im Fehlerfall false (0).
Seit
Seit Version 6.0.18 kann der Port statt als Nummer auch als Servicenamen angegeben werden.
int ppl6::CTCPSocket::Connect ( const char *  host,
int  port 
)
Beschreibung:
Mit dieser Funktion wird eine Verbindung zur angegebenen Adresse aufgebaut.
Parameter
[in]hostDer Hostname oder die IP-Adresse des Zielrechners
[in]portDer gewünschte Zielport
Rückgabe
Konnte die Verbindung erfolgreich aufgebaut werden, wird true (1) zurückgegeben, im Fehlerfall false (0).
int ppl6::CTCPSocket::ConnectSSL ( const char *  host,
CSSL ssl = NULL 
)
Beschreibung:
Mit dieser Funktion wird zunächst eine Verbindung zur gewünschten Zieladresse host aufgebaut und dann die SSL-Verschlüsselung gestartet.
Parameter
[in]hostDer Parameter "host" muss das Format "hostname:port" haben, wobei "hostname" auch eine IP-Adresse sein kann. Der Port kann entweder als Zahl oder als Servicename angegeben werden, z.B. "smtp" für Port 25.
[in]sslOptionaler Pointer auf ein CSSL-Objekt. Wird es nicht angegeben, erstellt die Klasse selbst eins mit Default-Parametern. Es ist flexibler, ein eigenes Objekt zu erstellen, da man damit auch beliebige zusätzliche Zertifikate laden oder bestimmte Verschlüsselungs-Algorithmen definieren kann.
Rückgabe
Konnte die Verbindung erfolgreich aufgebaut werden, wird true (1) zurückgegeben, im Fehlerfall false (0).
Seit
Seit Version 6.0.18 kann der Port statt als Nummer auch als Servicenamen angegeben werden.
int ppl6::CTCPSocket::ConnectSSL ( const char *  host,
int  port,
CSSL ssl = NULL 
)
Beschreibung:
Mit dieser Funktion wird zunächst eine Verbindung zur gewünschten Zieladresse host aufgebaut und dann die SSL-Verschlüsselung gestartet.
Parameter
[in]hostDer Hostname oder die IP-Adresse des Zielrechners
[in]portDer gewünschte Zielport
[in]sslOptionaler Pointer auf ein CSSL-Objekt. Wird es nicht angegeben, erstellt die Klasse selbst eins mit Default-Parametern. Es ist flexibler, ein eigenes Objekt zu erstellen, da man damit auch beliebige zusätzliche Zertifikate laden oder bestimmte Verschlüsselungs-Algorithmen definieren kann.
Rückgabe
Konnte die Verbindung erfolgreich aufgebaut werden, wird true (1) zurückgegeben, im Fehlerfall false (0).
Seit
Seit Version 6.0.18 kann der Port statt als Nummer auch als Servicenamen angegeben werden.
int ppl6::CTCPSocket::Disconnect ( )
Beschreibung:
Durch Aufruf dieser Funktion wird eine bestehende Verbindung beendet. Unter Windows ist die Funktion identisch mit CTCPSocket::Shutdown, unter Unix unterscheiden sie sich.
CTCPSocket::Disconnect schließt den Socket-Descriptor für den Prozess, die Verbindung bleibt jedoch weiterhin bestehen, wenn ein anderer Prozess den gleichen Descriptor verwendet. Die Verbindung bleibt dann sowohl zum lesen als auch zum schreiben geöffnet.
CTCPSocket::Shutdown trennt die Verbindung für alle Prozesse, die den gleichen Descriptor verwenden. Falls ein anderer Prozess noch versucht auf den Socket zuzzugreifen, bekommt er eine Fehlermeldung. Beim Lesen ist dies meist ein EOF, beim Schreiben ein SIGPIPE, der möglicherweise Aufgrund von Puffern im Kernel nicht sofort auftreten muss.
Rückgabe
Die Funktion liefert immer 1 zurück.
void ppl6::CTCPSocket::DispatchErrno ( )
Beschreibung:
Diese Funktion wird intern immer dann aufgerufen, wenn eine Socket-Funktion des Betriebssystems einen Fehler signalisiert. Sie übersetzt die Betriebssystem-Anghängigen Fehlercodes in einheitliche PPL-Fehlercodes.
Unter Unix wird dazu die globale Fehlervariable "errno" ausgewertet, unter Windows wird der Fehler über die Socketfunktion WSAGetLastError ausgelesen.
int ppl6::CTCPSocket::GetBytesRead ( )
Beschreibung:
Diese Funktion liefert die Anzahl gelesener Bytes während der letzten Leseoperation.
Rückgabe
Anzahl Bytes
int ppl6::CTCPSocket::GetBytesWritten ( )
Beschreibung:
Diese Funktion liefert die Anzahl gesendeter Bytes während der letzten Schreiboperation.
Rückgabe
Anzahl Bytes
int ppl6::CTCPSocket::GetDescriptor ( )
Beschreibung:
Mit dieser Funktion kann der Betriebssystem-spezifische Socket-Descriptor ausgelesen werden. Unter Unix ist dies ein File-Descriptor vom Typ Integer, unter Windows ein Socket-Descriptor vom Typ SOCKET.
Rückgabe
Betriebsystem-spezifischer Descriptor.
const CString & ppl6::CTCPSocket::getHostname ( ) const
int ppl6::CTCPSocket::getPort ( ) const
ppluint32 ppl6::CTCPSocket::Htonl ( ppluint32  host)
static
Beschreibung:
Mit dieser statischen Funktion kann ein 32-Bit-Wert von der Systemspezifische Byte-Reihenfolge in Netzwerk-Byte-Order (Big Endian) umgewandelt werden.
Parameter
[in]host32-Bit-Wert in Systemspezifischer Byte-Reihenfolge
Rückgabe
Liefert den Wert host in Netzwerk-Byteorder (Big Endian) zurück
ppluint16 ppl6::CTCPSocket::Htons ( ppluint16  host)
static
Beschreibung:
Mit dieser statischen Funktion kann ein 16-Bit-Wert von der Systemspezifische Byte-Reihenfolge in Netzwerk-Byte-Order (Big Endian) umgewandelt werden.
Parameter
[in]host16-Bit-Wert in Systemspezifischer Byte-Reihenfolge
Rückgabe
Liefert den Wert host in Netzwerk-Byteorder (Big Endian) zurück
int ppl6::CTCPSocket::IsConnected ( )
Beschreibung:
Mit dieser Funktion kann überprüft werden, ob eine TCP-Verbindung besteht.
Rückgabe
Liefert 1 zurück, wenn eine Verbindung besteht, sonst 0. Es wird kein Fehlercode gesetzt.
int ppl6::CTCPSocket::IsListening ( )
Beschreibung:
Mit dieser Funktion kann überprüft werden, ob der Socket auf eingehende TCP-Verbindungen wartet.
Rückgabe
Liefert 1 zurück, wenn der Socket wartet, sonst 0. Es wird kein Fehlercode gesetzt.
int ppl6::CTCPSocket::IsReadable ( )
Beschreibung:
Diese Funktion prüft, ob auf dem bereits geöffneten Socket Daten zum Lesen vorhanden sind.
Rückgabe
Liefert 1 zurück, wenn Daten auf dem Socket zum Lesen bereitstehen.
int ppl6::CTCPSocket::IsWriteable ( )
Beschreibung:
Diese Funktion prüft, ob der bereits verbundene Socket beschreibbar ist.
Rückgabe
Liefert 1 zurück, wenn Daten auf den Socket geschrieben werden können, ansonsten 0.
int ppl6::CTCPSocket::Listen ( int  timeout = 100)
Beschreibung:
Der Aufruf dieser Funktion führt dazu, dass auf eingehende TCP-Verbindungen gewartet wird. Es wird also ein TCP-Server gestartet. Wird eine Verbindung geöffnet, ruft sie die virtuelle Funktion CTCPSocket::ReceiveConnect auf. Diese muss entsprechend reagieren, indem Sie bei Annahme der Verbindung einen neuen Thread startet und 1 zurückgibt, bei Ablehnung 0.
Vor Aufruf der Funktion muss der Klasse über die Funktion CTCPSocket::Bind zuerst mitgeteilt werden, auf welche IP-Adresse und Port sich der Server binden soll. Sofern kein kritischer Fehler auftritt, läuft die Funktion in einer Endlosschleife. Alle timeout Millisekunden wird jedoch geprüft, ob die Funktion sich beenden soll. Dies wird durch Aufruf der Funktion CTCPSocket::SignalStopListen oder CTCPSocket::StopListen signalisiert.
Parameter
[in]timeoutIntervall in Millisekunden, nachdem geprüpft werden soll, ob weiter auf eingehende Verbindungen gewartet werden soll. Je niedriger der Wert, desto schneller wird auf einen Stop-Befehl reagiert, jedoch steigt dadurch auch die CPU-Auslastung. Der Default ist 100 Millisekunden (1000 Millisekunden = 1 Sekunde).
Rückgabe
Konnte der Server erfolgreich gestartet werden, kehrt die Funktion erst dann wieder zurück, wenn er wieder gestoppt wird. In diesem Fall liefert sie den Wert 1 zurück. Konnte der Server nicht gestartet werden, wird 0 zurückgegeben.
ppluint32 ppl6::CTCPSocket::Ntohl ( ppluint32  net)
static
Beschreibung:
Mit dieser statischen Funktion kann ein 32-Bit-Wert von Netzwerk-Byte-Order (Big Endian) in die Systemspezifische Byte-Reihenfolge umgewandelt werden.
Parameter
[in]net32-Bit-Wert in Netzwerk-Byteorder (Big Endian)
Rückgabe
Liefert den Wert net in System-spezifischer Byte-Reihenfolge zurück
ppluint16 ppl6::CTCPSocket::Ntohs ( ppluint16  net)
static
Beschreibung:
Mit dieser statischen Funktion kann ein 16-Bit-Wert von Netzwerk-Byte-Order (Big Endian) in die Systemspezifische Byte-Reihenfolge umgewandelt werden.
Parameter
[in]net16-Bit-Wert in Netzwerk-Byteorder (Big Endian)
Rückgabe
Liefert den Wert net in System-spezifischer Byte-Reihenfolge zurück
int ppl6::CTCPSocket::Read ( void *  buffer,
int  bytes 
)
Beschreibung:
Diese Funktion liest genau bytes vom Socket in den von der Anwendung angegebenen Puffer buffer. Falls der Socket auf "non-blocking" eingestellt wurde und mit CTCPSocket::WatchThread ein Überwachungsthread angegeben wurde, prüft die Funktion regelmäßig, ob ein Stop signalisiert wurde.
Parameter
[in]bufferSpeicherbereich, in dem die gelesenen Daten abgelegt werden sollen.
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Die Funktion gibt 1 zurück, wenn die Bytes erfolgreich gelesen wurden, im Fehlerfall 0. Ist ein Fehler aufgetreten, kann mit der Funktion CTCPSocket::GetBytesRead abgefragt werden, wieviel Bytes tatsächlich gelesen wurden.
int ppl6::CTCPSocket::Read ( CString buffer,
int  bytes 
)
Beschreibung:
Diese Funktion liest genau bytes vom Socket in den Buffer des Strings buffer ein. Falls der Socket auf "blocking" eingestellt ist (=Default), wartet die Funktion, bis die gewünschte Anzahl Bytes eingegangen ist. Ist er auf "non-blocking" eingestellt, und es wurde mit CTCPSocket::WatchThread ein Überwachungsthread angegeben, prüft die Funktion regelmäßig, ob ein Stop signalisiert wurde.
Parameter
[out]bufferString, in dem die gelesenen Daten abgelegt werden sollen.
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Die Funktion gibt 1 zurück, wenn die Bytes erfolgreich gelesen wurden, im Fehlerfall 0. Ist ein Fehler aufgetreten, kann mit der Funktion CTCPSocket::GetBytesRead abgefragt werden, wieviel Bytes tatsächlich gelesen wurden.
int ppl6::CTCPSocket::Read ( CString buffer,
int  bytes 
)
Beschreibung:
Diese Funktion liest genau bytes vom Socket in den Buffer des Strings buffer ein. Falls der Socket auf "blocking" eingestellt ist (=Default), wartet die Funktion, bis die gewünschte Anzahl Bytes eingegangen ist. Ist er auf "non-blocking" eingestellt, und es wurde mit CTCPSocket::WatchThread ein Überwachungsthread angegeben, prüft die Funktion regelmäßig, ob ein Stop signalisiert wurde.
Parameter
[out]bufferString, in dem die gelesenen Daten abgelegt werden sollen.
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Die Funktion gibt 1 zurück, wenn die Bytes erfolgreich gelesen wurden, im Fehlerfall 0. Ist ein Fehler aufgetreten, kann mit der Funktion CTCPSocket::GetBytesRead abgefragt werden, wieviel Bytes tatsächlich gelesen wurden.
int ppl6::CTCPSocket::Read ( CBinary buffer,
int  bytes 
)
Beschreibung:
Diese Funktion liest genau bytes vom Socket in das CBinary-Objekt buffer ein. Falls der Socket auf "blocking" eingestellt ist (=Default), wartet die Funktion, bis die gewünschte Anzahl Bytes eingegangen ist. Ist er auf "non-blocking" eingestellt, und es wurde mit CTCPSocket::WatchThread ein Überwachungsthread angegeben, prüft die Funktion regelmäßig, ob ein Stop signalisiert wurde.
Parameter
[out]bufferCBinary-Objekt, in dem die gelesenen Daten abgelegt werden sollen.
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Die Funktion gibt 1 zurück, wenn die Bytes erfolgreich gelesen wurden, im Fehlerfall 0. Ist ein Fehler aufgetreten, kann mit der Funktion CTCPSocket::GetBytesRead abgefragt werden, wieviel Bytes tatsächlich gelesen wurden.
char * ppl6::CTCPSocket::Read ( int  bytes)
Beschreibung:
Diese Funktion liest genau bytes vom Socket. Falls der Socket nicht auf Non-Blocking gestellt wurde, wartet die Funktion solange, bis mindestens bytes Bytes eingegangen sind.
Die Funktion allokiert Speicher mit "malloc", um die eingegangenen Daten zu speichern. Die Anwendung muss diesen daher selbst mit "free" wieder freigeben. Mit der Funktion CTCPSocket::GetBytesRead kann abgefragt werden, wieviele Bytes gelesen wurden.
Parameter
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Liefert einen Pointer auf den Speicherbereich zurück, in dem die gelesenen Daten abgelegt wurden. Dieser muss von der Anwendung mit "free" wieder freigegeben werden. Im Fehlerfall wird NULL zurückgegeben.
int ppl6::CTCPSocket::ReadOnce ( void *  buffer,
int  bytes 
)
Beschreibung:
Diese Funktion liest maximal bytes vom Socket in den von der Anwendung angegebenen Puffer buffer. Falls der Socket auf "blocking" eingestellt ist (=Default) wartet die Funktion solange, bis die ersten Daten eingegangen sind und liefert diese zurück. Ist der Socket auf "non blocking" eingestellt, kehrt die Funktion sofort zurück, wenn keine Daten zur Verfügung stehen. Die Anzahl tatsächlich gelesener Bytes kann mit der Funktion CTCPSocket::GetBytesRead ausgelesen werden.
Parameter
[in]bufferSpeicherbereich, in dem die gelesenen Daten abgelegt werden sollen.
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Die Funktion gibt 1 zurück, wenn die Bytes erfolgreich gelesen wurden, im Fehlerfall 0. Die Anzahl tatsächlich gelesener Bytes kann mit CTCPSocket::GetBytesRead abgefragt werden.
int ppl6::CTCPSocket::ReadOnce ( CString buffer,
int  bytes 
)
Beschreibung:
Diese Funktion liest maximal bytes vom Socket in den String buffer. Falls der Socket auf "blocking" eingestellt ist (=Default) wartet die Funktion solange, bis die ersten Daten eingegangen sind und liefert diese zurück. Ist der Socket auf "non blocking" eingestellt, kehrt die Funktion sofort zurück, wenn keine Daten zur Verfügung stehen. Die Anzahl tatsächlich gelesener Bytes kann mit der Funktion CTCPSocket::GetBytesRead ausgelesen werden.
Parameter
[in]bufferString, in dem die gelesenen Daten abgelegt werden sollen.
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Die Funktion gibt 1 zurück, wenn die Bytes erfolgreich gelesen wurden, im Fehlerfall 0. Die Anzahl tatsächlich gelesener Bytes kann mit CTCPSocket::GetBytesRead abgefragt werden.
int ppl6::CTCPSocket::ReadOnce ( CString buffer,
int  bytes 
)
Beschreibung:
Diese Funktion liest maximal bytes vom Socket in den String buffer. Falls der Socket auf "blocking" eingestellt ist (=Default) wartet die Funktion solange, bis die ersten Daten eingegangen sind und liefert diese zurück. Ist der Socket auf "non blocking" eingestellt, kehrt die Funktion sofort zurück, wenn keine Daten zur Verfügung stehen. Die Anzahl tatsächlich gelesener Bytes kann mit der Funktion CTCPSocket::GetBytesRead ausgelesen werden.
Parameter
[in]bufferString, in dem die gelesenen Daten abgelegt werden sollen.
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Die Funktion gibt 1 zurück, wenn die Bytes erfolgreich gelesen wurden, im Fehlerfall 0. Die Anzahl tatsächlich gelesener Bytes kann mit CTCPSocket::GetBytesRead abgefragt werden.
char * ppl6::CTCPSocket::ReadOnce ( int  bytes)
Beschreibung:
Diese Funktion liest maximal bytes vom Socket und gibt einen Pointer auf den Speicherbereich zurück. Falls der Socket auf "blocking" eingestellt ist (=Default) wartet die Funktion solange, bis die ersten Daten eingegangen sind und liefert diese zurück. Ist der Socket auf "non blocking" eingestellt, kehrt die Funktion sofort zurück, wenn keine Daten zur Verfügung stehen. Die Anzahl tatsächlich gelesener Bytes kann mit der Funktion CTCPSocket::GetBytesRead ausgelesen werden.
Die Funktion allokiert Speicher mit "malloc", um die eingegangenen Daten zu speichern. Die Anwendung muss diesen daher selbst mit "free" wieder freigeben. Mit der Funktion CTCPSocket::GetBytesRead kann abgefragt werden, wieviele Bytes gelesen wurden.
Parameter
[in]bytesAnzahl zu lesender Bytes
Rückgabe
Liefert einen Pointer auf den Speicherbereich zurück, in dem die gelesenen Daten abgelegt wurden. Dieser muss von der Anwendung mit "free" wieder freigegeben werden. Im Fehlerfall wird NULL zurückgegeben. Die Anzahl tatsächlich gelesener Bytes kann mit CTCPSocket::GetBytesRead abgefragt werden.
int ppl6::CTCPSocket::ReceiveConnect ( CTCPSocket socket,
const char *  host,
int  port 
)
virtual
Beschreibung:
Diese virtuelle Funktion wird innerhalb von CTCPSocket::Listen aufgerufen, wenn eine neue Verbindung zum Server aufgebaut wurde. Sie muss daher von der abgeleiteten Klasse reimplementiert werden.
Parameter
[in]socketPointer auf eine neue Socket-Klasse, die die eingegangene Verbindung repräsentiert. Die Anwendung muss die Klasse nach Verbindungsende selbst mit "delete" löschen.
[in]hostHostname oder IP der Gegenstelle
[in]portTCP-Port der Gegenstelle
Rückgabe
Wird die Verbindung angenommen und von der Anwendung weiter verarbeitet (z.B. in einem eigenen Thread), muss die Funktion 1 zurückgeben. Soll die Verbindung wieder getrennt werden, muss die Funktion 0 zurückgeben.
int ppl6::CTCPSocket::SetBlocking ( bool  value)
Beschreibung:
Durch Aufruf dieser Funktion kann festgelegt werden, ob der Socket bei Lesezugriffen blockieren soll. Nach dem Öffnen des Sockets ist dieser defaultmäßig so eingestellt, dass er bei Lesezugriffen solange blockiert (wartet), bis Daten zur Verfügung stehen. Wird er auf "Non-Blocking" gestellt, kehren die Lese-Funktionen sofort mit einer Fehlermeldung zurück, wenn noch keine Daten bereitstehen.
Parameter
[in]valueDer Wert "true" setzt den Socket in den Blocking-Modus, was auch der Default ist. Durch den Wert "false" wird er in den Non-Blocking-Modus gesetzt.
Rückgabe
Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.
void ppl6::CTCPSocket::SetConnectTimeout ( int  seconds,
int  useconds 
)
Beschreibung:
Mit dieser Funktion kann ein Timeout für die Connect-Funktionen definiert werden. Ist es nicht möglich innerhalb der vorgegebenen Zeit eine Verbindung mit dem Ziel herzustellen, brechen die Connect-Funktionen mit einer Timeout-Fehlermeldung ab.
Um den Timeout wieder abzustellen, kann die Funktion mit 0 als Wert für seconds und useconds aufgerufen werden.
Parameter
[in]secondsAnzahl Sekunden
[in]usecondsAnzahl Mikrosekunden (1000 Mikrosekunden=1 Millisekunde, 1000 Millisekunden = 1 Sekunde)
void ppl6::CTCPSocket::SetLogfile ( CLog log)
Beschreibung:
Einige Funktionen können zusätzliche Debug-Informationen in ein Logfile schreiben. Durch Aufruf dieser Funktion wird dieses Feature aktiviert oder deaktiviert.
Parameter
[in]logPointer auf eine CLog-Klasse oder NULL, um das Logging zu deaktivieren
int ppl6::CTCPSocket::SetReadTimeout ( int  seconds,
int  useconds 
)

Mit dieser Funktion kann ein Timeout für Lesezugriffe gesetzt werden. Normalerweise blockiert eine Leseoperation mit "Read" solange, bis die angeforderten Daten eingegangen sind (ausser der Socket wurde mit CTCPSocket::SetBlocking auf "Non-Blocking" gesetzt). Mit dieser Funktion kann jedoch ein beliebiger mikrosekunden genauer Timeout festgelegt werden. Der Timeout errechnet sich dabei aus seconds + useconds.

Um den Timeout wieder abzustellen, kann die Funktion mit 0 als Wert für seconds und useconds aufgerufen werden.
Parameter
[in]secondsAnzahl Sekunden
[in]usecondsAnzahl Mikrosekunden (1000000 Mikrosekunden = 1 Sekunde)
Rückgabe
Konnte der Timeout errfolgreich gesetzt werden, gibt die Funktion 1 zurück, im Fehlerfall 0.
void ppl6::CTCPSocket::SetSource ( const char *  host,
int  port = 0 
)
Beschreibung:
Diese Funktion kann aufgerufen werden, wenn der Rechner über mehrere Netzwerkinterfaces verfügt. Normalerweise entscheidet das Betriebssytem, welches Interface für eine ausgehende Verbindung verwendet werden soll, aber manchmal kann es sinnvoll sein, dies manuell zu machen.
Parameter
[in]hostHostname oder IP-Adresse des Quellinterfaces. Wird NULL angegeben, wird nur der port beachtet
[in]portPort-Nummer des Quellinterfaces. Wird 0 angegeben, wird nur der host beachtet
Achtung
Diese Funktionalität wird derzeit nicht unter Windows unterstützt! Falls trotzdem ein host oder port definiert wurden, wird die Connect-Funktion fehlschlagen!
Bemerkungen
Sind beide Parameter NULL bzw. 0, wird das Quellinterface und Port vom Betriebssystem festgelegt.
int ppl6::CTCPSocket::SetWriteTimeout ( int  seconds,
int  useconds 
)

Mit dieser Funktion kann ein Timeout für Schreibzugriffe gesetzt werden. Normalerweise blockiert eine Schreiboperation mit "Write" solange, bis alle Daten gesendet wurden. Mit dieser Funktion kann jedoch ein beliebiger mikrosekunden genauer Timeout festgelegt werden. Der Timeout errechnet sich dabei aus seconds + useconds.

Um den Timeout wieder abzustellen, kann die Funktion mit 0 als Wert für seconds und useconds aufgerufen werden.
Parameter
[in]secondsAnzahl Sekunden
[in]usecondsAnzahl Mikrosekunden (1000000 Mikrosekunden = 1 Sekunde)
Rückgabe
Konnte der Timeout errfolgreich gesetzt werden, gibt die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::Shutdown ( )
Beschreibung:
Durch Aufruf dieser Funktion wird eine bestehende Verbindung beendet. Unter Windows ist die Funktion identisch mit CTCPSocket::Shutdown, unter Unix unterscheiden sie sich.
CTCPSocket::Disconnect schließt den Socket-Descriptor für den Prozess, die Verbindung bleibt jedoch weiterhin bestehen, wenn ein anderer Prozess den gleichen Descriptor verwendet. Die Verbindung bleibt dann sowohl zum lesen als auch zum schreiben geöffnet.
CTCPSocket::Shutdown trennt die Verbindung für alle Prozesse, die den gleichen Descriptor verwenden. Falls ein anderer Prozess noch versucht auf den Socket zuzzugreifen, bekommt er eine Fehlermeldung. Beim Lesen ist dies meist ein EOF, beim Schreiben ein SIGPIPE, der möglicherweise Aufgrund von Puffern im Kernel nicht sofort auftreten muss.
Rückgabe
Die Funktion liefert immer 1 zurück.
int ppl6::CTCPSocket::SignalStopListen ( )
Beschreibung:
Durch Aufruf dieser Funktion innerhalb eines anderen Threads wird dem Server mitgeteilt, dass er nicht weiter auf Verbindungseingänge warten soll. Die Funktion kehrt dabei sofort zurück und es liegt an der Anwendung später zu prüfen, ob der Server wirklich gestoppt wurde (z.B. mit CTCPSocket::StopListen).
Rückgabe
Die Funktion liefert immer 1 zurück.
int ppl6::CTCPSocket::SSL_Accept ( )
Beschreibung:
SSL_Accept wartet darauf, dass der mit dem Socket verbundene Client eine TLS/SSL Verbindung startet. Ist der Socket auf "blocking" eingestellt, wartet die Funktion solange, bis ein Handshake erfolgt, die Verbindung getrennt wird oder ein Timeout auftritt. Die verwandte Funktion CTCPSocket::SSL_WaitForAccept wartet ebenfalls auf ein TLS/SSL Handshake, jedoch kann hier zusätzlich ein Timeout angegeben werden und die Funktion beendet sich, wenn der Thread beendet werden soll.
Rückgabe
Bei erfolgreichem Handshake liefert die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::SSL_CheckCertificate ( const char *  hostname,
bool  AcceptSelfSignedCert = false 
)
Beschreibung:
Mit dieser Funktion kann nach Herstellung einer SSL-Verbindung das Zertifikat der Gegenstelle geprüft werden. Dabei werden insbesondere auch die Signierungsketten bis zum Root-Zertifikat überprüft und dabei nicht nur die gängigen Root-Zertifikate, die in der OpenSSL-Library enthalten sind, berücksichtigt, sondern auch die, die zuvor manuell mit CSSL::LoadTrustedCAfromFile oder CSSL::LoadTrustedCAfromPath geladen wurden.
Parameter
[in]hostnameDer erwartete Name des Zertifikats. Wird NULL übergeben, wird der Name des Zertifikats nicht überprüft
[in]AcceptSelfSignedCertWird hier "true" angegeben, werden auch selbst-signierte Zertifikate akzeptiert.
Rückgabe
Ist das Zertifikat gültig und alle Prüfungen erfolgreich, gibt die Funktion 1 zurück, ansonsten 0.
int ppl6::CTCPSocket::SSL_GetCipherBits ( ) const
CString ppl6::CTCPSocket::SSL_GetCipherName ( ) const
CString ppl6::CTCPSocket::SSL_GetCipherVersion ( ) const
void ppl6::CTCPSocket::SSL_Info ( )
int ppl6::CTCPSocket::SSL_Init ( CSSL ssl)
Beschreibung:
Falls beabsichtigt wird mit diesem Socket verschlüsselt zu kommunizieren, muss diese Funktion noch vor Verbindungsaufbau aufgerufen werden. Als Parameter ssl bekommt sie einen Pointer auf eine CSSL-Klasse. Diese muss ebenfalls vor Verwendung initialisiert worden sein.
Parameter
[in]sslPointer auf eine CSSL-Klasse
Rückgabe
Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::SSL_Init_Client ( )
Beschreibung:
Diese Funktion muss aufgerufen werden, wenn über eine bereits bestehende TCP-Verbindung SSL-Verschlüsselung aktiviert werden soll. Dazu muss nach dem Connect zunächst CTCPSocket::SSL_Init_Client gefolgt von CTCPSocket::SSL_Start aufgerufen werden.
Rückgabe
Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::SSL_Init_Server ( )
Beschreibung:
Falls mit diesem Socket ein SSL-fähiger Server gestartet werden soll, muss nach Verbindungseingang CTCPSocket::Init_SSL gefolgt von dieser Funktion aufgerufen werden. Damit wird dem Client mitgeteilt, dass der Server nun verschlüsselt kommunizieren möchte. Mit CTCPSocket::SSL_Accept kann geprüft werden, ob der Client bereits zugestimmt hat, mit CTCPSocket::SSL_WaitForAccept wird gewartet, bis der Client zustimmt oder ein Timeout auftritt.
Rückgabe
Bei Erfolg gibt die Funktion 1 zurück, im Fehlerfall 0.
bool ppl6::CTCPSocket::SSL_IsEncrypted ( ) const
int ppl6::CTCPSocket::SSL_Read ( void *  buffer,
int  size 
)
private
Beschreibung:
Diese private Funktion wird intern automatisch von den Read-Funktionen der Socketklasse aufgerufen, wenn SSL-Verschlüsselung aktiviert wurde. Anstelle der Read-Funktionen der Socket-Schnittstelle des Betriebssystems wird dann diese Funktion verwendet. Sie liest size verschlüsselte Bytes von der Gegenstelle in den bereits allokierten Speicherbereich buffer und entschlüsselt sie dabei.
Parameter
[in]bufferBereits allokierter Speicherbereich, in den die gelesenen Daten geschrieben werden sollen
[in]sizeAnzahl zu lesender Bytes.
Rückgabe
Die Funktion gibt die Anzahl erfolgreich gelesener Bytes zurück, im Fehlefall 0 oder einen negativen Wert.
int ppl6::CTCPSocket::SSL_Shutdown ( )
Beschreibung:
Wurde mit dieser Socket-Klasse SSL-Verschlüsselung verwendet, muss nach beendigung der Verbindung diese Funktion aufgerufen werde. Dies wird vom Destruktor der Klasse automatisch durchgeführt, so dass ein manueller Aufruf durch die Anwendung in der Regel nicht erforderlich ist.
Rückgabe
Die Funktion gibt zur Zeit immer 1 zurück.
int ppl6::CTCPSocket::SSL_Start ( )
Beschreibung:
Durch Aufruf dieser Funktion wird die SSL-Kommunikation über eine bereits bestehende TCP-Verbindung zu einem Server gestartet. Um wieder unverschlüsselt kommunizieren zu können, muss CTCPSocket::SSL_Stop aufgerufen werden.
Rückgabe
Wenn die SSL-Kommunikation mit dem Server erfolgreich gestartet werden konnte, liefert die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::SSL_Stop ( )
Beschreibung:
Durch Aufruf dieser Funktion wird die SSL-Kommunikation zu einem Server wieder gestoppt. Sofern die Verbindung dadurch nicht geschlossen wird, kann mit der Gegenstelle wieder unverschlüsselt kommuniziert werden.
Rückgabe
Wenn die SSL-Kommunikation erfolgreich beendet werden konnte, liefert die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::SSL_WaitForAccept ( int  timeout = 0)
Beschreibung:
SSL_WaitForAccept wartet darauf, dass der mit dem Socket verbundene Client eine TLS/SSL Verbindung startet. Vor AUfruf sollte der Socket auf "non-Blocking" gestellt werden (siehe CTCPSocket::SetBlocking). Die Funktion wartet solange, bis entweder ein Handshake zustande kommt, der angegebene Timeout erreicht oder die Verbindung getrennt wurde, oder der Überwachungsthread (siehe CTCPSocket::WatchThread) beendet werden soll.
Parameter
timeoutEin Timeout in Sekunden. Bei Angabe von 0, wartet die Funktion unbegenzt lange.
Rückgabe
Bei erfolgreichem Handshake liefert die Funktion 1 zurück, im Fehlerfall 0.
int ppl6::CTCPSocket::SSL_Write ( const void *  buffer,
int  size 
)
private
Beschreibung:
Diese private Funktion wird intern automatisch von den Write-Funktionen der Socketklasse aufgerufen, wenn SSL-Verschlüsselung aktiviert wurde. Anstelle der Write-Funktionen der Socket-Schnittstelle des Betriebssystems wird dann diese Funktion verwendet. Sie schickt size Bytes aus dem Speicherbereich buffer verschlüsselt an die Gegenstelle.
Parameter
[in]bufferBeginn des zu sendenden Speicherbereichs
[in]sizeAnzahl zu sendender Bytes.
Rückgabe
Die Funktion gibt die Anzahl erfolgreich geschriebener Bytes zurück, im Fehlerfall 0 oder einen negativen Wert. Aus der Manpage zu SSL_write(3):
  • 0: The write operation was not successful. Probably the underlying connection was closed. Call SSL_get_error() with the return value ret to find out, whether an error occurred or the connection was shut down cleanly (SSL_ERROR_ZERO_RETURN).
SSLv2 (deprecated) does not support a shutdown alert protocol, so it can only be detected, whether the underlying connection was closed. It cannot be checked, why the closure happened.
  • <0: The write operation was not successful, because either an error occurred or action must be taken by the calling process. Call SSL_get_error() with the return value ret to find out the reason.
int ppl6::CTCPSocket::StopListen ( )
Beschreibung:
Durch Aufruf dieser Funktion innerhalb eines anderen Threads wird dem Server mitgeteilt, dass er nicht weiter auf Verbindungseingänge warten soll. Die Funktion kehrt dabei erst zurück, wenn der Server sich beendet hat. Falls man darauf nicht warten möchte, kann stattdessen auch CTCPSocket::SignalStopListen aufgerufen werden.
Rückgabe
Die Funktion liefert immer 1 zurück.
int ppl6::CTCPSocket::WaitForIncomingData ( int  seconds,
int  useconds 
)
Beschreibung:
Diese Funktion prüft, ob Daten eingegangen sind. Ist dies der Fall, kehrt sie sofort wieder zurück. Andernfalls wartet sie solange, bis Daten eingehen, maximal aber die mit seconds und useconds angegebene Zeitspanne. Falls seconds und useconds Null sind, und keine Daten bereitstehen, kehrt die Funktion sofort zurück.
Falls über die Funktion CTCPSocket::WatchThread ein Thread angegeben wurde, kehrt die Funktion nicht nach erreichen des Timeouts zurück, sondern erst wenn dem Thread ein Stopsignal gegeben wird, bzw. wenn Daten bereitstehen.
Parameter
[in]secondsAnzahl Sekunden, die gewartet werden soll
[in]usecondsAnzahl Mikrosekunden, die gewartet werden soll
Rückgabe
Die Funktion gibt 1 zurück, wenn Daten zum Lesen bereitstehen, sonst 0. Der Fehlercode 174 zeigt an, dass ein Timeout aufgetreten ist, und man die Funktion nochmal aufrufen kann. Alle anderen Fehlercodes weisen auf einen richtigen Fehler hin, meist einen Verbindungsabbruch.
int ppl6::CTCPSocket::WaitForMessage ( CSocketMessage msg,
int  timeout = 0 
)
Beschreibung:

Mit der Klasse ppl6::CpplSocketMessage und den Funktionen CpplSocket::Write und CpplSocket::WaitForMessage lassen sich bequem Nachrichten per TCP austauschen.

Jedes Nachrichtenpaket besteht dabei aus einem Header und den Nutzdaten.

Aufbau des Headers Version 1
Version 1 besteht aus einem 20 Byte langem Header mit folgendem Aufbau:
Byte 0: "V" (1 Byte)
Byte 1: Version=1 (1 Byte)
Byte 2: CommandId (2 Byte)
Byte 4: Id (4 Byte)
Byte 8: Bytes Nutzdaten (4 Byte)
Byte 12: Flags (1 Byte)
Bit 0: Zlib-Kompression
Bit 1: Client supports Zlib
Bit 2: Client supports MsgChannel
Byte 13: Datatype, PPL_ARRAY, usw. (1 Byte)
Byte 14: Zufallszahl (2 Byte)
Byte 16: CRC-Summe über den Header (4 Byte)

Die CRC-Summe wird über die ersten 16 Byte des Headers gebildet (siehe ppl6::crc32). Alle mehrbyteigen Werte müssen in Network-Byte-Order (Big Endian) angegeben werden.

Aufbau des Headers Version 2
Der Version 2-Header ist 4 Byte länger, die eine zusätzliche CRC-Summe über die Nutzdaten enthalten.
Byte 0: "V" (1 Byte)
Byte 1: Version=2 (1 Byte)
Byte 2: CommandId (2 Byte)
Byte 4: Id (4 Byte)
Byte 8: Bytes Nutzdaten (4 Byte)
Byte 12: Flags (1 Byte)
Bit 0: Zlib-Kompression
Bit 1: Client supports Zlib
Bit 2: Client supports MsgChannel
Byte 13: Datatype, PPL_ARRAY, usw. (1 Byte)
Byte 14: Zufallszahl (2 Byte)
Byte 16: CRC-Summe über die Nutzdaten (4 Byte)
Byte 20: CRC-Summe über den Header (4 Byte)
Die CRC-Summe des Headers wird über die ersten 20 Byte des Headers gebildet (siehe ppl6::crc32). Alle mehrbyteigen Werte müssen in Network-Byte-Order (Big Endian) angegeben werden.
int ppl6::CTCPSocket::WaitForOutgoingData ( int  seconds,
int  useconds 
)
Beschreibung:
Diese Funktion prüft, ob Daten auf den Socket geschrieben werden können. Ist dies der Fall, kehrt sie sofort wieder zurück. Andernfalls wartet sie solange, bis der Socket beschrieben werden kann, maximal aber die mit seconds und useconds angegebene Zeitspanne. Falls seconds und useconds Null sind, und keine Daten gesendet werden können, kehrt die Funktion sofort zurück.
Falls über die Funktion CTCPSocket::WatchThread ein Thread angegeben wurde, kehrt die Funktion nicht nach erreichen des Timeouts zurück, sondern erst wenn dem Thread ein Stopsignal gegeben wird, bzw. wenn der Socket beschrieben werden kann.
Parameter
[in]secondsAnzahl Sekunden, die gewartet werden soll
[in]usecondsAnzahl Mikrosekunden, die gewartet werden soll
Rückgabe
Die Funktion gibt 1 zurück, wenn Daten geschrieben werden können, sonst 0. Der Fehlercode 174 zeigt an, dass ein Timeout aufgetreten ist, und man die Funktion nochmal aufrufen kann. Alle anderen Fehlercodes weisen auf einen richtigen Fehler hin, meist einen Verbindungsabbruch.
int ppl6::CTCPSocket::WatchThread ( CThread thread)
Beschreibung:
Mit dieser Funktion kann der Klasse ein Überwachungsthread mitgeteilt werden. Verschiedene Funktionen der Socket-Klasse, die üblicherweise in einer Endlosschleife laufen oder erst wiederkehren, wenn bestimmte Voraussetzungen erfüllt sind, prüfen diese Threadklasse, ob Ihr ein Stop signalisiert wurde. Ist dies der Fall, beenden sich diese Funktionen ebenfalls.
Bemerkungen
Eventuell wird diese Funktionalität nochmal überarbeitet.
Parameter
[in]threadPointer auf die zu überwachende Thread-Klasse
Rückgabe
Liefert immer 1 zurück.
int ppl6::CTCPSocket::Write ( const CString str)
Beschreibung:
Mit dieser Funktion wird der Inhalt des Strings str an die Gegenstelle gesendet.
Parameter
[in]strReferenz auf eine CString-Klasse
Rückgabe
Wenn die Daten erfolgreich geschrieben wurden, gibt die Funktion 1 zurück, im Fehlerfall 0. Falls ein Fehler aufgetreten ist, kann mit der Funktion CTCPSocket::GetBytesWritten abgefragt werden, wieviele Bytes wirklich geschrieben wurden.
int ppl6::CTCPSocket::Write ( const CBinary bin)
Beschreibung:
Mit dieser Funktion wird der Inhalt des CBinary-Objekts bin an die Gegenstelle gesendet.
Parameter
[in]binReferenz auf eine CBinary-Klasse
Rückgabe
Wenn die Daten erfolgreich geschrieben wurden, gibt die Funktion 1 zurück, im Fehlerfall 0. Falls ein Fehler aufgetreten ist, kann mit der Funktion CTCPSocket::GetBytesWritten abgefragt werden, wieviele Bytes wirklich geschrieben wurden.
int ppl6::CTCPSocket::Write ( const CString str)
Beschreibung:
Mit dieser Funktion wird der Inhalt des Strings str an die Gegenstelle gesendet.
Parameter
[in]strPointer auf eine CString-Klasse
Rückgabe
Wenn die Daten erfolgreich geschrieben wurden, gibt die Funktion 1 zurück, im Fehlerfall 0. Falls ein Fehler aufgetreten ist, kann mit der Funktion CTCPSocket::GetBytesWritten abgefragt werden, wieviele Bytes wirklich geschrieben wurden.
int ppl6::CTCPSocket::Write ( const void *  buffer,
int  bytes 
)
Beschreibung:
Mit dieser Funktionen werden bytes Bytes aus dem Speicherbereich buffer an die Gegenstelle gesendet.
Parameter
[in]bufferPointer auf die zu sendenden Daten
[in]bytesAnzahl zu sendender Bytes
Rückgabe
Wenn die Daten erfolgreich geschrieben wurden, gibt die Funktion 1 zurück, im Fehlerfall 0. Falls ein Fehler aufgetreten ist, kann mit der Funktion CTCPSocket::GetBytesWritten abgefragt werden, wieviele Bytes wirklich geschrieben wurden.
int ppl6::CTCPSocket::Write ( CSocketMessage msg)
Beschreibung:

Mit der Klasse ppl6::CpplSocketMessage und den Funktionen CpplSocket::Write und CpplSocket::WaitForMessage lassen sich bequem Nachrichten per TCP austauschen.

Jedes Nachrichtenpaket besteht dabei aus einem Header und den Nutzdaten.

Aufbau des Headers Version 1
Version 1 besteht aus einem 20 Byte langem Header mit folgendem Aufbau:
Byte 0: "V" (1 Byte)
Byte 1: Version=1 (1 Byte)
Byte 2: CommandId (2 Byte)
Byte 4: Id (4 Byte)
Byte 8: Bytes Nutzdaten (4 Byte)
Byte 12: Flags (1 Byte)
Bit 0: Zlib-Kompression
Bit 1: Client supports Zlib
Bit 2: Client supports MsgChannel
Byte 13: Datatype, PPL_ARRAY, usw. (1 Byte)
Byte 14: Zufallszahl (2 Byte)
Byte 16: CRC-Summe über den Header (4 Byte)

Die CRC-Summe wird über die ersten 16 Byte des Headers gebildet (siehe ppl6::crc32). Alle mehrbyteigen Werte müssen in Network-Byte-Order (Big Endian) angegeben werden.

Aufbau des Headers Version 2
Der Version 2-Header ist 4 Byte länger, die eine zusätzliche CRC-Summe über die Nutzdaten enthalten.
Byte 0: "V" (1 Byte)
Byte 1: Version=2 (1 Byte)
Byte 2: CommandId (2 Byte)
Byte 4: Id (4 Byte)
Byte 8: Bytes Nutzdaten (4 Byte)
Byte 12: Flags (1 Byte)
Bit 0: Zlib-Kompression
Bit 1: Client supports Zlib
Bit 2: Client supports MsgChannel
Byte 13: Datatype, PPL_ARRAY, usw. (1 Byte)
Byte 14: Zufallszahl (2 Byte)
Byte 16: CRC-Summe über die Nutzdaten (4 Byte)
Byte 20: CRC-Summe über den Header (4 Byte)
Die CRC-Summe des Headers wird über die ersten 20 Byte des Headers gebildet (siehe ppl6::crc32). Alle mehrbyteigen Werte müssen in Network-Byte-Order (Big Endian) angegeben werden.
int ppl6::CTCPSocket::WriteBuffer ( const void *  buffer,
int  bytes 
)
Beschreibung:
Mit dieser Funktionen werden bytes Bytes aus dem Speicherbereich buffer an die Gegenstelle gesendet.
Parameter
[in]bufferPointer auf die zu sendenden Daten
[in]bytesAnzahl zu sendender Bytes
Rückgabe
Wenn die Daten erfolgreich geschrieben wurden, gibt die Funktion 1 zurück, im Fehlerfall 0. Falls ein Fehler aufgetreten ist, kann mit der Funktion CTCPSocket::GetBytesWritten abgefragt werden, wieviele Bytes wirklich geschrieben wurden.
int ppl6::CTCPSocket::Writef ( const char *  fmt,
  ... 
)
Beschreibung:
Mit dieser Funktion wird zunächst ein String anhand der des angegebenen Formatierungsstrings fmt und den zusätzlichen optionalen Parametern gebildet und dieser an die Gegenstelle gesendet.
Parameter
[in]fmtFormatierungsstring
[in]...Optionale Parameter für den Formatierungsstring
Rückgabe
Wenn die Daten erfolgreich geschrieben wurden, gibt die Funktion 1 zurück, im Fehlerfall 0. Falls ein Fehler aufgetreten ist, kann mit der Funktion CTCPSocket::GetBytesWritten abgefragt werden, wieviele Bytes wirklich geschrieben wurden.

Freundbeziehungen und Funktionsdokumentation

static int out_bind ( const char *  host,
int  port 
)
related
Beschreibung:
Diese Funktion wird intern durch die Connect-Funktionen aufgerufen, um einen ausgehenden Socket auf ein bestimmtes Netzwerk-Interface zu binden. Die Funktion wird nur dann verwendet, wenn mit CTCPSocket::SetSource ein Quellinterface definiert wurde.
Parameter
[in]hostHostname oder IP des lokalen Interfaces
[in]portPort auf dem lokalen Interface
Rückgabe
Bei Erfolg liefert die Funktion die File-Nummer des Sockets zurück, im Fehlerfall 0.
static int ppl_connect_nb ( int  sockfd,
struct sockaddr *  serv_addr,
int  addrlen,
int  sec,
int  usec 
)
related
Beschreibung:
Diese Funktion wird intern durch die Connect-Funktionen aufgerufen, um einen nicht blockierenden Connect auf die Zieladresse durchzuführen. Normalerweise würde ein Connect solange blockieren, bis entweder ein Fehler festgestellt wird, die Verbindung zustande kommt oder das Betriebssystem einen Timeout auslöst. Letzteres kann aber mehrere Minuten dauern. Mit dieser Funktion wird ein non-blocking-connect durchgeführt, bei dem der Timeout mikrosekundengenau angegeben werden kann.
Parameter
[in]sockfdFile-ID des Sockets
[in]serv_addrIP-Adressenstruktur mit der Ziel-IP un dem Ziel-Port
[in]addrlenDie Länge der Adressenstruktur
[in]secTimeout in Sekunden
[in]usecTimeout in Mikrosekunden. Der tatsächliche Timeout errechnet sich aus sec + usec
Rückgabe
Bei Erfolg liefert die Funktion 1 zurück, im Fehlerfall 0.
Zu beachten
Zur Zeit wird diese Funktion nur unter Unix unterstützt.

Dokumentation der Datenelemente

int ppl6::CTCPSocket::BytesRead
private
int ppl6::CTCPSocket::BytesWritten
private
int ppl6::CTCPSocket::connect_timeout_sec
private
int ppl6::CTCPSocket::connect_timeout_usec
private
int ppl6::CTCPSocket::connected
private
CString ppl6::CTCPSocket::HostName
private
int ppl6::CTCPSocket::islisten
private
CLog* ppl6::CTCPSocket::log
private
CMutex ppl6::CTCPSocket::mutex
private
int ppl6::CTCPSocket::PortNum
private
void* ppl6::CTCPSocket::socket
private
CString ppl6::CTCPSocket::SourceHost
private
int ppl6::CTCPSocket::SourcePort
private
void* ppl6::CTCPSocket::ssl
private
CSSL* ppl6::CTCPSocket::sslclass
private
void* ppl6::CTCPSocket::sslreference
private
bool ppl6::CTCPSocket::stoplisten
private
CThread* ppl6::CTCPSocket::thread
private

Die Dokumentation für diese Klasse wurde erzeugt aufgrund der Dateien: