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:

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.