HandlerCall Class Reference

Convenience class for calling handlers. More...

#include <handlercall.hh>

Immediate Handler Calls
enum	Flags {   readable = Handler::f_read , f_read = Handler::f_read , writable = Handler::f_write , f_write = Handler::f_write ,   f_preinitialize = 4 , f_unquote_param = 8 }
typedef bool(HandlerCall::*	unspecified_bool_type) () const
static String	call_read (Element *e, const String &hname, ErrorHandler *errh=0)
	Call a read handler specified by element and handler name.
static String	call_read (const String &hdesc, const Element *context, ErrorHandler *errh=0)
	Call a read handler.
static int	call_write (Element *e, const String &hname, ErrorHandler *errh=0)
	Call a write handler specified by element and handler name.
static int	call_write (Element *e, const String &hname, const String &value, ErrorHandler *errh=0)
	Call a write handler specified by element and handler name.
static int	call_write (const String &hdesc, const Element *context, ErrorHandler *errh=0)
	Call a write handler.
static int	call_write (const String &hdesc, const String &value, const Element *context, ErrorHandler *errh=0)
	Call a write handler with a specified value.
static int	reset (HandlerCall *&hcall, const String &hdesc, int flags, const Element *context, ErrorHandler *errh=0)
	Create and initialize a HandlerCall from hdesc.
static int	reset (HandlerCall *&hcall, Element *e, const String &hname, const String &value, int flags, ErrorHandler *errh=0)
	Create and initialize a HandlerCall on element e.
static int	reset_read (HandlerCall *&hcall, const String &hdesc, const Element *context, ErrorHandler *errh=0)
	Create and initialize a read HandlerCall from hdesc.
static int	reset_read (HandlerCall *&hcall, Element *e, const String &hname, ErrorHandler *errh=0)
	Create and initialize a read HandlerCall from hdesc.
static int	reset_write (HandlerCall *&hcall, const String &hdesc, const Element *context, ErrorHandler *errh=0)
	Create and initialize a write HandlerCall from hdesc.
static int	reset_write (HandlerCall *&hcall, Element *e, const String &hname, const String &value=String(), ErrorHandler *errh=0)
	Create and initialize a read HandlerCall from hdesc.
	HandlerCall ()
	Construct an empty HandlerCall.
	HandlerCall (const String &hdesc)
	Construct a HandlerCall described by hdesc.
int	initialize (int flags, const Element *context, ErrorHandler *errh=0)
	Initialize the HandlerCall.
int	initialize_read (const Element *context, ErrorHandler *errh=0)
	Initialize the HandlerCall for reading.
int	initialize_write (const Element *context, ErrorHandler *errh=0)
	Initialize the HandlerCall for writing.
	operator unspecified_bool_type () const
	Test if HandlerCall is empty.
bool	empty () const
	Test if HandlerCall is empty.
bool	initialized () const
	Test if HandlerCall is initialized.
String	call_read (ErrorHandler *errh=0) const
	Call a read handler.
int	call_write (ErrorHandler *errh=0) const
	Call a write handler.
int	call_write (const VariableExpander &scope, ErrorHandler *errh=0) const
	Call a write handler, expanding its argument.
int	call_write (const String &value_ext, ErrorHandler *errh=0) const
	Call a write handler with an additional value.
Element *	element () const
	Return the Element corresponding to this HandlerCall.
const Handler *	handler () const
	Return the Handler corresponding to this HandlerCall.
const String &	value () const
	Return the write handler value and/or read handler parameters.
void	set_value (const String &value)
	Sets the write handler value and/or read handler parameters.
String	unparse () const
	Return a String that will parse into an equivalent HandlerCall.
void	clear ()
	Make this HandlerCall empty.

Detailed Description

Convenience class for calling handlers.

The HandlerCall class simplifies the process of calling Click handlers. (The lower-level interface is the Handler class.) HandlerCall is used in two ways: (1) to call handlers immediately via static member functions, and (2) to set up future handler calls via HandlerCall objects. The immediate handler call functions take handler names as arguments and perform all necessary error checks before calling handlers, if any. A HandlerCall object encapsulates a handler reference (possibly including parameters), again automating all necessary error checks.

Immediate Handler Calls

This example code shows how to use the HandlerCall functions for calling handlers immediately.

