The Network Kit: BNetConfig

Derived from: none

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

Library: libnetdev.so


Overview

Users will from time-to-time install new networking interfaces, or reconfigure old ones. This is done using the Network preference application, which provides the basic user interface for configuring networking devices.

When your network add-on's open_config() static C function is called, it returns a pointer to an object of a class derived from BNetConfig. This is the interface by which the Network preference application gives users access to the configuration options available on your device.

An object derived from BNetConfig is also used to automatically select default preferences for your device when it is first installed, and to let the Net Server determine whether or not the add-on represents an IP device, which requires special handling.


User Configuration

The Network preference application lets the user install and customize network interfaces. A list of network interfaces is provided, and the user can click on one and hit the Modify button to configure that device more closely

In order to make this possible, your network device add-on has to implement the following static C function:

   BNetConfig *open_config(const char *device);

open_config() must return an object of a class derived from BNetConfig. Your derived class must implement the following three functions:

Let's look at a sample class, derived from BNetConfig:

   class QuickNetConfig : public BNetConfig {
      public:
         int GetPrettyName(char *pretty_name, int buf_len) {
            int totlen = strlen(DRIVER_NAME)+1;
            if (buf_len < totlen) {
               return (-totlen);
            }
            strcpy(pretty_name, DRIVER_NAME);
            return totlen;
         }
         bool IsIpDevice(void) { return false };
         status_t Config(const char *ifname, net_settings *ncw,
                     BCallBackHandler *callback, bool autoconf);
   }

The QuickNetConfig class is pretty simple. GetPrettyName() is passed a pointer to a buffer and the length of the buffer, and fills that buffer with the name of the device. If the buffer is too small, we return the negative of the length actually needed. This lets the Network preference application know how much space is necessary for the name.

The device isn't an IP device, so IsIpDevice() returns false.

The Config() function is called with several parameters:

   extern "C" BNetConfig *open_config(const char *device) {
      system_info info;
   
      get_system_info(&info);
      if (info.platform_type == B_MAC_PLATFORM) {
         return NULL;
      }
      return (new QuickNetConfig());
   }

This sample open_config() function checks to see if the add-on is running on a Macintosh; for whatever reason, the device doesn't need to be configured on a Mac, so it returns NULL to indicate that no configuration is necessary (or possible). Otherwise, a QuickNetConfig object is instantiated and returned.


Destructor


~BNetConfig()


      virtual ~BNetConfig()

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


Member Functions


Config()


      virtual status_t Config(const char *ifname, net_settings *ncw, BCallbackHandler *callback, bool autoconfig = false) = 0

Your derived class must implement the Config() function. This function is called by the Network preference application when the user selects your device and presses the Modify button (or double-clicks the device in the Network Interfaces list). In this case, the autoconfig parameter is false.

It is also called to automatically configure the device--for example, if the device has settings already saved in the network configuration, this function is calledwith autoconfig set to true. In response, your add-on should make the configuration specified by ncw the current configuration.

When autoconfig is false, you should present a user interface by creating a window containing controls for configuring the device. The callback parameter is a pointer to a BCallbackHandler; when your user interface is finished--when the user clicks an OK or Cancel button, for example--you should call BCallbackHandler's Done() function to let the caller know the configuration is complete.

Autoconfiguration is only supported for IP devices; if your device is not an IP device, and your Config() function is called with autoconfig true, you should return an error.

Also, if your device doesn't support autoconfiguration, or for any reason you can't autoconfigure the device, you should return an error.

The device parameter specifies the name of the device. You can use this string as the heading for find_net_setting() and set_net_setting() calls.

RETURN CODES

See also: find_net_setting(), set_net_setting()


GetPrettyName()


      virtual int GetPrettyName(char *name_buffer, int buffer_len) = 0

Your derived class will implement this function to return, in the buffer specified by name_buffer, the name of your device. This name is used in user interface displays, so it should be a user-friendly string. For instance, the standard BeOS NE-2000 Ethernet driver returns the string "Novell NE2000 compatible adapter (ISA)" in response to this call.

Before copying your device's name into the buffer, you should ensure that your string will fit in the buffer. Do this by comparing the name string's length to buffer_len. If the buffer is too small, you should return the negative of your string's length.

For example, if your string's length is 25 characters, but the buffer provided is only 12 bytes long, you should return -25.

If the string is successfully copied, return B_OK.


IsIpDevice()


      virtual bool IsIpDevice(void) = 0

Your derived class needs to implement the IsIpDevice() function to return true if the device is an IP device, and false if not. As discussed in the sections on BNetDevice and BIpDevice, IP devices are handled differently from other, non-IP devices.




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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.