# The Network Kit: BNetProtocol

Derived from: none

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

Library: libnetdev.so

## Overview

The BNetProtocol class is an abstract class that defines the basic interface between the Net Server and your protocol.

When the Net Server loads your protocol add-on, its `open_protocol()` global function will be called. This function should return a pointer to an object of a class derived from BNetProtocol. For example, if the class QuickProtocol is derived from BNetProtocol, our `open_protocol()` function might look like this:

       extern "C" BNetProtocol *open_protocol(const char *devname) {
          ...
          return new QuickProtocol();
       }

The `open_protocol()` function might also spawn a new thread or perform other activities, but the key issue is that it must return a pointer to a BNetProtocol-derived object to let the Net Server know how to communicate with it.

Once the Net Server knows how to get in touch with your protocol add-on, it will call the protocol's `AddDevice()` function once for each network interface. You can implement this function to examine the each device and determine whether or not your protocol should receive packets from that device. If you want to get packets from the device, call `register_packet_handler()` to register a packet handler for that device:

       void QuickProtocol::AddDevice(BNetDevice *device,
                            const char *name) {
          if (device->Type() == B_ETHER_NET_DEVICE) {
             register_packet_handler(myHandler, device);
          }
       }

myHandler is a pointer to an object of a class derived from BPacketHandler. This object's `PacketReceived()` function will be called for each packet received by your protocol. See the BPacketHandler section for further details.

If your protocol requires that timeouts be managed and served, your BNetProtocol-derived class can also inherit from the BTimeoutHandler class, which provides these services in a convenient and easy-to-use form.

## Destructor

### ~BNetProtocol()

          virtual ~BNetProtocol()

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

## Member Functions

### AddDevice()

          virtual void AddDevice(BNetDevice *device, const char *name) = 0

Your derived class must implement this function. It's called by the Net Server once for each network device, so that you can determine whether or not your protocol wishes to receive packets from the device.

If you wish to receive packets from this device, call `register_packet_handler()` to register with the Network Server as a party with an interest in the device:

       if (device->Type() == B_ETHER_NET_DEVICE) {
          register_packet_handler(myHandler, device);
       }

In this example, our protocol only wants to receive packets from ethernet devices, so it checks the device to see if it's of type `B_ETHER_NET_DEVICE` before registering to receive packets.

## Global C Functions

### register_packet_handler()

          void register_packet_handler(BPacketHandler *handler, BNetDevice *device, int priority = 0);

Registers the specified packet handler with the Network Server. A BNetProtocol-derived object's `AddDevice()` function should call this function to register itself to receive packets from the specified device. The priority specifies the order in which the handlers will receive packets; the higher the value, the higher-priority the handler. Most devices should use 0, the default. Packet sniffers and other debugging aids should use higher priorities so they don't risk missing packets that other packet handlers might accept.

See also: BNetProtocol::`AddDevice()`

### unregister_packet_handler()

          void unregister_packet_handler(BPacketHandler *handler, BNetDevice *device);

Tells the Network Server to stop sending packets from the specified device to your packet handler.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.