class YourElement { ...
    Element *_other;
}
 
void YourElement::function() {
    // Call _other's "config" read handler.
    String result = HandlerCall::call_read(_other, "config");
 
    // The same, providing an error handler to print errors.
    ErrorHandler *errh = ErrorHandler::default_handler();
    result = HandlerCall::call_read(_other, "config", errh);
    // (Each function takes an optional last argument of "errh".)
 
    // Call the "foo.config" read handler.  Search for element "foo" in
    // the current compound element context.
    result = HandlerCall::call_read("foo.config", this);
 
    // Call the global "config" read handler for the current router.
    result = HandlerCall::call_read("config", this);
 
    // Call _other's "stop" write handler with empty value.
    int success = HandlerCall::call_write(_other, "stop");
 
    // Call _other's "config" write handler with value "blah".
    success = HandlerCall::call_write(_other, "config", "blah");
 
    // Call the "foo.config" write handler with value "blah".
    success = HandlerCall::call_write("foo.config blah", this);
    // Or, alternately:
    success = HandlerCall::call_write("foo.config", "blah", this);
}

HandlerCall Objects

This example code shows how to use the HandlerCall objects to call handlers with simplified error checking.

class YourElement { ...
    HandlerCall _read_call;
    HandlerCall _write_call;
}
 
YourElement::YourElement()
    : _read_call(), _write_call() {
}
 
int YourElement::configure(Vector<String> &conf, ErrorHandler *errh) {
    return cp_va_kparse(conf, this, errh,
                   "READ_CALL", cpkP, cpHandlerCallRead, &_read_call,
                   "WRITE_CALL", cpkP, cpHandlerCallWrite, &_write_call,
                   cpEnd);
}
 
int YourElement::initialize(ErrorHandler *errh) {
    if ((_read_call && _read_call.initialize_read(this, errh) < 0)
        || (_write_call && _write_call.initialize_write(this, errh) < 0))
        return -1;
    return 0;
}
 
void YourElement::function() {
    // call _read_call, print result
    if (_read_call)
        click_chatter("%s", _read_call.call_read());
 
    // call _write_call with error handler
    if (_write_call)
        _write_call.call_write(ErrorHandler::default_handler());
}

If usually your element's handler calls aren't used, you can save a small amount of space by using pointers to HandlerCall objects, as in this example. The cpHandlerCallPtrRead and cpHandlerCallPtrWrite types allow the _read_call and _write_call members to start out as null pointers.

class YourElement { ...
    HandlerCall *_read_call;
    HandlerCall *_write_call;
}
 
YourElement::YourElement()
    : _read_call(0), _write_call(0) {
}
 
int YourElement::configure(Vector<String> &conf, ErrorHandler *errh) {
    return cp_va_kparse(conf, this, errh,
                   "READ_CALL", cpkP, cpHandlerCallPtrRead, &_read_call,
                   "WRITE_CALL", cpkP, cpHandlerCallPtrWrite, &_write_call,
                   cpEnd);
}
 
int YourElement::initialize(ErrorHandler *errh) {
    if ((_read_call && _read_call->initialize_read(this, errh) < 0)
        || (_write_call && _write_call->initialize_write(this, errh) < 0))
        return -1;
    return 0;
}
 
void YourElement::cleanup(CleanupStage) {
    delete _read_call;
    delete _write_call;
}
 
void YourElement::function() {
    // call _read_call, print result
    if (_read_call)
        click_chatter("%s", _read_call->call_read());
 
    // call _write_call with error handler
    if (_write_call)
        _write_call->call_write(ErrorHandler::default_handler());
}

Constructor & Destructor Documentation

HandlerCall() [1/2]

HandlerCall::HandlerCall ( )

inline

Construct an empty HandlerCall.

Any attempt to read, write, or initialize the HandlerCall will fail.

HandlerCall() [2/2]

HandlerCall::HandlerCall ( const String &  hdesc )

inline

Construct a HandlerCall described by hdesc.

Parameters

hdesc

handler description "[ename.]hname[ value]"

Although the resulting HandlerCall isn't empty, it must be initialized before it can be used. It returns false for initialized(). The handler description is not checked for syntax errors, though; initialize() does that.

Member Function Documentation

call_read() [1/3]

