shibsp::SessionInitiator Class Referenceabstract

Pluggable runtime functionality that handles initiating sessions. More...

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

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

## Public Member Functions

virtual const std::set< std::string > & | getSupportedOptions () const
| Indicates the set of optional settings supported by the handler. More...
virtual std::pair< bool, long > | run (SPRequest &request, std::string &entityID, bool isHandler=true) const =0
| Executes an incoming request. More...
std::pair< bool, long > | run (SPRequest &request, bool isHandler=true) const
| Executes handler functionality as an incoming request. More...
const char * | remap (const char *src, xmltooling::logging::Category &log) const
| Remap a name (or return it unchanged). More...
const char * | getType () const
| Returns the "type" of the Handler plugin. More...
void | generateMetadata (opensaml::saml2md::SPSSODescriptor &role, const char *handlerURL) const
| Generates and/or modifies metadata reflecting the Handler. More...
void | doGenerateMetadata (opensaml::saml2md::SPSSODescriptor &role, const char *handlerURL) const
| Generates RequestInitiator metadata when instructed. More...
const char * | getEventType () const
| Get the type of event, as input to error handling in response to errors raised by this handler. More...
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. More...
virtual std::pair< bool, long > | run (SPRequest &request, bool isHandler=true) const =0
| Executes handler functionality as an incoming request. More...
virtual void | generateMetadata (opensaml::saml2md::SPSSODescriptor &role, const char *handlerURL) const
| Generates and/or modifies metadata reflecting the Handler. More...
virtual const char * | getType () const
| Returns the "type" of the Handler plugin. More...
virtual const char * | getEventType () const
| Get the type of event, as input to error handling in response to errors raised by this handler. More...
Public Member Functions inherited from shibsp::PropertySet
virtual const PropertySet * | getParent () const =0
| Returns parent of this PropertySet, if any. More...
virtual void | setParent (const PropertySet *parent)=0
| Establishes a "parent" PropertySet to supply inherited settings. More...
virtual std::pair< bool, bool > | getBool (const char *name, const char *ns=nullptr) const =0
| Returns a boolean-valued property. More...
virtual std::pair< bool, const char * > | getString (const char *name, const char *ns=nullptr) const =0
| Returns a string-valued property. More...
virtual std::pair< bool, const XMLCh * > | getXMLString (const char *name, const char *ns=nullptr) const =0
| Returns a Unicode string-valued property. More...
virtual std::pair< bool, unsigned int > | getUnsignedInt (const char *name, const char *ns=nullptr) const =0
| Returns an unsigned integer-valued property. More...
virtual std::pair< bool, int > | getInt (const char *name, const char *ns=nullptr) const =0
| Returns an integer-valued property. More...
virtual const PropertySet * | getPropertySet (const char *name, const char *ns=shibspconstants::ASCII_SHIBSPCONFIG_NS) const =0
| Returns a nested property set. More...
virtual const xercesc::DOMElement * | getElement () const =0
| Returns a DOM element representing the property container, if any. More...
Public Member Functions inherited from shibsp::DOMPropertySet::Remapper
virtual | ~Remapper ()
| Destructor.
virtual const char * | remap (const char *src, xmltooling::logging::Category &log) const =0
| Remap a name (or return it unchanged). More...

## Protected Member Functions

bool | checkCompatibility (SPRequest &request, bool isHandler) const
| Examines the request and applicable settings to determine whether the handler is able to support the request. More...
virtual AuthnRequestEvent * | newAuthnRequestEvent (const Application &application, const xmltooling::HTTPRequest *request=nullptr) const
| Creates a new AuthnRequestEvent for the event log. More...
Protected Member Functions inherited from shibsp::Handler
virtual void | log (SPRequest::SPLogLevel level, const std::string &msg) const
| Log using handler's specific logging object. More...
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. More...
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. More...
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. More...
Protected Member Functions inherited from shibsp::DOMPropertySet::Remapper
| Remapper ()
| Constructor.

## Protected Attributes

std::set< std::string > | m_supportedOptions
| Set of optional settings supported by handler.

## Friends

void | registerSessionInitiators ()
| Registers SessionInitiator implementations.

## Detailed Description

Pluggable runtime functionality that handles initiating sessions.

By default, SessionInitiators look for an entityID on the incoming request and pass control to the specialized run method.

## Member Function Documentation

## checkCompatibility()

bool shibsp::SessionInitiator::checkCompatibility | ( | SPRequest & | request,
|  | bool | isHandler
| ) |  | const

protected

Examines the request and applicable settings to determine whether the handler is able to support the request.

If the handler is within a chain, the method will return false, otherwise an exception will be raised.

Parameters

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

Returns
  true iff the request appears to be compatible

## doGenerateMetadata()

void shibsp::SessionInitiator::doGenerateMetadata | ( | opensaml::saml2md::SPSSODescriptor & | role,
|  | const char * | handlerURL
| ) |  | const

Generates RequestInitiator metadata when instructed.

Allows subclasses to decide whether it's appropriate to do so instead of requiring them to override the method to stop it.

Parameters

  role | role object to inject metadata into
  handlerURL | base of endpoint to generate metadata with

## generateMetadata()

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

## getEventType()

const char * shibsp::SessionInitiator::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 from shibsp::Handler.

## getSupportedOptions()

virtual const std::set< std::string > & shibsp::SessionInitiator::getSupportedOptions | ( |  | ) | const

virtual

Indicates the set of optional settings supported by the handler.

Returns
  a set of the optional settings supported

## getType()

const char * shibsp::SessionInitiator::getType | ( |  | ) | const

virtual

Returns the "type" of the Handler plugin.

Returns
  a Handler type

Reimplemented from shibsp::Handler.

## newAuthnRequestEvent()

virtual AuthnRequestEvent * shibsp::SessionInitiator::newAuthnRequestEvent | ( | const Application & | application,
|  | const xmltooling::HTTPRequest * | request = `nullptr`
| ) |  | const

protected virtual

Creates a new AuthnRequestEvent for the event log.

Parameters

  application | the Application associated with the event
  request | the HTTP client request associated with the event, or nullptr

Returns
  a fresh AuthnRequestEvent, prepopulated by the input parameters, or nullptr if an error occurs

## remap()

const char * shibsp::SessionInitiator::remap | ( | const char * | src,
|  | xmltooling::logging::Category & | log
| ) |  | const

virtual

Remap a name (or return it unchanged).

Parameters

  src | original name
  log | logger to use

Returns
  the name to use

Implements shibsp::DOMPropertySet::Remapper.

## run() [1/2]

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

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

Implements shibsp::Handler.

## run() [2/2]

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

pure virtual

Executes an incoming request.

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

Parameters

  request | SP request context
  entityID | the name of an IdP to request a session from, if known
  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

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

- shibsp/handler/SessionInitiator.h