balb_controlmanager

Detailed Description

Provide a mechanism for mapping control messages to callbacks.

Outline

• Purpose
• Classes
• Description
  • Callback Function Requirements
  • Thread Safety
  • Default Handler
  • Usage
    • Example 1: Creating an ECHO Message Handler

Purpose

Provide a mechanism for mapping control messages to callbacks.

Classes

• balb::ControlManager: mechanism that maps control messages

Description

The balb::ControlManager mechanism provided by this component maps control messages to callback functions on the basis of message prefixes.

The prefix (case-insensitive) "HELP" is reserved for use by the registerUsageHandler.

Callback Function Requirements

Functions registered as callbacks for messages must be invokable as void(*)(const bsl::string&, bsl::istream&). (This signature is balb::ControlManager::ControlHandler). When the function is invoked, the first argument is the message prefix, and the second is a stream on the remainder of the message.

Thread Safety

This component is thread-safe and thread-enabled: it is safe to access and manipulate multiple distinct instances from different threads, and it is safe to access and manipulate a single shared instance from different threads.

Default Handler

The balb::ControlManager ignores messages having (case-insensitive) prefixes that have not been previously registered. Optionally, users can install a (default) handler for messages messages with un-registered prefixes. Note that "default" refers to the message prefix – there is no such handler unless the user explicitly installs one using the setDefaultHandler method.

Usage

This section illustrates intended use of this component.

Example 1: Creating an ECHO Message Handler

First define a trivial callback to be invoked when an "ECHO" message is received:

void onEcho(const bsl::string& prefix, bsl::istream& stream)
{
   bsl::string word;
   bsl::cout << "onEcho: \"" << prefix;
   while (stream.good()) {
      stream >> word;
      bsl::cout << ' ' << word;
   }
   bsl::cout << '\"' << bsl::endl;
}

Now create a balb::ControlManager object and register a handler for "ECHO". Also register a handler for HELP to observe the auto-generated documentation for ECHO:

balb::ControlManager manager;
manager.registerHandler("ECHO", "<text>",
                        "Print specified text to the standard output",
                        &onEcho);
manager.registerHandler("HELP", "",
                        "Print documentation",
                        bdlf::BindUtil::bind(
                                &balb::ControlManager::printUsageHelper,
                                &manager, &bsl::cout, bsl::string(
             "The following commands are accepted by the test driver:")));
 
manager.dispatchMessage("ECHO repeat this text");
manager.dispatchMessage("echo matching is case-insensitive");
manager.dispatchMessage("HELP");