simpleid/extensions/hooks.php - sourcearcade - Gitiles

 <?php

 /**
  *
  * This page lists out all the hooks which are available to SimpleID extensions.
  *
  * When implementing these hooks in your extensions, you should replace the word
  * hook with the name of your extension.
  *
  * @package extensions
  */

 /**
  * Returns an array of type URIs to be included in SimpleID's XRDS document.
  *
  * For example:
  *
  * <code>
  * <?php
  * return array('http://specs.openid.net/extensions/ui/1.0/lang-pref', 'http://specs.openid.net/extensions/ui/1.0/mode/popup');
  * ?>
  * </code>
  *
  * @return array an array of URIs
  * @since 0.7
  */
 function hook_xrds_types() {
 }

 /**
  * Processes an authentication request that is <i>not</i> about an identifier.
  *
  * The OpenID specifications provides a mechanism for extensions to process
  * authentication requests that are not about an identifier.  Authentication requests
  * about identifiers are automatically processed by the {@link simpleid_checkid_identity()}
  * function and the {@link hook_checkid_identity()} hooks.
  *
  * Assertion results are coded within SimpleID as an integer between 127 ({@link CHECKID_OK})
  * and -127 ({@link CHECKID_PROTOCOL_ERROR}).  Positive values indicate a potential
  * positive assertion (subject to various types of user approval), while negative
  * values indicate a irrecoverable negative assertion.
  *
  * This hook should return one of these values.  If the extension is unable to
  * handle this particular type of authentication request, it should return NULL.
  *
  * @param array $request the OpenID request
  * @param bool $immediate true if openid.mode is checkid_immediate
  * @return int a return value from the list of possible values returned by
  * {@link simpleid_checkid_identity()} or NULL
  * @see simpleid_checkid()
  */
 function hook_checkid($request, $immediate) {
 }


 /**
  * Processes an authentication request where the assertion is potentially
  * positive.
  *
  * Assertion results are coded within SimpleID as an integer between 127 ({@link CHECKID_OK})
  * and -127 ({@link CHECKID_PROTOCOL_ERROR}).  Positive values indicate a potential
  * positive assertion (subject to various types of user approval), while negative
  * values indicate a irrecoverable negative assertion.
  *
  * Extensions are able to examine the authentication request to modify change
  * the assertion result from positive to negative.  As SimpleID takes the
  * minimum from the results returned by this hook, extensions are
  * not able to change the assertion result from negative to positive.
  *
  * If the extension is indifferent to the result of the current authentication
  * request (e.g. it cannot understand it), it should return NULL.
  *
  * This hook is not called at all if SimpleID determines that the assertion
  * is negative.
  *
  * @param array $request the OpenID request
  * @param string $identity the identity to be checked against
  * @param bool $immediate true if openid.mode is checkid_immediate
  * @return int a return value from the list of possible values returned by
  * {@link simpleid_checkid_identity()} or NULL
  * @see simpleid_checkid_identity()
  */
 function hook_checkid_identity($request, $identity, $immediate) {
 }

 /**
  * Gets fields and values to be included in the OpenID response.
  *
  * For positive assertions, this hook should assume that all user approvals
  * have been given and return a response array accordingly.  The extension has
  * the opportunity to modify the response what the user has actually approved
  * in the {@link hook_send() send hook}.
  *
  * This hook will need to provide any aliases required.
  *
  * An example:
  *
  * <code>
  * <?php
  * $alias = openid_extension_alias($my_uri);
  * return array(
  *     'openid.ns.' . $alias => $my_uri,
  *     'openid.' . $alias . '.field' => 'value'
  * );
  * ?>
  * </code>
  *
  * @param bool $assertion true if a positive assertion is made, false otherwise
  * @param array $request the OpenID request
  * @return array the fields and values to include
  */
 function hook_response($assertion, $request) {
 }

 /**
  * Gets fields associated with this extension which needs to be signed
  *
  * SimpleID automatically handles signing fields required by the OpenID
  * specification, so only the fields introduced by this extension
  * needed to be returned by this function.
  *
  * The array of fields returned by this function must include any applicable
  * aliases as required.  For example
  *
  * <code>
  * <?php
  * $alias = openid_extension_alias($my_uri);
  * return array($alias . '.field1', $alias . 'field2');
  * ?>
  * </code>
  *
  * @param array $response the OpenID response to sign
  * @return array an array of fields to sign
  */
 function hook_signed_fields($response) {
 }

 /**
  * Determines the format in which assertions are sent, when they are sent via
  * indirect communication.
  *
  * The OpenID specification version 2.0 provides for the sending of assertions
  * via indirect communication.  The original specifications provide that the
  * response should be formatted within the query string.
  *
  * Some extensions to the OpenID specification allows the assertion to be
  * formatted in some other way, e.g. via the fragment.  This hook allows
  * extensions to specify which format the assertion should be sent.
  *
  * If the extension is indifferent regarding the format, it should return
  * null
  *
  * @param string $url the URL of the RP to which the response is to be sent
  * @param array $response the assertion to be sent
  * @return int one of OPENID_RESPONSE_QUERY or OPENID_RESPONSE_FRAGMENT or NULL
  */
 function hook_indirect_response($url, $response) {
 }

 /**
  * Provides additional form items when displaying the relying party consent
  * form
  *
  *
  * @param array $request the OpenID request
  * @param array $response the proposed OpenID response
  * @param array $rp the user's preferences saved with this relying party
  * @return string HTML code to be inserted into the verification form
  * @see simpleid_consent_form()
  * @deprecated Use {@link hook_consent_form()}
  */
 function hook_rp_form($request, $response, $rp) {
 }

 /**
  * Provides additional form items when displaying the relying party consent
  * form
  *
  *
  * @param array $request the OpenID request
  * @param array $response the proposed OpenID response
  * @param array $rp the user's preferences saved with this relying party
  * @return string HTML code to be inserted into the verification form
  * @see simpleid_consent_form()
  * @since 0.8
  */
 function hook_consent_form($request, $response, $rp) {
 }

 /**
  * Processes the relying party consent form.
  *
  * This provides the extension with the opportunity to:
  *
  * - modify the OpenID response based on the user's preferences by editing
  *   $response
  * - save the user's preferences by editing $rp
  *
  * <strong>WARNING</strong> Because this function requires parameters to be
  * passed by reference, this does not work with {@link extension_invoke_all()}.
  *
  * @param array $form_request the data submitted by the user in the relying
  * party verification form
  * @param array &$response pointer to the proposed OpenID response
  * @param array &$rp pointer to the user's preferences saved with this relying party
  * @deprecated Use {@link hook_consent()}
  *
  */
 function hook_send($form_request, &$response, &$rp) {
 }

 /**
  * Processes the relying party verification form.
  *
  * This provides the extension with the opportunity to:
  *
  * - modify the OpenID response based on the user's preferences by editing
  *   $response
  * - save the user's preferences by editing $rp
  *
  * <strong>WARNING</strong> Because this function requires parameters to be
  * passed by reference, this does not work with {@link extension_invoke_all()}.
  *
  * @param array $form_request the data submitted by the user in the relying
  * party verification form
  * @param array &$response pointer to the proposed OpenID response
  * @param array &$rp pointer to the user's preferences saved with this relying party
  * @since 0.8
  *
  */
 function hook_consent($form_request, &$response, &$rp) {
 }

 /**
  * Return any additional items provided by the extension to be appended to the
  * Simpleweb route array.
  *
  * @see simpleweb.inc.php
  * @see simpleid_start()
  * @return array the routes array
  * @since 0.7
  */
 function hook_routes() {
 }

 /**
  * Provides additional form items when displaying the login form
  *
  * @param string $destination he SimpleID location to which the user is directed
  * if login is successful
  * @param string $state the current SimpleID state, if required by the location
  * @see user_login_form()
  */
 function hook_user_login_form($destination, $state) {
 }

 /**
  * Attempts to automatically login using credentials presented by the user agent.
  *
  * This hook is called by the {@link user_auto_login()} function.  The hook
  * should detect any credentials present in the request and return a $user array
  * (loaded using the {@link user_load()} function) if credentials identifying
  * the user is present.
  *
  * If no credentials are present, or the credentials are invalid, this hook
  * should return NULL.
  *
  * @return array the user array, or NULL
  */
 function hook_user_auto_login() {
 }

 /**
  * Verifies a set of credentials for a specified user.
  *
  * A set of credentials comprises:
  *
  * - A user name
  * - Some kind of verifying information, such as a plaintext password, a hashed
  *   password (e.g. digest) or some other kind of identifying information.
  *
  * The user name is passed to this function using the $uid parameter.  The user
  * name may or may not exist.  If the user name does not exist, this function
  * <strong>must</strong> return false.
  *
  * The credentials are supplied as an array using the $credentials parameter.
  * Typically this array will be a subset of the $_POST superglobal passed to the
  * {@link user_login()} function.  Thus it will generally contain the keys 'pass' and
  * 'digest'.
  *
  * This hook must check whether the credentials supplied matches the credentials
  * for the specified user in the store.  If for any reason that credentials
  * do not match, this function <strong>must</strong> return false.
  *
  * @param string $uid the name of the user to verify
  * @param array $credentials the credentials supplied by the browser
  * @return bool whether the credentials supplied matches those for the specified
  * user
  */
 function hook_user_verify_credentials($uid, $credentials) {
 }


 /**
  * Returns additional blocks to be displayed in the user's dashboard.
  *
  * A block is coded as an array in accordance with the specifications set
  * out in {@link page.inc}.
  *
  * This hook should return an <i>array</i> of blocks, i.e. an array of
  * arrays.
  *
  * @see page_dashboard()
  * @return array an array of blocks to add to the user's dashboard
  * @since 0.7
  */
 function hook_page_dashboard() {
 }

 /**
  * Returns additional blocks to be displayed in the user's profile page.
  *
  * A block is coded as an array in accordance with the specifications set
  * out in {@link page.inc}.
  *
  * This hook should return an <i>array</i> of blocks, i.e. an array of
  * arrays.
  *
  * @see page_profile()
  * @return array an array of blocks to add to the user's profile page
  * @since 0.7
  */
 function hook_page_profile() {
 }

 ?>
	<?php

	/**
	*
	* This page lists out all the hooks which are available to SimpleID extensions.
	*
	* When implementing these hooks in your extensions, you should replace the word
	* hook with the name of your extension.
	*
	* @package extensions
	*/

	/**
	* Returns an array of type URIs to be included in SimpleID's XRDS document.
	*
	* For example:
	*
	* <code>
	* <?php
	* return array('http://specs.openid.net/extensions/ui/1.0/lang-pref', 'http://specs.openid.net/extensions/ui/1.0/mode/popup');
	* ?>
	* </code>
	*
	* @return array an array of URIs
	* @since 0.7
	*/
	function hook_xrds_types() {
	}

	/**
	* Processes an authentication request that is <i>not</i> about an identifier.
	*
	* The OpenID specifications provides a mechanism for extensions to process
	* authentication requests that are not about an identifier. Authentication requests
	* about identifiers are automatically processed by the {@link simpleid_checkid_identity()}
	* function and the {@link hook_checkid_identity()} hooks.
	*
	* Assertion results are coded within SimpleID as an integer between 127 ({@link CHECKID_OK})
	* and -127 ({@link CHECKID_PROTOCOL_ERROR}). Positive values indicate a potential
	* positive assertion (subject to various types of user approval), while negative
	* values indicate a irrecoverable negative assertion.
	*
	* This hook should return one of these values. If the extension is unable to
	* handle this particular type of authentication request, it should return NULL.
	*
	* @param array $request the OpenID request
	* @param bool $immediate true if openid.mode is checkid_immediate
	* @return int a return value from the list of possible values returned by
	* {@link simpleid_checkid_identity()} or NULL
	* @see simpleid_checkid()
	*/
	function hook_checkid($request, $immediate) {
	}


	/**
	* Processes an authentication request where the assertion is potentially
	* positive.
	*
	* Assertion results are coded within SimpleID as an integer between 127 ({@link CHECKID_OK})
	* and -127 ({@link CHECKID_PROTOCOL_ERROR}). Positive values indicate a potential
	* positive assertion (subject to various types of user approval), while negative
	* values indicate a irrecoverable negative assertion.
	*
	* Extensions are able to examine the authentication request to modify change
	* the assertion result from positive to negative. As SimpleID takes the
	* minimum from the results returned by this hook, extensions are
	* not able to change the assertion result from negative to positive.
	*
	* If the extension is indifferent to the result of the current authentication
	* request (e.g. it cannot understand it), it should return NULL.
	*
	* This hook is not called at all if SimpleID determines that the assertion
	* is negative.
	*
	* @param array $request the OpenID request
	* @param string $identity the identity to be checked against
	* @param bool $immediate true if openid.mode is checkid_immediate
	* @return int a return value from the list of possible values returned by
	* {@link simpleid_checkid_identity()} or NULL
	* @see simpleid_checkid_identity()
	*/
	function hook_checkid_identity($request, $identity, $immediate) {
	}

	/**
	* Gets fields and values to be included in the OpenID response.
	*
	* For positive assertions, this hook should assume that all user approvals
	* have been given and return a response array accordingly. The extension has
	* the opportunity to modify the response what the user has actually approved
	* in the {@link hook_send() send hook}.
	*
	* This hook will need to provide any aliases required.
	*
	* An example:
	*
	* <code>
	* <?php
	* $alias = openid_extension_alias($my_uri);
	* return array(
	* 'openid.ns.' . $alias => $my_uri,
	* 'openid.' . $alias . '.field' => 'value'
	* );
	* ?>
	* </code>
	*
	* @param bool $assertion true if a positive assertion is made, false otherwise
	* @param array $request the OpenID request
	* @return array the fields and values to include
	*/
	function hook_response($assertion, $request) {
	}

	/**
	* Gets fields associated with this extension which needs to be signed
	*
	* SimpleID automatically handles signing fields required by the OpenID
	* specification, so only the fields introduced by this extension
	* needed to be returned by this function.
	*
	* The array of fields returned by this function must include any applicable
	* aliases as required. For example
	*
	* <code>
	* <?php
	* $alias = openid_extension_alias($my_uri);
	* return array($alias . '.field1', $alias . 'field2');
	* ?>
	* </code>
	*
	* @param array $response the OpenID response to sign
	* @return array an array of fields to sign
	*/
	function hook_signed_fields($response) {
	}

	/**
	* Determines the format in which assertions are sent, when they are sent via
	* indirect communication.
	*
	* The OpenID specification version 2.0 provides for the sending of assertions
	* via indirect communication. The original specifications provide that the
	* response should be formatted within the query string.
	*
	* Some extensions to the OpenID specification allows the assertion to be
	* formatted in some other way, e.g. via the fragment. This hook allows
	* extensions to specify which format the assertion should be sent.
	*
	* If the extension is indifferent regarding the format, it should return
	* null
	*
	* @param string $url the URL of the RP to which the response is to be sent
	* @param array $response the assertion to be sent
	* @return int one of OPENID_RESPONSE_QUERY or OPENID_RESPONSE_FRAGMENT or NULL
	*/
	function hook_indirect_response($url, $response) {
	}

	/**
	* Provides additional form items when displaying the relying party consent
	* form
	*
	*
	* @param array $request the OpenID request
	* @param array $response the proposed OpenID response
	* @param array $rp the user's preferences saved with this relying party
	* @return string HTML code to be inserted into the verification form
	* @see simpleid_consent_form()
	* @deprecated Use {@link hook_consent_form()}
	*/
	function hook_rp_form($request, $response, $rp) {
	}

	/**
	* Provides additional form items when displaying the relying party consent
	* form
	*
	*
	* @param array $request the OpenID request
	* @param array $response the proposed OpenID response
	* @param array $rp the user's preferences saved with this relying party
	* @return string HTML code to be inserted into the verification form
	* @see simpleid_consent_form()
	* @since 0.8
	*/
	function hook_consent_form($request, $response, $rp) {
	}

	/**
	* Processes the relying party consent form.
	*
	* This provides the extension with the opportunity to:
	*
	* - modify the OpenID response based on the user's preferences by editing
	* $response
	* - save the user's preferences by editing $rp
	*
	* <strong>WARNING</strong> Because this function requires parameters to be
	* passed by reference, this does not work with {@link extension_invoke_all()}.
	*
	* @param array $form_request the data submitted by the user in the relying
	* party verification form
	* @param array &$response pointer to the proposed OpenID response
	* @param array &$rp pointer to the user's preferences saved with this relying party
	* @deprecated Use {@link hook_consent()}
	*
	*/
	function hook_send($form_request, &$response, &$rp) {
	}

	/**
	* Processes the relying party verification form.
	*
	* This provides the extension with the opportunity to:
	*
	* - modify the OpenID response based on the user's preferences by editing
	* $response
	* - save the user's preferences by editing $rp
	*
	* <strong>WARNING</strong> Because this function requires parameters to be
	* passed by reference, this does not work with {@link extension_invoke_all()}.
	*
	* @param array $form_request the data submitted by the user in the relying
	* party verification form
	* @param array &$response pointer to the proposed OpenID response
	* @param array &$rp pointer to the user's preferences saved with this relying party
	* @since 0.8
	*
	*/
	function hook_consent($form_request, &$response, &$rp) {
	}

	/**
	* Return any additional items provided by the extension to be appended to the
	* Simpleweb route array.
	*
	* @see simpleweb.inc.php
	* @see simpleid_start()
	* @return array the routes array
	* @since 0.7
	*/
	function hook_routes() {
	}

	/**
	* Provides additional form items when displaying the login form
	*
	* @param string $destination he SimpleID location to which the user is directed
	* if login is successful
	* @param string $state the current SimpleID state, if required by the location
	* @see user_login_form()
	*/
	function hook_user_login_form($destination, $state) {
	}

	/**
	* Attempts to automatically login using credentials presented by the user agent.
	*
	* This hook is called by the {@link user_auto_login()} function. The hook
	* should detect any credentials present in the request and return a $user array
	* (loaded using the {@link user_load()} function) if credentials identifying
	* the user is present.
	*
	* If no credentials are present, or the credentials are invalid, this hook
	* should return NULL.
	*
	* @return array the user array, or NULL
	*/
	function hook_user_auto_login() {
	}

	/**
	* Verifies a set of credentials for a specified user.
	*
	* A set of credentials comprises:
	*
	* - A user name
	* - Some kind of verifying information, such as a plaintext password, a hashed
	* password (e.g. digest) or some other kind of identifying information.
	*
	* The user name is passed to this function using the $uid parameter. The user
	* name may or may not exist. If the user name does not exist, this function
	* <strong>must</strong> return false.
	*
	* The credentials are supplied as an array using the $credentials parameter.
	* Typically this array will be a subset of the $_POST superglobal passed to the
	* {@link user_login()} function. Thus it will generally contain the keys 'pass' and
	* 'digest'.
	*
	* This hook must check whether the credentials supplied matches the credentials
	* for the specified user in the store. If for any reason that credentials
	* do not match, this function <strong>must</strong> return false.
	*
	* @param string $uid the name of the user to verify
	* @param array $credentials the credentials supplied by the browser
	* @return bool whether the credentials supplied matches those for the specified
	* user
	*/
	function hook_user_verify_credentials($uid, $credentials) {
	}



	/**
	* Returns additional blocks to be displayed in the user's dashboard.
	*
	* A block is coded as an array in accordance with the specifications set
	* out in {@link page.inc}.
	*
	* This hook should return an <i>array</i> of blocks, i.e. an array of
	* arrays.
	*
	* @see page_dashboard()
	* @return array an array of blocks to add to the user's dashboard
	* @since 0.7
	*/
	function hook_page_dashboard() {
	}

	/**
	* Returns additional blocks to be displayed in the user's profile page.
	*
	* A block is coded as an array in accordance with the specifications set
	* out in {@link page.inc}.
	*
	* This hook should return an <i>array</i> of blocks, i.e. an array of
	* arrays.
	*
	* @see page_profile()
	* @return array an array of blocks to add to the user's profile page
	* @since 0.7
	*/
	function hook_page_profile() {
	}

	?>