Programming Manual for SABUL 2.2


Table of Contents

I. Introduction

II. Application Programming Interface

CSabulSender:

CSabulRecver:

III. Exception Handling

IV. Examples

V. Specific Note


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

TOP

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.

 

TOP

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
}

TOP

IV. Specific Note

SABUL is not thread safe in the current version. Using "send" or "recv" in multi-threads may cause undefined error.

TOP