Read Me

CBNTk

Authors

Vit Stancl(stancl@fit.vutbr.cz), Michal Spanel (spanel@fit.vutbr.cz), Radek Barton (ibarton@fit.vutbr.cz), Miroslav Svub (svub@fit.vutbr.cz) and Ondrej Siler (siler@fit.vutbr.cz)

  
Intorduction

'c'Url 'B'ased 'M'ultithreaded 'N'etworking 'T'ool'k'it is a C++ library used by PGMed group as a low level, object oriented layer between cURL and an application. Library simplifies common cURL tasks - creating network session, connecting and disconnecting, transfers. As an addition, a simple but powerful multithreaded job control classes are included. This file contains basic overview of the library, basic concepts description and example explanation. See doc directory for the further info.

The library is coded in C++ and CMake (www.cmake.org) is used as a building tool. In order to build toolkit, cURL library (curl.haxx.se) and MDSTk (mdstk.sourceforge.net) is required. 

This library is distributed under the LGPL license - see licence.txt file.


Basic concepts

This is overview only. See doxygen documentation in the doc directory for the more info.
Toolkit can be divided into the three parts - base cURL C++ wrapper (curlTools directory), higher level networking layer and multithreading support (comm directory). Now we will describe cURL wrapper. This is only wrapper so for more information about possible parameters, settings and return values of the methods see libcurl documentation.        

1) Networking layer

Basic curl functionality is hidden in the CCurl class. Curl easy interface is in the CCurlEasy class and multi interface is in the CCurlMulti class. There is CCurlShared class that implements shared interface, but was not ever tested and used. Curl options are encapsulated in CCurlOptionBase class and in its derivatives. Form is described in CForm class (adding string variables), header parsing can be done by CHeaderReader. Curl linked lists are encapsulated by CSList class. 

On this really low level wrapper is based more complex layer. But at first some bit philosophical issues must be reviewed. Sending and receiving data in the toolkit is based on the dispatcher/receiver concept. Dispatcher is en entity that can feed data into the sending channel, receiver can receive incoming data. If you want do some transfers, you must have at least one dispatcher, one receiver and some connection. Now we will continue more precisely.

Dispatching data (feeding data into the connection channel) is work for CDispatcher class. When system needs some data, the dispatch() method is called. You can read data from a buffer, from file or generate them. Just implement your own dispatcher. The same principle is used when packet is received. The CReceiver class has a virtual receive() method.

All connections (from client to the server) are based on CConnection (template) class. Parameters of the connection can be set by setParams method. Just create CConnection object, set URL and call perform method. Dispatcher and receiver are called when needed. This procedure is described in example1.cpp.

Some predefined data transfer modules (dispatchers and receivers) are included - buffer reading/writing (CBufferDispatcher/Receiver - bufferdt file), standard stream input-output (CStdStreamDispatcher/Receiver - stdstream file) and null input and output. If you need some more functionality, just derive your own dispatcher or receiver, set it into the CConnection and use it. This can be seen in the example2.cpp file.


2) Multithreading 

Multithreading layer can be divided into the two subparts - common job processing technique and its networking specialization. Job processing technique conception is universally known - thread pool, jobs queue and jobs manager that assigns job to the threads. This functionality is hidden in the CThreadPool and CJob template classes. CJob class can do anything you want. You must only define your own virtual process() method. Its specializations are used to do the multithreaded networking task. See example3.cpp to see how to use multithreaded networking interface. 


Known restrictions

The Dispatcher-Receiver-Connection concept is not as general as it could be as it is implemented now. The CConnection template is parameterized by dispatcher&receiver type and so this type cannot be changed on run. This concept was quite sufficient for us.