Network Library

PreviousNext

Classic Network API

Overview

The classic network API establishes the basis for more complex classes like protocol implementations. (HTTP, SMTP, POP, ...) or class libraries like the Multiplayer Framework.
This page describes the usage of the core classes for network development.

Hint: As soon as you start network developping debugging is no longer a local process but a distributed one. Use network tools like sniffers/protocol analyzers. A popular one is ethereal.

About Internet addresses

Every host on the Internet has an address, which is unique on the whole network. Such an IP address is represented by the class EM_INET_ADDRESS. You can create an Internet address for the local host using make_local and for remote hosts with make_by_hostname, which will automatically resolve the host using an external DNS. For better performance, especially if you create a lot of Internet addresses, you should consider to use the creation procedures make_by_ip or make_by_ip_string, which will not query any naming service. This is particularly important on Linux based system, because tests have shown that they do not necessarily cache previous DNS queries, resulting in a very poor performance. Should you later need the hostname nevertheless, you’ve the option to retrieve it using reverse_resolve_blocking.

Note: Currently there’s only IPv4 support, since there exist no SDL_net implementation for the new IPv6.

As you’ve seen, EM_INET_ADDRESS represents an entire host on a network, where as EM_INET_SOCKET_ADDRESS specifies a single socket on a host. In other words, an Internet socket address is just an Internet address with an additional port.

You’ve the possibility to create an EM_INET_SOCKET_ADDRESS out of an existing EM_INET_ADDRESS. In this case you’ll use make_by_inet_address_port. On the other hand, you can also create a fresh socket address. The creation procedures for the later method are very similar to the ones you’ve seen before, except that there is always an additional port number you need to pass as argument.

Internet and socket addresses are used throughout the entire Network API. They provide a generic way to address hosts or specific sockets in a network.

TCP - Transmission Control Protocol

If you need to transmit data over a reliable channel, you can use EiffelMedia's built-in TCP support.

For the server side, you need to take a look at EM_TCP_SERVER_SOCKET. To create a server that listens on a specific port, you call open after you’ve set a port with set_port. Incoming connection attempts will then fire an event to all subscribers of the connection_accepted_event. The event will pass an instance of EM_TCP_CLIENT_SOCKET as argument, which is then used to transmit the actual data.

Note: This instance is already connected to the other side.

To establish a connection to a server, you’ll also use an EM_TCP_CLIENT_SOCKET. After having set the remote address using the creation procedure make_from_address or some of the setters, you can connect to the remote side by calling connect.

The following events are available for subscription:

Sending data is very easy, just call send_string. Close the connection by calling disconnect.

How do I...

UDP - User Datagram Protocol

UDP support in EiffelMedia is provided by the three classes EM_SIMPLE_UDP_SOCKET, EM_UDP_SOCKET and EM_UDP_PACKET.

All data that is being sent or received by UDP is encapsulated in an EM_UDP_PACKET. Every packet has an address, which can either be its source address or its destination address, depending on the usage of the packet. You can change this address using set_address. The actual data is available in item and can bet set with put_string. To send or receive a packet, you’ll need an EM_SIMPLE_UDP_SOCKET. open starts listening on all local interfaces on a specific port.

Note: It is currently not possible to constrain listening to a specific interface.

Afterwards you can test for a new incoming packet by is_packet_ready and receive it using receive_packet. The packet is then made available in last_packet. Sending is even easier: Prepare your packet (set its address and data) and pass it as argument to send. The socket doesn’t even need to be opened.

Note: The command receive_packet always creates a new instance of EM_UDP_PACKET.

As you might have noticed, it is necessary to poll a socket for ready packets. This can be unhandy for some types of applications. EM_UDP_SOCKET is the preferred alternative to the classic socket, which uses events instead of polling. The handling is similar to the EM_SIMPLE_UDP_SOCKET, but you have the possibility to send data directly without creating a packet first using send_direct.

The following events are available for subscription:

Note: Remember that UDP is unreliable. It is not guaranteed that packets receive their destination in order, not even that they arrive at all.

How do I...

HTTP - Hyper Text Transfer Protocol

Extended HTTP 1.0 support is available trough the class EM_HTTP_PROTOCOL. Extended means, that connections to virtual hosts are possible. The protocol supports HTTP GET and POST requests through the features get and post. The interface is very simliar to EM_TCP_CLIENT_SOCKET, except of the following differences:

How do I...

Examples

There are several examples provided: