Programming Manual for SABUL 2.2
Table of Contents
I. Introduction
II. Application Programming Interface
III. Exception Handling
IV. Examples
I. Introduction
SABUL 2.x is implemented in C++. It provides two classes to users: CSabulSender and CSabulRecver, for data sending and receiving, respectively.
Header file:
#include <sender.h>
#inlcude <recver.h>
You may need to use the -I option in Makefile to include the .h path, e.g., -I./src
Library:
libsabul.a
A SABUL session is uni-directional. A SABUL entity starts with an "open" call and ends with a "close" call. A sender starts the session by calling "listen" method, and waiting for a receiver to connect to it with a "connect" call.
Examples:
SABUL sender: appserver.cpp, SABUL receiver: appclient.cpp
SABUL can send or receive a disk file directly. File and in-memory data transfer are orthogonal, i.e., a SABUL entity can send or receive either in-memory data or disk file, no matter which method its peer side uses.
Examples:
To send a file: sendfile.cpp, To Receive a file:
recvfile.cpp
II. Application
Programming Interface
2.1 CSabulSender public methods:
int open(const int& port = 0);
Description | Open a SABUL connection at port number of the parameter |
Parameters | 0) port: The port number that the application expects SABUL to bind |
Returned Value | The real port number that SABUL is binded to (may be different from "port" if it is not available). |
void listen();
Description | The sender uses listen() after open() to wait for a receiver to connect to. |
Parameters | None. |
Returned Value | None.. |
void close();
Description | Close the SABUL session. |
Parameters | None. |
Returned Value | None.. |
bool send(const char* data, const int& len);
Description | Send data starting from address "data" with size of "len". |
Parameters | 0) data: The pointer to a memory block to be sent. 1) len: the size of the buffer to be sent. |
Returned Value | True if successful; otherwise return false. |
bool sendfile(const int& fd, const int& offset, const int& size);
Description | Send data from a disk file with file descriptor "fd", started from "offset" and the data size is "size". |
Parameters | 0) fd: The file descriptor. 1) offset: From which position to read and send data. 1) size: the size of the data to be sent. |
Returned Value | True if successful; otherwise return false. |
void setRate(const double& initrate, const double& l_limit = 0, const
double& u_limit = 1000);
Description | Set the initial sending rate, the lower limit of the sending rate, and the upper limit of the sending rate. Data is in Mbps. |
Parameters | 0) initrate: The initial data sending rate. 1) l_limit: The lower limit of the sending rate. 2) u_limit: The upper limit of the sending rate. |
Returned Value | None. |
int getCurrBufSize();
Description | Query the size of the data that is waiting to be sent out. |
Parameters | None |
Returned Value | The size of the data remaining in the sender side buffer. |
Special note | This method is particularly useful when the application
uses non-blocking sending and it is difficult for it to decide when it can safely quit the procedure or if the data has been successfully sent out. |
void setOpt(SblOpt optName, const int& optval, const int& optlen);
Description |
Set up SABUL options. SBL_BLOCK: If the value is 0, the data sending is non-blocking, otherwise it is blocking. "sendfile" method is always blocking and is not affected by this option. The default value is 0. If non-blocking mode is activated, SABUL will try to release the sent data buffer automatically. SBL_VERBOSE: If this value is 0, SABUL will output data loss and sending rate information to the screenl otherwise, it outputs to a log file. |
Parameters | 0) optName: SBL_BLOCK, or SBL_VERBOSE 1) optval: The value of the options. [should be true or false] 2) optlen: size of the "optval". |
Returned Value | None. |
Example | bool block = false; sender->setOpt(SBL_BLOCK, &block, sizeof(block)); |
int getOpt((SblOpt optName, const int& optval, const int& optlen);
Description | Read the current configuration of SABUL. |
Parameters | 0) optName: SBL_BLOCK, or SBL_VERBOSE 1) optval: The value of the option assigned in "optName". 2) optlen: size of the returned "optval". |
Returned Value | It always returns 0. |
2.2 CSabulRecver Public Methods:
int open(const char* ip, const int& port);
Description | Open a SABUL receiver entity and connect to the sender listening at "ip":"port". |
Parameters | 0) ip: the sender IP address 1) port: The sender port number |
Returned Value | The actual port number that the receiver is bound to. |
void close();
Description | Close the SABUL receiver. |
Parameters | None. |
Returned Value | None. |
long recv(char* data, const long& len);
Description | Received data with size of "len" to memory buffer pointed by "data". |
Parameters | 0) data: The memory buffer to put data into. 1) len: The expected size of data to be received. |
Returned Value | The actual size of data received. |
long recvfile(const int& fd, const int& offset, const int& size);
Description | Received data to a disk file with file descriptor "fd", started from "offset" and the data size is "size". |
Parameters | 0) fd: The file descriptor. 1) offset: From which position to write received data. 2) size: The expected size of data to be received. |
Returned Value | The actual size of data received. |
III. Exception handling
SABUL uses the C++ exception handling mechanism to throw and catch exceptions. It does NOT return any error codes.
The application should use the following example codes to handle error and exceptions.
Try
{
//some SABUL methods call like
//sabul->open(ip, port);
}
catch (...)
{
//process exception
}
IV. Specific Note
SABUL is not thread safe in the current version. Using "send" or "recv" in multi-threads may cause undefined error.