2.3 Key Abstractions

The Essential Networking Module contains classes that encapsulate basic networking and C++ concepts. To understand how all the classes are used together, however, you need only two key abstractions: portals and sockets.

Class RWPortal of the Essential Networking Module is an encapsulation of the portal concept. Its derived class RWSocketPortal is the first class you encounter when making a connection to a network.

When you use the Essential Networking Module, you are usually either connecting to a remote server as a client, or waiting for remote clients to connect to you as a server. For either task, you use RWSocketPortal. We already used RWSocketPortal when connecting to a remote server in Section 2.2.1, "A Simple Code Example." Here's another example:

RWSocketPortal sp(RWInetAddr(80, "www.roguewave.com")); //1

In //1, we create a connection to www.roguewave.com, port 80, using class RWSocketPortal. Notice that we initialize the RWSocketPortal with an RWInetAddr object. RWInetAddr encapsulates an Internet address and can be constructed using a port and a host, as shown here.

Once we have created the connection using RWSocketPortal, it can work with the familiar C++ iostreams to send and receive data. Let's continue the example:

RWSocketPortal sp(RWInetAddr(80, "www.roguewave.com")); //1 RWPortalIStream istr(sp); //2 RWPortalOStream os(sp); //3 os << "GET / HTTP/1.0\r\n" << flush; //4 while(istr.good()) { //5 RWCString data; data.readLine(istr); cout << data << flush; }

On //2 and //3, we use RWPortalIStream and RWPortalOStream to give us a high-level iostream interface to our network connection. These classes derive from istream and ostream, respectively, and can be used anywhere a standard iostream is used.

On //4, we write our HTTP request. Finally, in the while loop beginning on //5, we read each line of the response using RWCString::readLine(), a member function that reads a line from the given stream into the RWCString, and echo it to cout. That's all there is to it. Of course, we could write an even simpler version of this program by using the prebuilt HTTP classes in the Internet Protocols Module, but this example shows how easy it is to use classes of the Essential Networking Module alone. For more information on transferring data using streams, see Chapter 5, "Streams."

As we have mentioned, class RWPortal is an encapsulation of the portal concept, a high-level abstraction used in network programming with Rogue Wave products. Class RWPortal is a base for classes such as RWSocketPortal, RWBufferedRecvPortal and RWBufferedSendPortal, and is used for writing code that sends or receives data over a network connection without regard for a particular networking transport protocol or technology. For example, consider the following function:

void serviceClient(RWPortal& p) { RWPortalIStream is(p); RWPortalOStream os(p); Request request; is >> request; // read the client request Response response(request); os << response; // send our response // now process the remaining data on is... }

Because of the way this code is written, it could be used to service clients of an imaginary server, regardless of the transport protocol used in implementing the server. Of course, a transport protocol must be chosen at some point, but that doesn't mean all networking code must be implemented in a way that is specific to that protocol. By keeping transport protocol details out of the code as much as possible, we increase our chances for code reuse.

In the Essential Networking Module, you would use the high-level class RWPortal and derived classes such as RWSocketPortal to write most of your code. These classes are discussed in Chapter 4, "Portals." To make custom modifications to your network connections, you would then work with lower level classes such as RWSocket, which is described in Chapter 7, "The Berkeley Sockets Adapter," and Chapter 8, "The Windows Socket Adapter," and discussed in the following section.

In the Essential Networking Module, class RWSocket provides low-level socket functionality for TCP/IP. Internally, class RWSocket is implemented with calls to the Berkeley sockets API provided by the operating system. You will use RWSocket member functions directly for those times when you want to work with low-level details of your network connection, and you don't need a higher-level interface. Here's an example:

RWSocket s; //1 s.connect(RWInetAddr(80,"www.roguewave.com")); //2 s.sendAtLeast("GET / HTTP/1.0\r\n"); //3 s.shutdownwrite(); //4

On //1, we create an RWSocket using its default constructor. On //2, we connect the socket to www.roguewave.com, port 80. On //3, we use the function sendAtLeast() to send a string to the remote host, and on //4, we shut down the writing side of the socket.

This code example illustrates a perfectly legitimate use of RWSocket appropriate to development requiring low-level control. Since such direct use can be difficult, however, the class is actually more commonly used in conjunction with the higher-level portal abstraction. Class RWSocketPortal multiply inherits from both RWPortal and RWSocket. For this reason, it can provide both the easy-to-use RWPortal interface and the RWSocket flexibility to freely mix high-level portal usage with lower-level socket calls. For example:

RWSocketPortal sp(RWInetAddr(80, "www.roguewave.com")); RWPortalOStream os(sp); os << "GET / HTTP/1.0\r\n" << flush; //1 cout << "Sent request to: " << sp.getpeername() << endl; //2

On //1, RWPortalOStream is used to send a request to the server, using the higher-level portal interface. However, on //2 we use the lower-level getpeername() method, inherited from RWSocket, to obtain the name of the host to which the RWSocketPortal is connected.

This is a very typical use of RWSocket. You will probably avoid using RWSocket members directly for most tasks since you can perform them through the higher-level APIs provided in the rest of the product. If you need to work directly with the low-level details of a network connection, however, you'll use RWSocket directly. RWSocket is discussed in more detail in Chapter 6, "Socket Addresses."

Class RWSocketListener is another commonly used class of the Essential Networking Module. This class makes it easy to create server applications by encapsulating the work needed to listen for and accept incoming connections. An RWSocketListener creates a listening socket, which can wait for incoming connections. Its overloaded operator() waits for a connection and returns it as a new RWSocketPortal. To use RWSocketListener, just create one with the port you'd like to listen on as shown:

RWSocketListener listener(RWInetAddr(1234)); // 1 while(1) { RWSocketPortal socketPortal = listener(); // 2 serviceClient(socketPortal); // 3 }

On //1, we create a new RWSocketListener, telling it to listen for new connections on port 1234. This sets up a queue for incoming connections, but does not cause the program to wait for a new connection. On //2 we wait for the new connection by invoking the listener as if it were a function, made syntactically possible by the RWSocketListener overloaded operator().

Once a client connects to our port 1234, an RWSocketPortal connected to the new client is returned on //2. On //3, the client is serviced in our imaginary serviceClient() function that we created in Section 2.3.1.2, "RWPortal as a Base." In a real server, serviceClient() might hand the new connection to a separate thread to be serviced. Since local objects declared inside a while loop are destroyed and recreated on each loop iteration, the connection to each client is automatically closed.

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.