String HandlerCall::call_read ( Element *  e, const String &  hname, ErrorHandler *  errh = 0  )

static

Call a read handler specified by element and handler name.

Parameters

e	relevant element, if any
hname	handler name
errh	optional error handler

Returns

handler result, or empty string on error

Searches for a read handler named hname on element e. If the handler exists, calls it (with no parameters) and returns the result. If errh is nonnull, then errors, such as a missing handler or a write-only handler, are reported there. If e is some router's root element, calls the global handler named hname on that router.

call_read() [2/3]

String HandlerCall::call_read ( const String &  hdesc, const Element *  context, ErrorHandler *  errh = 0  )

static

Call a read handler.

Parameters

hdesc	handler description "[ename.]hname[ params]"
context	optional element context
errh	optional error handler

Returns

handler result, or empty string on error

Searches for a read handler matching hdesc. Any element name in hdesc is looked up relative to context. (For example, if hdesc is "x.config" and context's name is "aaa/bbb/ccc", will search for elements named aaa/bbb/x, aaa/x, and finally x.) If the handler exists, calls it (with specified parameters, if any) and returns the result. If errh is nonnull, then errors, such as a missing handler or a write-only handler, are reported there. If hdesc has no ename, then calls the global handler named hname on context's router.

call_write() [1/7]

int HandlerCall::call_write ( Element *  e, const String &  hname, ErrorHandler *  errh = 0  )

inlinestatic

Call a write handler specified by element and handler name.

Parameters

e	relevant element, if any
hname	handler name
errh	optional error handler

Returns

handler result, or -EINVAL on error

Searches for a write handler named hname on element e. If the handler exists, calls it (with empty write value) and returns the result. If errh is nonnull, then errors, such as a missing handler or a read-only handler, are reported there. If e is some router's root element, calls the global write handler named hname on that router.

call_write() [2/7]

int HandlerCall::call_write ( Element *  e, const String &  hname, const String &  value, ErrorHandler *  errh = 0  )

static

Call a write handler specified by element and handler name.

Parameters

e	relevant element, if any
hname	handler name
value	write value
errh	optional error handler

Returns

handler result, or -EINVAL on error

Searches for a write handler named hname on element e. If the handler exists, calls it with value and returns the result. If errh is nonnull, then errors, such as a missing handler or a read-only handler, are reported there. If e is some router's root element, calls the global write handler named hname on that router.

call_write() [3/7]

int HandlerCall::call_write ( const String &  hdesc, const Element *  context, ErrorHandler *  errh = 0  )

static

Call a write handler.

Parameters

hdesc	handler description "[ename.]hname[ value]"
context	optional element context
errh	optional error handler

Returns

handler result, or -EINVAL on error

Searches for a write handler matching hdesc. Any element name in hdesc is looked up relative to context (see above). If the handler exists, calls it with the value specified by hdesc and returns the result. If errh is nonnull, then errors, such as a missing handler or a read-only handler, are reported there. If e is some router's root element, calls the global write handler named hname on that router.

call_write() [4/7]

int HandlerCall::call_write ( const String &  hdesc, const String &  value, const Element *  context, ErrorHandler *  errh = 0  )

static

Call a write handler with a specified value.

Parameters

hdesc	handler description "[ename.]hname[ value]"
value	handler value
context	optional element context
errh	optional error handler

Returns

handler result, or -EINVAL on error

Searches for a write handler matching hdesc. Any element name in hdesc is looked up relative to context (see above). If the handler exists, calls it with value and returns the result. (Any value specified by hdesc is ignored.) If errh is nonnull, then errors, such as a missing handler or a read-only handler, are reported there. If e is some router's root element, calls the global write handler named hname on that router.

initialize()

int HandlerCall::initialize	(	int	flags,
		const Element *	context,
		ErrorHandler *	errh = 0
	)

Initialize the HandlerCall.

Parameters

flags	zero or more of f_read, f_write, f_preinitialize, f_unquote_param
context	optional element context
errh	optional error handler

Returns

0 on success, negative on failure

Initializes the HandlerCall object. The handler description supplied to the constructor is parsed and checked for syntax errors. Any element reference is looked up relative to context, if any. (For example, if hdesc was "x.config" and context's name is "aaa/bbb/ccc", this will search for elements named aaa/bbb/x, aaa/x, and finally x. If context is null, then the description must refer to a global handler.) If f_read is set in flags, then there must be a read handler named appropriately; if f_write is set, then there must be a write handler. If f_unquote_param is set, then any parameters are unquoted.

Initialization fails if the handler description was bogus (for example, an empty string, or something like "*#!$&!(#&$."), if the named handler does not exist, if a read handler description has parameters but the read handler doesn't actually take parameters, and so forth. If errh is nonnull, errors are reported there. The HandlerCall becomes empty on failure: empty() will return true, and (bool) *this will return false. Future call_read() and call_write() attempts will correctly fail.

If the f_preinitialize flag is set, the initialize function will check whether the router's handlers are ready (Router::handlers_ready()). If handlers are not ready, then initialize() will check for syntax errors, but not actually look up the handler (since we don't know yet whether or not the handler exists). Absent a syntax error, initialize() will return 0 for success even though the HandlerCall remains uninitialized.

initialize_read()

int HandlerCall::initialize_read ( const Element *  context, ErrorHandler *  errh = 0  )

inline

Initialize the HandlerCall for reading.

Parameters

context	optional element context
errh	optional error handler

Equivalent to initialize(f_read, context, errh).

initialize_write()

int HandlerCall::initialize_write ( const Element *  context, ErrorHandler *  errh = 0  )

inline

Initialize the HandlerCall for writing.

Parameters

context	optional element context
errh	optional error handler

Equivalent to initialize(f_write, context, errh).

operator unspecified_bool_type()

HandlerCall::operator unspecified_bool_type ( ) const

inline

Test if HandlerCall is empty.

Returns

True if HandlerCall is not empty, false otherwise.

Valid HandlerCall objects have been successfully initialized.

empty()

bool HandlerCall::empty ( ) const

inline

Test if HandlerCall is empty.

Returns

True if HandlerCall is empty, false otherwise.

initialized()

bool HandlerCall::initialized ( ) const

inline

Test if HandlerCall is initialized.

Returns

True if HandlerCall is initialized, false otherwise.

call_read() [3/3]

String HandlerCall::call_read ( ErrorHandler *  errh = 0 ) const

inline

Call a read handler.

Parameters

errh	optional error handler

Returns

Read handler result.

Fails and returns the empty string if this HandlerCall is invalid or not a read handler. If errh is nonnull, then any errors are reported there, whether from HandlerCall or the handler itself.

call_write() [5/7]

int HandlerCall::call_write ( ErrorHandler *  errh = 0 ) const

inline

Call a write handler.

Parameters

errh	optional error handler

Returns

Write handler result.

Fails and returns -EINVAL if this HandlerCall is invalid or not a write handler. If errh is nonnull, then any errors are reported there, whether from HandlerCall or the handler itself.

call_write() [6/7]

int HandlerCall::call_write ( const VariableExpander &  scope, ErrorHandler *  errh = 0  ) const

inline

Call a write handler, expanding its argument.

Parameters

scope	variable scope
errh	optional error handler

Returns

Write handler result.

The write value is expanded in scope before the handler is called. Fails and returns -EINVAL if this HandlerCall is invalid or not a write handler. If errh is nonnull, then any errors are reported there, whether from HandlerCall or the handler itself.

call_write() [7/7]

int HandlerCall::call_write ( const String &  value_ext, ErrorHandler *  errh = 0  ) const

inline

Call a write handler with an additional value.

Parameters

value_ext	write value extension
errh	optional error handler

Returns

Write handler result.

The value_ext is appended to the write value before the handler is called. (For example, consider a handler with description "a.set value". call_write("foo") will call "a.set value foo".) Fails and returns -EINVAL if this HandlerCall is invalid or not a write handler. If errh is nonnull, then any errors are reported there, whether from HandlerCall or the handler itself.

reset() [1/2]

int HandlerCall::reset ( HandlerCall *&  hcall, const String &  hdesc, int  flags, const Element *  context, ErrorHandler *  errh = 0  )

static

Create and initialize a HandlerCall from hdesc.

Parameters

hcall	stores the HandlerCall result
hdesc	handler description "[ename.]hname[ value]"
flags	initialization flags (f_read, f_write, f_preinitialize)
context	optional element context
errh	optional error handler

Returns

0 on success, -EINVAL on failure

Creates a HandlerCall and initializes it. Behaves somewhat like:

hcall = new HandlerCall(hdesc);
return hcall->initialize(flags, context, errh);

However, (1) if initialization fails, then hcall is untouched; and (2) if initialization succeeds and hcall is not null, then the existing HandlerCall is assigned so that it corresponds to the new one (no new memory allocations).

If errh is nonnull, then any errors are reported there.

reset() [2/2]

int HandlerCall::reset ( HandlerCall *&  hcall, Element *  e, const String &  hname, const String &  value, int  flags, ErrorHandler *  errh = 0  )

static

Create and initialize a HandlerCall on element e.

Parameters

hcall	stores the HandlerCall result
e	relevant element, if any
hname	handler name
value	handler value
flags	initialization flags (f_read, f_write, f_preinitialize)
errh	optional error handler

Returns

0 on success, -EINVAL on failure

Creates a HandlerCall and initializes it. Behaves analogously to reset(HandlerCall*&, const String&, int, const Element*, ErrorHandler*).

reset_read() [1/2]

int HandlerCall::reset_read ( HandlerCall *&  hcall, const String &  hdesc, const Element *  context, ErrorHandler *  errh = 0  )

inlinestatic

Create and initialize a read HandlerCall from hdesc.

Parameters

hcall	stores the HandlerCall result
hdesc	handler description "[ename.]hdesc[ param]"
context	optional element context
errh	optional error handler

Returns

0 on success, -EINVAL on failure

Equivalent to reset(hcall, hdesc, f_read, context, errh).

reset_read() [2/2]

int HandlerCall::reset_read ( HandlerCall *&  hcall, Element *  e, const String &  hname, ErrorHandler *  errh = 0  )

inlinestatic

Create and initialize a read HandlerCall from hdesc.

Parameters

hcall	stores the HandlerCall result
e	relevant element, if any
hname	handler name
errh	optional error handler

Returns

0 on success, -EINVAL on failure

Equivalent to reset(hcall, e, hname, String(), f_read, context, errh).

reset_write() [1/2]

int HandlerCall::reset_write ( HandlerCall *&  hcall, const String &  hdesc, const Element *  context, ErrorHandler *  errh = 0  )

inlinestatic

Create and initialize a write HandlerCall from hdesc.

Parameters

hcall	stores the HandlerCall result
hdesc	handler description "[ename.]hdesc[ value]"
context	optional element context
errh	optional error handler

Returns

0 on success, -EINVAL on failure

Equivalent to reset(hcall, hdesc, f_write, context, errh).

reset_write() [2/2]

int HandlerCall::reset_write ( HandlerCall *&  hcall, Element *  e, const String &  hname, const String &  value = String(), ErrorHandler *  errh = 0  )

inlinestatic

Create and initialize a read HandlerCall from hdesc.

Parameters

hcall	stores the HandlerCall result
e	relevant element, if any
hname	handler name
value	write handler value
errh	optional error handler

Returns

0 on success, -EINVAL on failure

Equivalent to reset(hcall, e, hname, @ value, f_write, context, errh).

element()

Element * HandlerCall::element ( ) const

inline

Return the Element corresponding to this HandlerCall.

Returns null if invalid. A global handler may return some Router::root_element() or null.

handler()

const Handler * HandlerCall::handler ( ) const

inline

Return the Handler corresponding to this HandlerCall.

Returns Handler::blank_handler() if invalid.

value()

const String & HandlerCall::value ( ) const

inline

Return the write handler value and/or read handler parameters.

Returns the empty string if invalid.

set_value()

void HandlerCall::set_value ( const String &  value )

inline

Sets the write handler value and/or read handler parameters.

Parameters

value

new value and/or parameters

Does nothing if invalid.

unparse()

String HandlerCall::unparse

(

)

const

Return a String that will parse into an equivalent HandlerCall.

Will work even if the HandlerCall has not been initialized.

clear()

void HandlerCall::clear ( )

inline

Make this HandlerCall empty.

Subsequent attempts to read, write, or initialize the HandlerCall will fail.

---

The documentation for this class was generated from the following files:

• include/click/handlercall.hh
• lib/handlercall.cc