# 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:

- `IsIpDevice()` should return `true` if the device is an IP device; if it's not an IP device, it should return `false`. If you return `true`, the Network Server will call the BIpDevice's `OpenIP()` function and communicate through the BIpDevice object returned by that function.

- `Config()` is called by the Network preference application when the user clicks the Modify button to configure the interface. This can present a window or perform automatic configuration, depending on the needs of your add-on. This function is also called to automatically select default settings for the device when the device is first installed.

- `GetPrettyName()` should return the name of the device. This is the name that will be displayed in the Network preference application.

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:

- ifname The name of the network interface.
- ncw A pointer to a net_settings structure; this is basically a magic cookie used when calling `find_net_setting()` and `set_net_setting()` to manage your saved configuration variables.
- callback A pointer to a BCallbackHandler object. This object has a single function, `Done()`, which you should call when your user interface has been closed. If you don't present a user interface, you don't have to call callback->`Done()`. `Done()` accepts one parameter, a status_t. Specify `B_OK` if the configuration was concluded successfully, or `B_ERROR` otherwise.
- autoconf A boolean; this is `true` if the `Config()` function should automatically configure the device to its default settings. If `false`, the user interface should be presented with the current settings intact. This is only used for IP devices.

       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

- `B_OK`. No errors occurred.
- `B_ERROR`. Unable to open the user interface or autoconfigure the device.

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.