From: tokul Date: Sun, 24 Apr 2005 08:44:25 +0000 (+0000) Subject: adding api doc X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=a4b225eeb8120e7102609f38039ee826d1cf5a49;p=squirrelmail.git adding api doc git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@9385 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- diff --git a/plugins/change_password/API b/plugins/change_password/API new file mode 100644 index 00000000..eaf4ef17 --- /dev/null +++ b/plugins/change_password/API @@ -0,0 +1,65 @@ + ****************************** + * Change Password plugin API * + ****************************** + +Document should explain how to create change_password plugin backends and +provide details about plugin structure. + +Plugin uses standard SquirrelMail plugin architecture and implements backends +with two hooks. + +change_password_init hook +------------------------- +change_password_init hook is used to execute some code before displaying +change password form. Plugin can use this hook to check if install has all +required components, or to check if backend is configured correctly, or +display some messages to end user. Maybe some background information about +password security and how to choose good password. If backend detects some +configuration errors that make backend unusable, it can stop execution of the +script with PHP exit() call. + +change_password_dochange hook +----------------------------- +change_password_dochange hook is used when user submits old and new passwords. +Plugin checks if old password matches current session password and checks new +password satisfies requirements set in plugin's configuration. All data is +provided in array submitted via hook. 'username' key contains user's login +name, 'curpw' contains current session password, 'newpw' contains new password. +Function that is attached to plugin should return empty array or array filled +with error messages. If array is empty - plugin assumes that password was +changed and updates current session password. + +common strings +-------------- +Backends can use constants for some error messages. CPW_CURRENT_NOMATCH +constant sets 'Your current password is not correct.' error. CPW_INVALID_PW +constant sets 'Your new password contains invalid characters.' error. + +Recommendations +--------------- +Backend should check, if current password matches stored password. +Internal plugin functions only check if password matches the one that +was used to login into SquirrelMail. Password is validated against IMAP +server and not against used backend. + +Backend should store only default configuration variables that don't +have any information specific to developer's server or these variables +should be set to sane default values. + +Backend's configuration should be controlled with configuration overrides +that are set config.php. It is recommended to use array with +configuration overrides and make sure that array is set to empty value +before loading plugin's configuration file. + +Backend should not use generic function names. It is recommended to use +'cpw_' prefix. + +If backend must load other SquirrelMail functions, it must use SM_PATH +constant in include_once() calls and make sure that SM_PATH is defined +in any case when backend file is loaded. In most cases constant is +already defined, but some unusual use of php files might cause php +warnings, if constant is used inside backend functions and not defined +in backend file. + +Overrides used by backend and backend requirements must be documented +in README file.