Handler Class Reference

Represents a router's handlers. More...

Public Types
enum	Flags {   f_read = 0x0001 , f_write = 0x0002 , f_read_param = 0x0004 , f_exclusive = 0 ,   f_nonexclusive = 0x0020 , f_raw = 0x0040 , f_read_private = 0x0080 , f_write_private = 0x0100 ,   f_deprecated = 0x0200 , f_uncommon = 0x0400 , f_calm = 0x0800 , f_expensive = 0x1000 ,   f_button = 0x2000 , f_checkbox = 0x4000 , f_driver0 = 1U << 26 , f_driver1 = 1U << 27 ,   f_user_shift = 28 , f_user0 = 1U << f_user_shift , f_read_comprehensive = 0x0008 , f_write_comprehensive = 0x0010 ,   f_special = f_read | f_write | f_read_param | f_read_comprehensive | f_write_comprehensive }

Public Member Functions
const String &	name () const
	Return this handler's name.
uint32_t	flags () const
	Return this handler's flags.
void *	user_data (int op) const
	Return this handler's callback data.
void *	read_user_data () const
	Return this handler's read callback data.
void *	write_user_data () const
	Return this handler's write callback data.
bool	readable () const
	Test if this is a valid read handler.
bool	read_param () const
	Test if this is a valid read handler that may accept parameters.
bool	read_visible () const
	Test if this is a public read handler.
bool	writable () const
	Test if this is a valid write handler.
bool	write_visible () const
	Test if this is a public write handler.
bool	visible () const
	Test if this is a public read or write handler.
bool	allow_concurrent_handlers () const
	Test if this handler can execute concurrently with other handlers.
bool	allow_concurrent_threads () const
	Test if this handler can execute concurrently with router threads.
bool	raw () const
	Test if spaces should be preserved when calling this handler.
String	call_read (Element *e, const String &param, ErrorHandler *errh) const
	Call a read handler, possibly with parameters.
String	call_read (Element *e, ErrorHandler *errh=0) const
	Call a read handler without parameters.
int	call_write (const String &value, Element *e, ErrorHandler *errh) const
	Call a write handler.
String	unparse_name (Element *e) const
	Unparse this handler's name.

Static Public Member Functions
static String	unparse_name (Element *e, const String &hname)
	Unparse a handler name.
static const Handler *	blank_handler ()
	Returns a handler incapable of doing anything.

Detailed Description

Represents a router's handlers.

Each handler is represented by a Handler object. Handlers are not attached to specific elements, allowing a single handler object to be shared among multiple elements with the same basic handler definition. Handlers cannot be created directly; to create one, call methods such as Router::add_read_handler(), Router::add_write_handler(), Router::set_handler(), Element::add_read_handler(), Element::add_write_handler(), and Element::set_handler().

The HandlerCall class simplifies interaction with handlers and is preferred to direct Handler calls for most purposes.

Member Enumeration Documentation

Flags

enum Handler::Flags

Enumerator
f_read	Handler supports read operations.
f_write	Handler supports write operations.
f_read_param	Read handler takes parameters.
f_exclusive	Handler is exclusive (the default): router threads must stop while it is called.
f_nonexclusive	Handler is nonexclusive: router threads don't need to stop while it is called.
f_raw	Don't add newline to results.
f_read_private	Read handler private (invisible outside the router configuration).
f_write_private	Write handler private (invisible.
f_deprecated	outside the router configuration). Handler is deprecated and available only for compatibility.
f_uncommon	User interfaces should not display handler by default.
f_calm	Read handler value changes rarely.
f_expensive	Read handler is expensive to call.
f_button	Write handler ignores data.
f_checkbox	Read/write handler is boolean and should be rendered as a checkbox.
f_driver1	Uninterpreted handler flags available for drivers.
f_user0	First uninterpreted handler flag available for element-specific use. Equals 1 << f_user_shift.
f_special	These flags may not be set by Router::set_handler_flags().

Member Function Documentation

name()

const String & Handler::name ( ) const

inline

Return this handler's name.

flags()

uint32_t Handler::flags ( ) const

inline

Return this handler's flags.

