handlercall.hh

Click is a modular router toolkit. To use it you ll need to know how to compile and install the sof

     *  @return  Write handler result.
     *
     *  Fails and returns -EINVAL if this HandlerCall is invalid or not a
     *  write handler.  If @a errh is nonnull, then any errors are reported
     *  there, whether from HandlerCall or the handler itself. */
    inline int call_write(ErrorHandler *errh = 0) const;

    /** @brief  Call a write handler, expanding its argument.
     *  @param  scope  variable scope
     *  @param  errh  optional error handler
     *  @return  Write handler result.
     *
     *  The write value is expanded in @a scope before the handler is called.
     *  Fails and returns -EINVAL if this HandlerCall is invalid or not a
     *  write handler.  If @a errh is nonnull, then any errors are reported
     *  there, whether from HandlerCall or the handler itself. */
    inline int call_write(const VariableExpander &scope, ErrorHandler *errh = 0) const;

    /** @brief  Call a write handler with an additional value.
     *  @param  value_ext  write value extension
     *  @param  errh       optional error handler
     *  @return  Write handler result.
     *
     *  The @a 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 @a errh is nonnull, then any errors are reported there, whether
     *  from HandlerCall or the handler itself. */
    inline int call_write(const String &value_ext, ErrorHandler *errh = 0) const;


    /** @brief  Create and initialize a HandlerCall from @a hdesc.
     *  @param  hcall    stores the HandlerCall result
     *  @param  hdesc    handler description "[ename.]hname[ value]"
     *  @param  flags    initialization flags (OP_READ, OP_WRITE, PREINITIALIZE)
     *  @param  context  optional element context
     *  @param  errh     optional error handler
     *  @return  0 on success, -EINVAL on failure
     *
     *  Creates a HandlerCall and initializes it.  Behaves somewhat like:
     *
     *  @code
     *  hcall = new HandlerCall(hdesc);
     *  return hcall->initialize(flags, context, errh);
     *  @endcode
     *
     *  However, (1) if initialization fails, then @a hcall is untouched; and
     *  (2) if initialization succeeds and @a hcall is not null, then the
     *  existing HandlerCall is assigned so that it corresponds to the new one
     *  (no new memory allocations).
     *
     *  If @a errh is nonnull, then any errors are reported there. */
    static int reset(HandlerCall *&hcall, const String &hdesc, int flags,
		     const Element *context, ErrorHandler *errh = 0);

    /** @brief  Create and initialize a HandlerCall on element @a e.
     *  @param  hcall  stores the HandlerCall result
     *  @param  e      relevant element, if any
     *  @param  hname  handler name
     *  @param  value  handler value
     *  @param  flags  initialization flags (OP_READ, OP_WRITE, PREINITIALIZE)
     *  @param  errh   optional error handler
     *  @return  0 on success, -EINVAL on failure
     *
     *  Creates a HandlerCall and initializes it.  Behaves analogously to
     *  reset(HandlerCall*&, const String&, int, Element*, ErrorHandler*). */
    static int reset(HandlerCall *&hcall,
		     Element *e, const String &hname, const String &value,
		     int flags, ErrorHandler *errh = 0);


    /** @brief  Create and initialize a read HandlerCall from @a hdesc.
     *  @param  hcall    stores the HandlerCall result
     *  @param  hdesc    handler description "[ename.]hdesc[ param]"
     *  @param  context  optional element context
     *  @param  errh     optional error handler
     *  @return  0 on success, -EINVAL on failure
     *
     *  Equivalent to
     *  @link reset(HandlerCall*&, const String&, int, Element*, ErrorHandler*) reset@endlink(@a hcall, @a hdesc, OP_READ, @a context, @a errh). */
    static inline int reset_read(HandlerCall *&hcall, const String &hdesc,
				 const Element *context, ErrorHandler *errh = 0);

    /** @brief  Create and initialize a read HandlerCall from @a hdesc.
     *  @param  hcall  stores the HandlerCall result
     *  @param  e      relevant element, if any
     *  @param  hname  handler name
     *  @param  errh   optional error handler
     *  @return  0 on success, -EINVAL on failure
     *
     *  Equivalent to
     *  @link reset(HandlerCall*&, Element*, const String&, const String&, int, ErrorHandler*) reset@endlink(@a hcall, @a e, @a hname, String(), OP_READ, @a context, @a errh). */
    static inline int reset_read(HandlerCall *&hcall,
				 Element *e, const String &hname,
				 ErrorHandler *errh = 0);

    /** @brief  Create and initialize a write HandlerCall from @a hdesc.
     *  @param  hcall    stores the HandlerCall result
     *  @param  hdesc    handler description "[ename.]hdesc[ value]"
     *  @param  context  optional element context
     *  @param  errh     optional error handler
     *  @return  0 on success, -EINVAL on failure
     *
     *  Equivalent to
     *  @link reset(HandlerCall*&, const String&, int, Element*, ErrorHandler*) reset@endlink(@a hcall, @a hdesc, OP_WRITE, @a context, @a errh). */
    static inline int reset_write(HandlerCall *&hcall, const String &hdesc,
				  const Element *context, ErrorHandler *errh = 0);

    /** @brief  Create and initialize a read HandlerCall from @a hdesc.
     *  @param  hcall  stores the HandlerCall result
     *  @param  e      relevant element, if any
     *  @param  hname  handler name
     *  @param  value  write handler value
     *  @param  errh   optional error handler
     *  @return  0 on success, -EINVAL on failure
     *
     *  Equivalent to
     *  @link reset(HandlerCall*&, Element*, const String&, const String&, int, ErrorHandler*) reset@endlink(@a hcall, @a e, @a hname, @ value, OP_WRITE, @a context, @a errh). */
    static inline int reset_write(HandlerCall *&hcall,
				  Element *e, const String &hname,
				  const String &value = String(),
				  ErrorHandler *errh = 0);


    /** @brief  Return the Element corresponding to this HandlerCall.
     *
     *  Returns null if invalid.  A global handler may return some
     *  Router::root_element() or null. */
    Element *element() const {
	return _e;
    }

    /** @brief  Return the Handler corresponding to this HandlerCall.
     *
     *  Returns Handler::blank_handler() if invalid. */
    const Handler *handler() const {
	return _h;
    }

    /** @brief  Return the write handler value and/or read handler parameters.
     *
     *  Returns the empty string if invalid. */
    const String &value() const	{
	return initialized() ? _value : String::make_empty();
    }

    /** @brief  Sets the write handler value and/or read handler parameters.
     *  @param  value  new value and/or parameters
     *
     *  Does nothing if invalid. */
    void set_value(const String &value) {
	if (initialized())
	    _value = value;
    }

    /** @brief  Return a String that will parse into an equivalent HandlerCall.
     *
     *  Will work even if the HandlerCall has not been initialized. */
    String unparse() const;

    /** @brief  Make this HandlerCall empty.
     *
     *  Subsequent attempts to read, write, or initialize the HandlerCall will
     *  fail. */
    void clear() {
	_e = 0;
	_h = Handler::blank_handler();
	_value = String();
    }


    /** @cond never */
    enum { CHECK_READ = OP_READ, CHECK_WRITE = OP_WRITE };
    /** @endcond never */

  private:

    Element *_e;
    const Handler *_h;
    String _value;

    int parse(int flags, Element*, ErrorHandler*);
    int assign(Element*, const String&, const String&, int flags, ErrorHandler*);

};

