[Zope-CVS] CVS: Products/PluggableAuthService/interfaces - authservice.py:1.4

[Tres Seaver]

Update of /cvs-repository/Products/PluggableAuthService/interfaces
In directory cvs.zope.org:/tmp/cvs-serv8352/interfaces

Modified Files:
	authservice.py 
Log Message:
 - Merge 'zc-pas_fix_logout-branch', and release version 1.0.4.


=== Products/PluggableAuthService/interfaces/authservice.py 1.3 => 1.4 ===
--- Products/PluggableAuthService/interfaces/authservice.py:1.3	Thu Aug 12 11:15:54 2004
+++ Products/PluggableAuthService/interfaces/authservice.py	Thu Jan 27 14:00:23 2005
@@ -101,6 +101,92 @@
         o roles is the list of roles the caller 
         """
 
+class IPluggableAuthService( IUserFolder ):
+    
+    """ The full, default contract for the pluggable authentication service.
+    """
+    
+    def searchUsers(**kw):
+    
+        """ Search for users.  Returns a sequence of dicts, each dict 
+        representing a user matching the query, with the keys 
+        'userid','id', 'login', 'title', and 'principal_type', possibly among 
+        others.  'principal_type' is always 'user'.
+        
+        Possible keywords include the following:
+        
+        o exact_match: boolean; forces an exact match on id (unused if id is not
+          part of query)
+        
+        o id: user id
+        
+        o name: user name
+        
+        o max_results: an int (or value castable to int) indicating the maximum
+          number of results the method should return
+        
+        o sort_by: the key in the user dictionary that should be used to sort 
+          the results
+        
+        o login: user login
+        """
+
+    def searchGroups(**kw):
+        """ Search for groups.  Returns a sequence of dicts, each dict 
+        representing a group matching the query, with the keys 
+        'groupid','id', 'title', and 'principal_type', possibly among 
+        others.  'principal_type' is always 'group'.
+        
+        Possible keywords include the following:
+        
+        o exact_match: boolean; forces an exact match on id (unused if id is not
+          part of query)
+        
+        o id: user id
+        
+        o name: user name
+        
+        o max_results: an int (or value castable to int) indicating the maximum
+          number of results the method should return
+        
+        o sort_by: the key in the user dictionary that should be used to sort 
+          the results
+        """
+
+    def searchPrincipals(groups_first=False, **kw):
+        """ Search for principals (users, groups, or both).
+        Returns a sequence of dicts, each dict 
+        representing a principal (group or user) matching the query.  groups
+        will be represented with dictionaries as described in searchGroups,
+        and users as described in searchUsers.  Possible keywords include 
+        exact_match, id, name, max_results, sort_by, and login.
+        """
+
+    def updateCredentials(request, response, login, new_password):
+        """Central updateCredentials method
+
+        This method is needed for cases where the credentials storage and
+        the credentials extraction is handled by different plugins. Example
+        case would be if the CookieAuthHelper is used as a Challenge and
+        Extraction plugin only to take advantage of the login page feature
+        but the credentials are not stored in the CookieAuthHelper cookie
+        but somewhere else, like in a Session.
+        """
+
+    def logout(REQUEST):
+        """Publicly accessible method to log out a usera wrapper
+        around resetCredentials that may implement some policy (the default
+        implementation redirects to HTTP_REFERER)
+        """
+
+    def resetCredentials(self, request, response):
+        """Reset credentials by informing all active resetCredentials plugins
+        """
+
+# The IMutableUserFolder and IEnumerableFolder are not supported out-of-the-box
+# by the pluggable authentication service.  These interfaces describe contracts
+# that other standard Zope user folders implement.
+
 class IMutableUserFolder( Interface ):
 
     """ Specify the interface called out in AccessControl.User.BasicUserFolder