The result is a bitwise-or of flags from the Flags enumeration type.

user_data()

void * Handler::user_data ( int  op ) const

inline

Return this handler's callback data.

Parameters

op	either f_read or f_write.

read_user_data()

void * Handler::read_user_data ( ) const

inline

Return this handler's read callback data.

write_user_data()

void * Handler::write_user_data ( ) const

inline

Return this handler's write callback data.

readable()

bool Handler::readable ( ) const

inline

Test if this is a valid read handler.

never

read_param()

bool Handler::read_param ( ) const

inline

Test if this is a valid read handler that may accept parameters.

read_visible()

bool Handler::read_visible ( ) const

inline

Test if this is a public read handler.

Private handlers may be not called from outside the router configuration. Handlers are public by default; to make a read handler private, add the f_read_private flag.

writable()

bool Handler::writable ( ) const

inline

Test if this is a valid write handler.

write_visible()

bool Handler::write_visible ( ) const

inline

Test if this is a public write handler.

Private handlers may not be called from outside the router configuration. Handlers are public by default; to make a write handler private, add the f_write_private flag.

visible()

bool Handler::visible ( ) const

inline

Test if this is a public read or write handler.

allow_concurrent_handlers()

bool Handler::allow_concurrent_handlers ( ) const

inline

Test if this handler can execute concurrently with other handlers.

allow_concurrent_threads()

bool Handler::allow_concurrent_threads ( ) const

inline

Test if this handler can execute concurrently with router threads.

raw()

bool Handler::raw ( ) const

inline

Test if spaces should be preserved when calling this handler.

Some Click drivers perform some convenience processing on handler values, for example by removing a terminating newline from write handler values or adding a terminating newline to read handler values. Raw handlers do not have their values manipulated in this way. Rawness is set by the f_raw flag.

• The linuxmodule driver adds a terminating newline to non-raw read handler values, but does not modify raw read handlers' values in any way.
• The same applies to handler values returned by the userlevel driver's -h option.
• The linuxmodule driver removes an optional terminating newline from a one-line non-raw write handler value, but does not modify raw write handlers' values in any way.

call_read() [1/2]

String Handler::call_read	(	Element *	e,
		const String &	param,
		ErrorHandler *	errh
	)		const

Call a read handler, possibly with parameters.

Parameters

e	element on which to call the handler
param	parameters, or an empty string if no parameters
errh	optional error handler

The element must be nonnull; to call a global handler, pass the relevant router's Router::root_element(). errh may be null, in which case errors are reported to ErrorHandler::silent_handler().

call_read() [2/2]

String Handler::call_read ( Element *  e, ErrorHandler *  errh = 0  ) const

inline

Call a read handler without parameters.

Parameters

e	element on which to call the handler
errh	error handler

The element must be nonnull; to call a global handler, pass the relevant router's Router::root_element(). errh may be null, in which case errors are ignored.

call_write()

int Handler::call_write	(	const String &	value,
		Element *	e,
		ErrorHandler *	errh
	)		const

Call a write handler.

Parameters

value	value to write to the handler
e	element on which to call the handler
errh	optional error handler

The element must be nonnull; to call a global handler, pass the relevant router's Router::root_element(). errh may be null, in which case errors are reported to ErrorHandler::silent_handler().

unparse_name() [1/2]

String Handler::unparse_name

(

Element *

e

)

const

Unparse this handler's name.

Parameters

e	relevant element

If e is an actual element, then returns "ENAME.HNAME", where ENAME is e's name and HNAME is this handler's name(). Otherwise, just returns name().

unparse_name() [2/2]

String Handler::unparse_name ( Element *  e, const String &  hname  )

static

Unparse a handler name.

Parameters

e	relevant element, if any
hname	handler name

If e is an actual element on some router, then returns "ENAME.hname", where ENAME is e's name. Otherwise, just returns hname.

blank_handler()

static const Handler * Handler::blank_handler ( )

inlinestatic

Returns a handler incapable of doing anything.

The returned handler returns false for readable() and writable() and has flags() of zero.

---

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

• include/click/handler.hh
• include/click/router.hh
• lib/router.cc