balb_controlmanager

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