# The Network Kit: BIpDevice

Derived from: none

Declared in: be/addons/net_server/IpDevice.h

Library: libnetdev.so

## Overview

If the network server add-on you're writing communicates through IP packets, there is an extra step to go through while writing the add-on. Because the Network Server doesn't directly send and receive IP packets, you have to create a special layer that provides the interface between your network add-on's IP packets and the Network Server. The BIpDevice class defines the protocol for this special layer.

A network device of this kind requires the following three classes to define the interface with the BeOS:

- BNetConfig Lets the Network Server and others configure and obtain information about the device.
- BNetDevice Handles communication between the network and the Network Server.
- BIpDevice Represents the IP layer of the device. This object receives packets in the background and forwards them to the Network Server, and sends IP packets for the Network Server.

The Network Server determines that your add-on is for an IP device by calling the `IsIpDevice()` function of your add-on's BNetConfig-derived object.

Once the Network Server knows that the add-on represents an IP device, it will call the BNetDevice-derived object's `OpenIP()` function to obtain a pointer to an object derived from the BIpDevice class. Once this has been done, the Network Server will interact with your network add-on through the BIpDevice object and not the BNetDevice.

The IP protocol in the Network Server won't call into the BNetDevice if there's also a BIpDevice. However, other protocol add-ons might do so. For example, PPP exports a BIpDevice and a BNetDevice of type `B_PPP_NET_DEVICE`. Other protocol add-ons might use the BNetDevice for their own purposes.

If it doesn't make sense for your add-on's BNetDevice to be used by others (for example, if your add-on is a packet sniffer), you should set the BNetDevice's type to `B_NULL_NET_DEVICE`.

The Network Server will then call your BIpDevice's `Run()` function. `Run()` should spawn a thread to watch for incoming IP packets and forward them to the Network Server. This is done through the use of the BIpHandler object passed to the `Run()` function; the BIpHandler's `PacketReceived()` function should be called to do this.

If your IP device needs to manage timeouts, you should consider also inheriting from the BTimeoutHandler class.

## Destructor

### ~BNetDevice()

          virtual ~BNetDevice()

Your derived class can implement the BIpDevice destructor, if necessary, to perform cleanup before objects of your derived class are deleted.

## Member Functions

### AllocPacket()

          virtual BNetPacket *AllocPacket(void) = 0

Your derived class should implement `AllocPacket()` to return a pointer to a newly-instantiated BNetPacket-derived object. As discussed further in the section on BNetPacket, you should never instantiate BNetPacket directly; it's an abstract class that you should subclass.

Unless you have special needs, usually you can return a BStandardPacket:

       BNetPacket *AllocPacket(void) {
          return (new BStandardPacket());
       }

### Close()

          virtual void Close(void) = 0

Your derived class's implementation of `Close()` is called by the Network Server when your device is no longer in use. This function should close the device.

### Flags()

          virtual unsigned Flags(void) = 0

You should implement the `Flags()` function to return the current flag settings for the IP device.

Currently, the only defined flag is `B_FLAGS_POINT_TO_POINT`.

### MaxPacketSize()

          virtual unsigned MaxPacketSize(void) = 0

Implement this function to return the size, in bytes, of the maximum packet size setting currently in effect.

### Run()

          virtual void Run(BIpHandler *ipHandler) = 0

Your `Run()` function is called by the Network Server to tell your IP device add-on to begin receiving IP packets. Your `Run()` function should spawn a new thread that watches for incoming packets and forwards them on to the Network Server.

Because the Network Server doesn't handle IP traffic directly, you have to receive the packets in your add-on, then forward them to the Network Server by calling the ipHandler object's `PacketReceived()` function. ipHandler is, essentially, your interface to the Network Server:

       /* we've received a packet - let the Network Server have it */

       ipHandler->PacketReceived(thePacket, this);

Once we've done this, the packet belongs to the Network Server and we don't have to worry about it anymore.

### SendPacket()

          virtual void SendPacket(uint32 dest, BNetPacket *packet) = 0

Your derived class's implementation of `SendPacket()` is called to send the specified packet to the IP address specified by dest. Once the packet has been sent, you should delete it.

### Statistics()

          virtual void Statistics(FILE *stat_file) = 0

Your implementation of `Statistics()` should output device status information to the specified file. This will typically be called for debugging purposes, but can also be used to provide valuable status information to users.

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.