inline int
HandlerCall::reset_read(HandlerCall*& hcall, const String& hdesc, const Element* context, ErrorHandler* errh)
{
    return reset(hcall, hdesc, OP_READ, context, errh);
}

inline int
HandlerCall::reset_write(HandlerCall*& hcall, const String& hdesc, const Element* context, ErrorHandler* errh)
{
    return reset(hcall, hdesc, OP_WRITE, context, errh);
}

inline int
HandlerCall::reset_read(HandlerCall*& hcall, Element* e, const String& hname, ErrorHandler* errh)
{
    return reset(hcall, e, hname, String(), OP_READ, errh);
}

inline int
HandlerCall::reset_write(HandlerCall*& hcall, Element* e, const String& hname, const String& value, ErrorHandler* errh)
{
    return reset(hcall, e, hname, value, OP_WRITE, errh);
}

inline int
HandlerCall::initialize_read(const Element* context, ErrorHandler* errh)
{
    return initialize(OP_READ, context, errh);
}

inline int
HandlerCall::initialize_write(const Element* context, ErrorHandler* errh)
{
    return initialize(OP_WRITE, context, errh);
}

inline String
HandlerCall::call_read(ErrorHandler *errh) const
{
    return _h->call_read(_e, _value, errh);
}

inline int
HandlerCall::call_write(ErrorHandler *errh) const
{
    return _h->call_write(_value, _e, errh);
}

String cp_expand(const String &str, const VariableExpander &env, bool expand_quote);

inline int
HandlerCall::call_write(const VariableExpander &scope, ErrorHandler *errh) const
{
    return _h->call_write(cp_expand(_value, scope, false), _e, errh);
}

inline int
HandlerCall::call_write(const String &value_ext, ErrorHandler *errh) const
{
    if (_value && value_ext)
	return _h->call_write(_value + " " + value_ext, _e, errh);
    else
	return _h->call_write(_value ? _value : value_ext, _e, errh);
}

/** @brief  Call a write handler specified by element and handler name.
 *  @param  e      relevant element, if any
 *  @param  hname  handler name
 *  @param  errh   optional error handler
 *  @return  handler result, or -EINVAL on error
 *
 *  Searches for a write handler named @a hname on element @a e.  If the
 *  handler exists, calls it (with empty write value) and returns the result.
 *  If @a errh is nonnull, then errors, such as a missing handler or a
 *  read-only handler, are reported there.  If @a e is some router's @link
 *  Router::root_element() root element@endlink, calls the global write
 *  handler named @a hname on that router. */
inline int
HandlerCall::call_write(Element *e, const String &hname, ErrorHandler *errh)
{
    return call_write(e, hname, String(), errh);
}

CLICK_ENDDECLS
#endif