Network and Web Libraries
Ruby provides two levels of access to network services. At a low level, you can access the basic socket support in the underlying operating system, which allows you to implement clients and servers for both connection-oriented and connectionless protocols. These are documented in the next section.
Ruby also has libraries that provide higher-level access to specific application-level network protocols, such as FTP, HTTP, and so on. These are documented starting on page 482.
Finally, the
CGI libraries, documented beginning on page 497, provide server-side developers with a convenient interface for developing Web applications.
Socket-Level Access
Sockets are the endpoints of a bidirectional communications channel. Sockets may communicate within a process, between processes on the same machine, or between processes on different continents. Sockets may be implemented over a number of different channel types: Unix domain sockets, TCP, UDP, and so on. The socket library provides specific classes for handling the common transports as well as a generic interface for handling the rest. All functionality in the socket library is accessible through a single extension library. Access it using
Sockets have their own vocabulary:
- domain
- The family of protocols that will be used as the transport mechanism. These values are constants such as
PF_INET, PF_UNIX, PF_X25, and so on.
- type
- The type of communications between the two endpoints, typically
SOCK_STREAM for connection-oriented protocols and SOCK_DGRAM for connectionless protocols.
- protocol
- Typically zero, this may be used to identify a variant of a protocol within a domain and type.
- hostName
- The identifier of a network interface:
- a string, which can be a host name, a dotted-quad address, or an IPV6 address in colon (and possibly dot) notation,
- the string ``<broadcast>'', which specifies an
INADDR_BROADCAST address,
- a zero-length string, which specifies
INADDR_ANY, or
- an
Integer, interpreted as a binary address in host byte order.
- port
- (sometimes called service) Each server listens for clients calling on one or more ports. A port may be a
Fixnum port number, a string containing a port number, or the name of a service.
Sockets are children of class
IO. Once a socket has been successfully opened, the conventional I/O methods may be used. However, greater efficiency is sometimes obtained by using socket-specific methods. As with other I/O classes, socket I/O blocks by default. The hierarchy of the socket classes is shown in Figure 26.1 on page 471.
For more information on the use of sockets, see your operating system documentation. You'll also find a comprehensive treatment in W. Richard Stevens,
Unix Network Programming, Volumes 1 and 2 .
Index:
do_not_reverse_lookup do_not_reverse_lookup= lookup_order lookup_order=
close_read close_write getpeername getsockname getsockopt recv send setsockopt shutdown
BasicSocket is an abstract base class for all other socket classes.
This class and its subclasses often manipulate addresses using something called a
struct sockaddr, which is effectively an opaque binary string.
[In reality, it maps onto the underlying C-language struct sockaddr set of structures, documented in the man pages and in the books by Stevens.]
| class methods |
| do_not_reverse_lookup |
BasicSocket.do_not_reverse_lookup -> true or false |
|
Returns the value of the global reverse lookup flag. If set to true, queries on remote addresses will return the numeric address but not the host name.
|
| do_not_reverse_lookup= |
BasicSocket.do_not_reverse_lookup = true or false |
|
Sets the global reverse lookup flag.
|
| lookup_order |
BasicSocket.lookup_order -> aFixnum |
|
Returns the global address lookup order, one of:
|
Order |
Families Searched |
LOOKUP_UNSP |
AF_UNSPEC |
LOOKUP_INET |
AF_INET, AF_INET6, AF_UNSPEC |
LOOKUP_INET6 |
AF_INET6, AF_INET, AF_UNSPEC |
 |
|
| lookup_order= |
BasicSocket.lookup_order = aFixnum |
|
Sets the global address lookup order.
|
| instance methods |
| close_read |
aSession.close_read -> nil |
|
Closes the readable connection on this socket.
|
| close_write |
aSession.close_write -> nil |
|
Closes the writable connection on this socket.
|
| getpeername |
aSession.getpeername -> aString |
|
Returns the struct sockaddr structure associated with the other end of this socket connection.
|
| getsockname |
aSession.getsockname -> aString |
|
Returns the struct sockaddr structure associated with aSession.
|
| getsockopt |
aSession.getsockopt( level, optname ) -> aString |
|
Returns the value of the specified option.
|
| recv |
aSession.recv( len, [, flags ] ) -> aString |
|
Receives up to len bytes from aSession.
|
| send |
aSession.send( aString, flags, [, to ] ) -> aFixnum |
|
Sends aString over aSession. If specified, to is a struct sockaddr specifying the recipient address. flags are the sum or one or more of the MSG_ options (listed on page 478). Returns the number of characters sent.
|
| setsockopt |
aSession.setsockopt( level, optname, optval ) -> 0 |
|
Sets a socket option. level is one of the socket-level options (listed on page 478). optname and optval are protocol specific---see your system documentation for details.
|
| shutdown |
aSession.shutdown( how=2 ) -> 0 |
|
Shuts down the receive (how == 0), or send (how == 1), or both (how == 2), parts of this socket.
|
|
|
class IPSocket |
| Parent: |
BasicSocket |
| Version: |
1.6 |
|
Index:
getaddress
addr peeraddr
Class
IPSocket is a base class for sockets using IP as their transport.
TCPSocket and
UDPSocket are based on this class.
| class methods |
| getaddress |
IPSocket.getaddress( hostName ) -> aString |
|
Returns the dotted-quad IP address of hostName.
a = IPSocket.getaddress('www.ruby-lang.org') |
a |
|
|
