shibsp::Handler Class Referenceabstract

Pluggable runtime functionality that implement protocols and services. More...

`#include <shibsp/handler/Handler.h>`

Inheritance diagram for shibsp::Handler:
[legend]
Collaboration diagram for shibsp::Handler:
[legend]

## Public Member Functions

virtual const XMLCh * | getProtocolFamily () const
| Returns an identifier for the protocol family associated with the handler, if any.
virtual std::pair< bool, long > | run (SPRequest &request, bool isHandler=true) const =0
| Executes handler functionality as an incoming request.
virtual void | generateMetadata (opensaml::saml2md::SPSSODescriptor &role, const char *handlerURL) const
| Generates and/or modifies metadata reflecting the Handler.
virtual const char * | getType () const
| Returns the "type" of the Handler plugin.
virtual const char * | getEventType () const
| Get the type of event, as input to error handling in response to errors raised by this handler.
Public Member Functions inherited from shibsp::PropertySet
virtual const PropertySet * | getParent () const =0
| Returns parent of this PropertySet, if any.
virtual void | setParent (const PropertySet *parent)=0
| Establishes a "parent" PropertySet to supply inherited settings.
virtual std::pair< bool, bool > | getBool (const char *name, const char *ns=nullptr) const =0
| Returns a boolean-valued property.
virtual std::pair< bool, const char * > | getString (const char *name, const char *ns=nullptr) const =0
| Returns a string-valued property.
virtual std::pair< bool, const XMLCh * > | getXMLString (const char *name, const char *ns=nullptr) const =0
| Returns a Unicode string-valued property.
virtual std::pair< bool, unsigned int > | getUnsignedInt (const char *name, const char *ns=nullptr) const =0
| Returns an unsigned integer-valued property.
virtual std::pair< bool, int > | getInt (const char *name, const char *ns=nullptr) const =0
| Returns an integer-valued property.
virtual const PropertySet * | getPropertySet (const char *name, const char *ns=shibspconstants::ASCII_SHIBSPCONFIG_NS) const =0
| Returns a nested property set.
virtual const xercesc::DOMElement * | getElement () const =0
| Returns a DOM element representing the property container, if any.

## Protected Member Functions

virtual void | log (SPRequest::SPLogLevel level, const std::string &msg) const
| Log using handler's specific logging object.
virtual void | cleanRelayState (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response) const
| Prevents unused relay state from building up by cleaning old state from the client.
virtual void | preserveRelayState (const Application &application, xmltooling::HTTPResponse &response, std::string &relayState) const
| Implements various mechanisms to preserve RelayState, such as cookies or StorageService-backed keys.
virtual void | recoverRelayState (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response, std::string &relayState, bool clear=true) const
| Implements various mechanisms to recover RelayState, such as cookies or StorageService-backed keys.

## Detailed Description

Pluggable runtime functionality that implement protocols and services.

## Member Function Documentation

## cleanRelayState()

virtual void shibsp::Handler::cleanRelayState | ( | const Application & | application,
|  | const xmltooling::HTTPRequest & | request,
|  | xmltooling::HTTPResponse & | response
| ) |  | const

protected virtual

Prevents unused relay state from building up by cleaning old state from the client.

Handlers that generate relay state should call this method as a house cleaning step.

Parameters

  application | the associated Application
  request | incoming HTTP request
  response | outgoing HTTP response

## generateMetadata()

virtual void shibsp::Handler::generateMetadata | ( | opensaml::saml2md::SPSSODescriptor & | role,
|  | const char * | handlerURL
| ) |  | const

virtual

Generates and/or modifies metadata reflecting the Handler.

The default implementation does nothing.

Parameters

  role | metadata role to decorate
  handlerURL | base location of handler's endpoint

Reimplemented in shibsp::AssertionConsumerService, and shibsp::SessionInitiator.

## getEventType()

virtual const char * shibsp::Handler::getEventType | ( |  | ) | const

virtual

Get the type of event, as input to error handling in response to errors raised by this handler.

Returns
  an event type for error handling

Reimplemented in shibsp::AssertionConsumerService, shibsp::LogoutHandler, and shibsp::SessionInitiator.

## getProtocolFamily()

virtual const XMLCh * shibsp::Handler::getProtocolFamily | ( |  | ) | const

virtual

Returns an identifier for the protocol family associated with the handler, if any.

Returns
  a protocol identifier, or nullptr

Reimplemented in shibsp::AssertionConsumerService.

## getType()

virtual const char * shibsp::Handler::getType | ( |  | ) | const

virtual

Returns the "type" of the Handler plugin.

Returns
  a Handler type

Reimplemented in shibsp::AssertionConsumerService, shibsp::LogoutInitiator, and shibsp::SessionInitiator.

## log()

virtual void shibsp::Handler::log | ( | SPRequest::SPLogLevel | level,
|  | const std::string & | msg
| ) |  | const

protected virtual

Log using handler's specific logging object.

Parameters

  level | logging level
  msg | message to log

Reimplemented in shibsp::AbstractHandler.

## preserveRelayState()

virtual void shibsp::Handler::preserveRelayState | ( | const Application & | application,
|  | xmltooling::HTTPResponse & | response,
|  | std::string & | relayState
| ) |  | const

protected virtual

Implements various mechanisms to preserve RelayState, such as cookies or StorageService-backed keys.

If a supported mechanism can be identified, the input parameter will be replaced with a suitable state key.

Parameters

  application | the associated Application
  response | outgoing HTTP response
  relayState | RelayState token to supply with message

## recoverRelayState()

virtual void shibsp::Handler::recoverRelayState | ( | const Application & | application,
|  | const xmltooling::HTTPRequest & | request,
|  | xmltooling::HTTPResponse & | response,
|  | std::string & | relayState,
|  | bool | clear = `true`
| ) |  | const

protected virtual

Implements various mechanisms to recover RelayState, such as cookies or StorageService-backed keys.

If a supported mechanism can be identified, the input parameter will be replaced with the recovered state information.

Parameters

  application | the associated Application
  request | incoming HTTP request
  response | outgoing HTTP response
  relayState | RelayState token supplied with message
  clear | true iff the token state should be cleared

## run()

virtual std::pair< bool, long > shibsp::Handler::run | ( | SPRequest & | request,
|  | bool | isHandler = `true`
| ) |  | const

pure virtual

Executes handler functionality as an incoming request.

Handlers can be run either directly by incoming web requests or indirectly/implicitly during other SP processing.

Parameters

  request | SP request context
  isHandler | true iff executing in the context of a direct handler invocation

Returns
  a pair containing a "request completed" indicator and a server-specific response code

Implemented in shibsp::AssertionConsumerService, shibsp::LogoutHandler, shibsp::SecuredHandler, and shibsp::SessionInitiator.

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

- shibsp/handler/Handler.h