Reading Data

The conexus::Endpoint class provides a pure virtual method with the following prototype for reading data from an endpoint:

 virtual Data read(size_t max_octets = 0) throw (read_error) = 0;
This method is similar to the POSIX API read method, which has the following prototype:
 ssize_t read(int fd, void *buf, size_t count);
The following list examines the differences between the POSIX API read() function and the conexus library read() method, and explains the reasons for differing.
  1. Difference: The return value is an instance of conexus::Data rather than the number of bytes read.
  2. Difference: The conexus read() method does not accept a file descriptor as a parameter.
  3. Difference: The conexus read() method does not accept a pointer in which the read data will be stored.

Despite the differences, there remains a similarity between the max_octets and the count parameter. In the POSIX API the count parameter is used to indicate that buf points to an allocated storage area of at least count octets, and additionally places an upper limit on the number of octets that will be read in. The max_octets fills the latter role, and indicates the upper limit on the octets to read in. As with the POSIX API, the actual number of octets read may not be equal to the requested octets. The return conexus::Data object's size member will indicate the actual number of octets read, while the data member will contain a smart pointer to the actual data.

The following image illustrates the sequence of operations in receiving data via the read() method.

read.png

Sequence of operations that occur when the read() method is called.

When a callback has been registered with the endpoint a read() operation will simultaneously deliver the endpoint data to the read() method caller and to all connected callbacks.

The following image illustrates the sequence of operations in receiving data via the read() method when a callback has been registered with the endpoint.

read_with_callback.png

Sequence of operations that occur when the read() method is called and a callback has been registered with the endpoint.


Generated on Sun Aug 6 12:16:57 2006 by  doxygen 1.4.6