Component balb_controlmanager [Package balb]

Provide a mechanism for mapping control messages to callbacks. More...

Namespaces
namespace	balb

---

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Callback Function Requirements
  • Thread Safety
  • 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.

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.

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");