shibsp::AbstractHandler Class Reference

Base class for handlers based on a DOMPropertySet. More...

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

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

## Protected Types

enum | PropertySourceTypes { HANDLER_PROPERTY_REQUEST = 1 , HANDLER_PROPERTY_MAP = 2 , HANDLER_PROPERTY_FIXED = 4 , HANDLER_PROPERTY_ALL = 255 }
| Bitmask of property sources to read from (request query parameter, request mapper, fixed handler property).

## Protected Member Functions

| AbstractHandler (const xercesc::DOMElement *e, xmltooling::logging::Category &log, xercesc::DOMNodeFilter *filter=nullptr, const Remapper *remapper=nullptr)
| Constructor.
void | log (SPRequest::SPLogLevel level, const std::string &msg) const
| Log using handler's specific logging object.
virtual void | checkError (const xmltooling::XMLObject *response, const opensaml::saml2md::RoleDescriptor *role=nullptr) const
| Examines a protocol response message for errors and raises an annotated exception if an error is found.
void | fillStatus (opensaml::saml2p::StatusResponseType &response, const XMLCh *code, const XMLCh *subcode=nullptr, const char *msg=nullptr) const
| Prepares Status information in a SAML 2.0 response.
long | sendMessage (const opensaml::MessageEncoder &encoder, xmltooling::XMLObject *msg, const char *relayState, const char *destination, const opensaml::saml2md::RoleDescriptor *role, const Application &application, xmltooling::HTTPResponse &httpResponse, const char *defaultSigningProperty) const
| Encodes and sends SAML 2.0 message, optionally signing it in the process.
virtual void | preservePostData (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response, const char *relayState) const
| Implements a mechanism to preserve form post data.
virtual DDF | recoverPostData (const Application &application, const xmltooling::HTTPRequest &request, xmltooling::HTTPResponse &response, const char *relayState) const
| Implements storage service and cookie mechanism to recover PostData.
virtual long | sendPostResponse (const Application &application, xmltooling::HTTPResponse &response, const char *url, DDF &postData) const
| Post a redirect response with post data.
std::pair< bool, bool > | getBool (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
| Returns a boolean-valued property.
std::pair< bool, const char * > | getString (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
| Returns a string-valued property.
std::pair< bool, unsigned int > | getUnsignedInt (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
| Returns an unsigned integer-valued property.
std::pair< bool, int > | getInt (const char *name, const xmltooling::HTTPRequest &request, unsigned int type=HANDLER_PROPERTY_ALL) const
| Returns an integer-valued property.
std::pair< bool, bool > | getBool (const char *name, const char *ns=nullptr) const
| Returns a boolean-valued property.
std::pair< bool, const char * > | getString (const char *name, const char *ns=nullptr) const
| Returns a string-valued property.
std::pair< bool, unsigned int > | getUnsignedInt (const char *name, const char *ns=nullptr) const
| Returns an unsigned integer-valued property.
std::pair< bool, int > | getInt (const char *name, const char *ns=nullptr) const
| Returns an integer-valued property.
Protected Member Functions inherited from shibsp::Handler
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.
Protected Member Functions inherited from shibsp::DOMPropertySet
bool | setProperty (const char *name, const char *val, const char *ns=nullptr)
| Post-load injection of a property, for use by subclasses.

## Protected Attributes

xmltooling::logging::Category & | m_log
| Logging object.

## Additional Inherited Members

Public Member Functions inherited from shibsp::Handler
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::DOMPropertySet
const PropertySet * | getParent () const
| Returns parent of this PropertySet, if any.
void | setParent (const PropertySet *parent)
| Establishes a "parent" PropertySet to supply inherited settings.
std::pair< bool, bool > | getBool (const char *name, const char *ns=nullptr) const
| Returns a boolean-valued property.
std::pair< bool, const char * > | getString (const char *name, const char *ns=nullptr) const
| Returns a string-valued property.
std::pair< bool, const XMLCh * > | getXMLString (const char *name, const char *ns=nullptr) const
| Returns a Unicode string-valued property.
std::pair< bool, unsigned int > | getUnsignedInt (const char *name, const char *ns=nullptr) const
| Returns an unsigned integer-valued property.
std::pair< bool, int > | getInt (const char *name, const char *ns=nullptr) const
| Returns an integer-valued property.
const PropertySet * | getPropertySet (const char *name, const char *ns=shibspconstants::ASCII_SHIBSPCONFIG_NS) const
| Returns a nested property set.
const xercesc::DOMElement * | getElement () const
| Returns a DOM element representing the property container, if any.
void | load (const xercesc::DOMElement *e, xmltooling::logging::Category *log=nullptr, xercesc::DOMNodeFilter *filter=nullptr, const Remapper *remapper=nullptr, const xmltooling::QName *unsetter=nullptr)
| Loads the property set from a DOM element.

## Detailed Description

Base class for handlers based on a DOMPropertySet.

## Constructor & Destructor Documentation

## AbstractHandler()

shibsp::AbstractHandler::AbstractHandler | ( | const xercesc::DOMElement * | e,
|  | xmltooling::logging::Category & | log,
|  | xercesc::DOMNodeFilter * | filter = nullptr,
|  | const Remapper * | remapper = nullptr )

protected

Constructor.

Parameters

  e | DOM element to load as property set.
  log | logging category to use
  filter | optional filter controls what child elements to include as nested PropertySets
  remapper | optional property rename mapper for legacy property support

## Member Function Documentation

## checkError()

virtual void shibsp::AbstractHandler::checkError | ( | const xmltooling::XMLObject * | response,
|  | const opensaml::saml2md::RoleDescriptor * | role = nullptr ) const

protected virtual

Examines a protocol response message for errors and raises an annotated exception if an error is found.

The base class version understands SAML 1.x and SAML 2.0 responses.

Parameters

  response | a response message of some known protocol
  role | issuer of message

## fillStatus()

void shibsp::AbstractHandler::fillStatus | ( | opensaml::saml2p::StatusResponseType & | response,
|  | const XMLCh * | code,
|  | const XMLCh * | subcode = nullptr,
|  | const char * | msg = nullptr ) const

protected

Prepares Status information in a SAML 2.0 response.

Parameters

  response | SAML 2.0 response message
  code | SAML status code
  subcode | optional SAML substatus code
  msg | optional message to pass back

## getBool() [1/2]

std::pair< bool, bool > shibsp::DOMPropertySet::getBool | ( | const char * | name,
|  | const char * | ns = nullptr ) const

protected virtual

Returns a boolean-valued property.

Parameters

  name | property name
  ns | property namespace, or nullptr

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

Implements shibsp::PropertySet.

## getBool() [2/2]

std::pair< bool, bool > shibsp::AbstractHandler::getBool | ( | const char * | name,
|  | const xmltooling::HTTPRequest & | request,
|  | unsigned int | type = HANDLER_PROPERTY_ALL ) const

protected

Returns a boolean-valued property.

Parameters

  name | property name
  request | reference to incoming request
  type | bitmask of property sources to use

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

## getInt() [1/2]

std::pair< bool, int > shibsp::DOMPropertySet::getInt | ( | const char * | name,
|  | const char * | ns = nullptr ) const

protected virtual

Returns an integer-valued property.

Parameters

  name | property name
  ns | property namespace, or nullptr

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

Implements shibsp::PropertySet.

## getInt() [2/2]

std::pair< bool, int > shibsp::AbstractHandler::getInt | ( | const char * | name,
|  | const xmltooling::HTTPRequest & | request,
|  | unsigned int | type = HANDLER_PROPERTY_ALL ) const

protected

Returns an integer-valued property.

Parameters

  name | property name
  request | reference to incoming request
  type | bitmask of property sources to use

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

## getString() [1/2]

std::pair< bool, const char * > shibsp::DOMPropertySet::getString | ( | const char * | name,
|  | const char * | ns = nullptr ) const

protected virtual

Returns a string-valued property.

Parameters

  name | property name
  ns | property namespace, or nullptr

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

Implements shibsp::PropertySet.

## getString() [2/2]

std::pair< bool, const char * > shibsp::AbstractHandler::getString | ( | const char * | name,
|  | const xmltooling::HTTPRequest & | request,
|  | unsigned int | type = HANDLER_PROPERTY_ALL ) const

protected

Returns a string-valued property.

Parameters

  name | property name
  request | reference to incoming request
  type | bitmask of property sources to use

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

## getUnsignedInt() [1/2]

std::pair< bool, unsigned int > shibsp::DOMPropertySet::getUnsignedInt | ( | const char * | name,
|  | const char * | ns = nullptr ) const

protected virtual

Returns an unsigned integer-valued property.

Parameters

  name | property name
  ns | property namespace, or nullptr

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

Implements shibsp::PropertySet.

## getUnsignedInt() [2/2]

std::pair< bool, unsigned int > shibsp::AbstractHandler::getUnsignedInt | ( | const char * | name,
|  | const xmltooling::HTTPRequest & | request,
|  | unsigned int | type = HANDLER_PROPERTY_ALL ) const

protected

Returns an unsigned integer-valued property.

Parameters

  name | property name
  request | reference to incoming request
  type | bitmask of property sources to use

Returns
  a pair consisting of a nullptr indicator and the property value iff the indicator is true

## log()

void shibsp::AbstractHandler::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 from shibsp::Handler.

## preservePostData()

virtual void shibsp::AbstractHandler::preservePostData | ( | const Application & | application,
|  | const xmltooling::HTTPRequest & | request,
|  | xmltooling::HTTPResponse & | response,
|  | const char * | relayState ) const

protected virtual

Implements a mechanism to preserve form post data.

Parameters

  application | the associated Application
  request | incoming HTTP request
  response | outgoing HTTP response
  relayState | relay state information attached to current sequence, if any

## recoverPostData()

virtual DDF shibsp::AbstractHandler::recoverPostData | ( | const Application & | application,
|  | const xmltooling::HTTPRequest & | request,
|  | xmltooling::HTTPResponse & | response,
|  | const char * | relayState ) const

protected virtual

Implements storage service and cookie mechanism to recover PostData.

If a supported mechanism can be identified, the return value will be the recovered state information.

Parameters

  application | the associated Application
  request | incoming HTTP request
  response | outgoing HTTP response
  relayState | relay state information attached to current sequence, if any

Returns
  recovered form post data associated with request as a DDF list of string members

## sendMessage()

long shibsp::AbstractHandler::sendMessage | ( | const opensaml::MessageEncoder & | encoder,
|  | xmltooling::XMLObject * | msg,
|  | const char * | relayState,
|  | const char * | destination,
|  | const opensaml::saml2md::RoleDescriptor * | role,
|  | const Application & | application,
|  | xmltooling::HTTPResponse & | httpResponse,
|  | const char * | defaultSigningProperty ) const

protected

Encodes and sends SAML 2.0 message, optionally signing it in the process.

If the method returns, the message MUST NOT be freed by the caller.

Parameters

  encoder | the MessageEncoder to use
  msg | the message to send
  relayState | any RelayState to include with the message
  destination | location to send message, if not a backchannel response
  role | recipient of message, if known
  application | the Application sending the message
  httpResponse | channel for sending message
  defaultSigningProperty | the effective value of the "signing" property if unset

Returns
  the result of sending the message using the encoder

## sendPostResponse()

virtual long shibsp::AbstractHandler::sendPostResponse | ( | const Application & | application,
|  | xmltooling::HTTPResponse & | response,
|  | const char * | url,
|  | DDF & | postData ) const

protected virtual

Post a redirect response with post data.

Parameters

  application | the associated Application
  response | outgoing HTTP response
  url | action url for the form
  postData | list of parameters to load into the form, as DDF string members

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

- shibsp/handler/AbstractHandler.h