Creates a new BInputServerDevice object. You can initialize your object—set initial values, spawn (but not necessarily resume; do that in Start()) threads, open drivers, etc.—either here or in the InitCheck() function, which is called immediately after the constructor.

Deletes the BInputServerDevice object. The destructor is invoked by the Input Server only—you never delete a BInputServerDevice object from your own code. When the destructor is called, the object's devices will already be unregistered and Stop() will already have been called. If this object spawned its own threads or allocated memory on the heap, it must clean up after itself here.

The Control() hook function is invoked by the Input Server to send an input device control message or a Node Monitor message to this object. name and cookie are the readable name and pointer-to-whatever-you-want that you used when registering the device (with the RegisterDevices() function).

Warning

The function's return value is ignored.

Invoked by the Input Server immediately after the object is constructed to test the validity of the initialization. If the object is properly initialized (i.e. all required resources are located or allocated), this function should return B_OK. Start() will be invoked soon if you need to do any extra initialization. If the object returns non-B_OK, the object is deleted and the add-on is unloaded.

The default implementation returns B_OK.

Start() is invoked by the Input Server to tell the object that it can begin sending events for the registered device identified by the arguments. The values of the arguments are taken from the input_device_ref structure you used to register the device (see RegisterDevices()). If your object needs to resume a thread (spawned in the constructor, in InitCheck(), or here), this is the place to do it.

Stop() is invoked to tell the object to stop sending events for the registered device. The device is not unregistered—you can still receive Control() messages for the device while it's stopped. You should pause or kill any threads associated with the device (that were spawned by this object) from here.

The return value (for both of these functions) is ignored.

Tells the object that the Input Server is in the process of shutting down. Unless something interrupts the shutdown, this notification will be followed by a Stop() and delete, thus you don't have to do much from this function (other than note that the end is near).

Warning

The return value is ignored.

Sends an event message to the Input Server, which passes it through the input methods and input filters before sending it to the App Server. The message you create should be appropriate for the action you're trying to depict. For example, if the user presses a key, you should create and send a B_KEY_DOWN message. A list of the system-defined event messages that an input device is expected to create and send is given in "Input Device Event Messages".

RegisterDevices() tells the Input Server that this object is responsible for the listed devices. This means that when a control message is sent back upstream, the message—which is tagged as being relevant for a specific device, or type of device—will be forwarded (through the Control() hook) to the responsible BInputServerDevice object(s). Typically, you initially register your devices as part of the constructor or InitCheck(). Registration is cumulative—each RegisterDevices() call adds to the object's current list of devices.

UnregisterDevices() tells the Input Server that this object is no longer responsible for the listed devices. The devices are automatically unregistered when your object is deleted.

RegisterDevices() invokes Start() for each device in the devices list; UnregisterDevices() invokes Stop().

For both functions, the devices list must be NULL-terminated, and the caller retains ownership of the list and its contents.

Note that the BeOS currently only targets the device types when sending a Control() message. For example, let's say you've registered two pointing devices and a keyboard:

status_t MyISDevice::InitCheck()
{
...
   input_device_ref **devices =
      (input_device_ref **)malloc(sizeof(*input_device_ref * 4));
   input_device_ref mouse1 = {"Mouse 1", B_POINTING_DEVICE,
                              (void *)this)};
   input_device_ref mouse2 = {"Mouse 2", B_POINTING_DEVICE,
                              (void *)this)};
   input_device_ref keyboard = {"Keyboard", B_KEYBOARD_DEVICE,
                              (void *)this)};
   devices[0] = &mouse1;
   devices[1] = &mouse2;
   devices[2] = &keyboard;
   devices[3] = NULL;
   RegisterDevices(devices);
   ...
}

When the user fiddles with the Mouse preference (more specifically, if an application calls set_mouse_speed() et. al.), this object will receive two Control() messages: one targets "Mouse 1", and the other targets "Mouse 2". That's because the mouse and keyboard functions (as defined by the BeOS and as used by the system preferences) know which type of device to control, but they don't provide a means for more granular identification. If you need a UI that identifies specific devices, you have to create the UI yourself, and use a BInputDevice object to tune the control messages that are sent back upstream.

Warning

The functions don't let you un/register the same device definition twice, and RegisterDevices() won't register a device that doesn't have a name (although the name can be ""). However, the functions don't complain about violations of these conditions as long as at least one definition is properly formed.

These are convenient covers for the Node Monitor's watch_node() and stop_watching() functions. You use them to watch for physical devices that are attached and detached, as indicated by changes to subdirectories of the system device directory (/dev).

deviceDir is the name of the device subdirectory that you want to watch. The /dev/ root is automatically prepended; for example, if you want to watch for new ps2 mice, you would pass input/mouse/ps2 as the deviceDir name. The Node Monitor is told to look for changes to the directory (B_WATCH_DIRECTORY opcode). When an entry is added or removed, this object receives a B_NODE_MONITOR message delivered to its Control() function.